Understanding Cmdlet Extension Agents

 

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

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 agent to 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 agent respects the value provided by the other agents.

Warning

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.

Warning

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

 © 2010 Microsoft Corporation. All rights reserved.