Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2
Topic Last Modified: 2010-08-25
Cmdlet extension agents are components in Microsoft Exchange Server 2010 called by Exchange 2010 cmdlets when the cmdlets run. As the name implies, cmdlet extension agents extend the capabilities of the cmdlets that call them by assisting in processing data or performing additional actions based on the requirements of the cmdlet. Cmdlet extension agents are available on any server role except the Edge Transport server role.
Agents can modify, replace, or extend functionality of Exchange Management Shell cmdlets. An agent can provide a value for a required parameter that isn't provided on a command, override a value provided by a user, perform other actions outside of the cmdlet workflow while a cmdlet runs, and more.
For example, the New-Mailbox cmdlet accepts the
Database parameter that specifies the mailbox database in
which to create a new mailbox. In Exchange Server 2007, if you
don't specify the Database parameter when you run the
New-Mailbox cmdlet, the command fails. With Exchange 2010,
the New-Mailbox cmdlet calls the Mailbox Resources
Management agent when the cmdlet runs. If the
Database parameter isn't specified, the Mailbox
Resources Management agent automatically determines a
suitable mailbox database on which to create the new mailbox and
inserts that value into the Database parameter.
Cmdlet extension agents can only be called by Exchange 2010 cmdlets. Exchange 2007 cmdlets and cmdlets provided by other Microsoft and third-party products can't call cmdlet extension agents. Scripts also can't call cmdlet extension agents directly. However, if scripts contain Exchange 2010 cmdlets, those cmdlets continue to call the cmdlet extension agents.
Looking for management tasks related to cmdlet extension agents? See Managing Cmdlet Extension Agents.
Agent Priority
The priority of an agent determines the order in which the agent is called while a cmdlet runs. An agent that has a higher priority, closer to 0, is called first. The priority of an agent becomes important when two or more agents attempt to set the value of the same property. The highest priority agent that attempts to set a property value succeeds, and all subsequent attempts to set the same property by lower priority agents are ignored. For example, if the Name property on an object is modified by an agent with a priority of 3 and another agent with a priority of 6 modifies the same object, the modification made by the agent with a priority of 6 is ignored.
If you want to use the Scripting agent to
set the value of properties that might be set by other, higher
priority agents, you have the following options:
- Disable the agent that currently sets the property.
- Set the
Scripting agentto a priority higher than the existing agent you want to replace.
- Keep the priorities of the agents the same and make sure that
the script that runs under the
Scripting agentrespects the value provided by the other agents.
 Caution: |
|---|
| Changing the priority or replacing the functionality of a built-in agent is an advanced operation. Be sure that you completely understand the changes you're making. |
For more information about changing the priority of an agent, see Change the Priority of a Cmdlet Extension Agent.
Built-in Agents
Exchange 2010 includes several agents that can be called when a cmdlet runs. The following table lists the agents, their order, and whether the agents are enabled by default. You can't add or remove agents to or from a server running Exchange 2010. You can, however, use the Scripting agent to run Microsoft Windows PowerShell scripts to extend the functionality of the cmdlets that use it. For more information about the Scripting agent, see Understanding the Scripting Agent.
You can enable or disable agents or change the priority of the agents if you want to replace the functionality of a particular agent with functionality you provide in a custom script that you call using the Scripting agent.
The configuration for agents is stored at the
organization level. When you enable or disable an agent, or set its
priority, you set that agent configuration across every server in
the organization. The exception is adding scripts to the
Scripting agent. You must update the scripts on each
server individually. For more information about configuring scripts
for use with the Scripting agent, see Understanding the
Scripting Agent.
| Caution: |
|---|
| Changing the priority of agents, or enabling or disabling agents, can cause unintended effects if you don't completely understand what each agent does and how they interact with Exchange cmdlets. Before you change the configuration of any agent, be sure you fully understand the changes and results you want and that you verify that your custom script will work as intended. |
Exchange 2010 cmdlet extension agents
| Agent name | Priority | Enabled by default |
|---|---|---|
|
Admin Audit Log Agent |
255 |
True |
|
Scripting Agent |
6 |
False |
|
OAB Resources Management Agent |
5 |
True |
|
Provisioning Policy Agent |
4 |
True |
|
Mailbox Creation Time Agent |
3 |
True |
|
Mailbox Resources Management Agent |
2 |
True |
|
Rus Agent |
1 |
True |
|
Query Base DN Agent |
0 |
True |