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.

Caution:

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:

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.

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.

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.

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.

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:

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:

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.

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

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: