Back in Exchange 2010 Microsoft Introduced the Cmdlet Extension agents. These agents perform various task such as User Mailbox distribution when a mailbox is provisioned. to see a list of the Extension agents, run the following Get-CmdletExtensionAgent |FT Name,Priority,Enabled .
This will output the agents there priority and if they are enabled or not. In the rest of this post I will be covering the Scripting Agent. the scripting Agent allow you to run Exchange cmdlets as a mailbox (user, shared, or resource) or Distribution list are created or enabled via the Shell or EAC.
The Scripting Agent utilizes an XML document named ScriptingAgentConfig.xml located on Each Exchange Servers (C:\Program Files\Microsoft\Exchange Server\v15\Bin\CmdletExtensionAgents) to preform the exchange related tasks you desire. Microsoft provides a sample file name ScriptingAgentConfig.xml.sample which I recommend that you review.
The XML contains several sections or nodes allowing you to define what cmdlets you want to trigger on and within what API.
the following API calls are exposed: (https://technet.microsoft.com/en-us/library/dd335054(v=exchg.80).aspx)
- 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 invoked. 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.
- $readOnlyIConfigurable.
- $provisioningHandler.UserSpecifiedParameters["ParameterName"]
When it comes time to deploy your Completed script, you will need to deploy it to each exchange server. the file must be copied to C:\Program Files\Microsoft\Exchange Server\v15\Bin\CmdletExtensionAgents. I would recommend if you have more then 2 exchange server you download Paul Cunninghams PushScriptingAgentConfig.ps1 it can be found here
once you have deployed your custom ScriptingAgentConfig.xml file you need to enable the scripting agent. to do so run the following Cmdlet:
Enable-CmdletExtensionAgent -Identity "Scripting Agent"
If you need to disable the scripting agent run the following
Disable-CmdletExtensionAgent -Identity "Scripting Agent"
A Few Gotchas
1. I have seen that during upgrades such as CU or rollups that setup will complain if the scripting agent is enabled. So I would recommend that during maintenance or when introducing a new version of exchange that you disable the scripting agent.
Below is an example ScriptingAgentConfig.xml I created to setup a user mailbox once its been created using either new-mailbox or the enable-mailbox cmdlets .
