Understanding the Scripting Agent

  • Article

 

Applies to: Exchange Server 2010 SP2, Exchange Server 2010 SP3

You can use the Scripting Agent cmdlet extension agent in Microsoft Exchange Server 2010 to insert your own scripting logic into the execution of Exchange cmdlets. Using the Scripting Agent, you can add conditions, override values, and set up reporting.

Warning

When you enable the Scripting Agent cmdlet extension agent, the agent is called every time a cmdlet is run on a server running Exchange 2010. This includes not only cmdlets run directly by you in the Exchange Management Shell, but also cmdlets run by Exchange services, the Exchange Management Console (EMC), and the Exchange Control Panel (ECP). We strongly recommend that you test your scripts and any changes you make to the configuration file, before you copy your updated configuration file to your Exchange 2010 servers and enable the Scripting Agent cmdlet extension agent.

Every time an Exchange cmdlet is run, the cmdlet calls the Scripting Agent cmdlet extension agent. When this agent is called, the cmdlet checks whether any scripts are configured to be called by the cmdlet. If a script should be run for a cmdlet, the cmdlet tries to call any APIs defined in the script. The following APIs are available and are called in the following order:

  1. ProvisionDefaultProperties   This API can be used to set values of properties on objects when they're created. When you set a value, that value is returned to the cmdlet, and the cmdlet sets the value on the property. You can fill in values on properties if the user didn't specify a value, or you can override the value specified by the user. This API respects the values set by higher priority agents. The Scripting Agent cmdlet extension agent won't overwrite the values set by higher priority agents.

  2. UpdateAffectedIConfigurable   This API can be used to set values of properties on objects after all other processing has been completed, but the Validate API hasn't yet been called. This API respects the values set by higher priority agents. The Scripting Agent cmdlet extension agent won't overwrite the values set by higher priority agents.

  3. Validate   This API can be used to validate the values on an object's properties that are about to be set by the cmdlet. This API is called just before a cmdlet writes any data. You can configure validation checks that allow a cmdlet to either succeed or fail. If a cmdlet passes the validation checks in this API, the cmdlet is allowed to write the data. If the cmdlet fails the validation checks, it returns any errors defined in this API.

  4. OnComplete   This API is used after all cmdlet processing is complete. It can be used to perform post-processing tasks, such as writing data to an external database.

Note

The Scripting Agent cmdlet extension agent isn't called when cmdlets with the Get verb are run. Also, the agent doesn't run on Exchange servers running the Edge Transport server role because that server role doesn't support cmdlet extension agents.

The Scripting Agent is one of several cmdlet extension agents. For more information about cmdlet extension agents, see Understanding Cmdlet Extension Agents.

Contents

Scripting Agent Configuration File

Enable the Scripting Agent

Agent Priority

Scripting Agent Configuration File

The Scripting Agent configuration file contains all of the scripts that you want the Scripting Agent to run. Scripts in the configuration file are contained within XML tags that define the beginning and end of the script and various input parameters required to pass data to the script. Scripts are written using Windows PowerShell syntax. The configuration file is an XML file that uses the elements or attributes in the following table.

Element Attribute Description

Configuration

Not applicable

This element contains all of the scripts that the Scripting Agent cmdlet extension agent can run. The Feature tag is a child of this tag.

There is only one Configuration tag in the configuration file.

Feature

Not applicable

This element contains a set of scripts that relate to a feature. Each script, defined in the ApiCall child tag, extends a specific part of the cmdlet execution pipeline. This tag contains the Name and Cmdlets attributes.

There can be multiple Feature tags under the Configuration tag.

 

Name

This attribute contains the name of the feature. Use this attribute to help identify which feature is extended by the scripts contained within the tag.

 

Cmdlets

This attribute contains a list of the Exchange cmdlets that the set of scripts in this feature extension will be used by. You can specify multiple cmdlets by separating each cmdlet with a comma.

ApiCall

Not applicable

This element contains scripts that can extend a part of the cmdlet execution pipeline. Each script is defined by the API call name in the cmdlet execution pipeline it's extending. The following are the API names that can be extended:

  • ProvisionDefaultProperties

  • UpdateAffectedIConfigurable

  • Validate

  • OnComplete

 

Name

This attribute includes the name of the API call that's extending the cmdlet execution pipeline.

Common

Not applicable

This element contains functions that can be used by any script in the configuration file.

Every Exchange 2010 server includes the file ScriptingAgentConfig.xml.sample in the <installation path>\V14\Bin\CmdletExtensionAgents folder. This file must be renamed to ScriptingAgentConfig.xml on every Exchange 2010 server if you enable the Scripting Agent cmdlet extension agent. The sample configuration file contains sample scripts that you can use to help you understand how to add scripts to the configuration file.

After you add a script to the configuration file, or if you make a change to the configuration file, you must update the file on every Exchange 2010 server in your organization. This must be done to make sure that each server contains an up-to-date version of the scripts that the Scripting Agent cmdlet extension agent runs.

Some characters typically used in scripts also have a special meaning in XML. To use these characters in your script, use escape sequences. For example, the following characters use an escape sequence:

  • Instead of a greater than sign ( > ), use &gt;

  • Instead of a less than sign ( < ), use $lt;

  • Instead of an ampersand ( & ), use &amp;

Return to top

Enable the Scripting Agent

The Scripting Agent cmdlet extension agent is disabled by default. When you enable the Scripting Agent, the agent is enabled for the entire Exchange 2010 organization. Before you enable the Scripting Agent, verify that the Scripting Agent configuration file has been properly renamed and updated with your scripts on every Exchange 2010 server. You will receive an error message each time a cmdlet runs if you don't rename the configuration file correctly.

To enable the Scripting Agent, you must do the following:

  1. Rename the ScriptingAgentConfig.xml.sample file in <installation path>\V14\Bin\CmdletExtensionAgents to ScriptingAgentConfig.xml on every Exchange 2010 server in your organization.

    Note

    You can copy the configuration file from one Exchange 2010 server to other Exchange 2010 servers. Be sure you update the configuration file you want to copy before you copy it.

  2. Add your script to the renamed configuration file on every Exchange 2010 server in your organization.

  3. Enable the Scripting Agent cmdlet extension agent. For more information about enabling cmdlet extension agents, see Enable a Cmdlet Extension Agent.

Return to top

Agent Priority

By default, the Scripting Agent cmdlet extension agent runs after every other agent, with the exception of the Admin Audit Log agent. If you want a script you created to replace an existing agent, you must either disable the other agent or change the priority of either agent so that the Scripting Agent cmdlet extension agent runs first. For more information about how to disable or change the priority of agents, see the following topics:

Return to top

 © 2010 Microsoft Corporation. All rights reserved.