Cmdlet extension agents are components within Exchange 2013 that are invoked when Exchange cmdlet’s run. Agens can do additional action when Exchange cmdlet are run such as modify,add functionality or validate input parameters.
Several agents exists out of the box when installing Exchange 2013. Run Get-CmdletExtensionAgent to see. note that they can be disabled/enabled and have a priority.
The one agent we can manipulate with ease is the “Scripting Agent”. It runs Exchange cmdlets located in an XML file, $exbin\CmdletExtensionAgents\ScriptingAgentConfig.xml. This file does not exists by default but there is a sample file in the same directory which contains examples.
The most common scenario I would think of is to run some cmdlet after a cmdlet is run. for example. when you create a mailbox you can also run some cmdlet to set some additional parameters on the mailbox. My example here is to enable SingleItemRecovery and also change de default permission on calendar to LimitedDetails for everyone to see the subject of calendar objects.
1: <?xml version="1.0" encoding="utf-8" ?>
2: <Configuration version="1.0">
3: <Feature Name="MailboxProvisioning" Cmdlets="Enable-Mailbox">
4: <ApiCall Name="OnComplete">
5: if($succeeded) {
6: $ErrorActionPreference = "SilentlyContinue"
7: $MaxTime = 608: for ($LoopVar = 0;$LoopVar -lt $MaxTime;$LoopVar++) {
9: if($provisioningHandler.UserSpecifiedParameters["Identity"] -ne $null) {
10: $user = Get-user $provisioningHandler.UserSpecifiedParameters["Identity"]
11: $mbx = Get-Mailbox $user.DistinguishedName 12: If (-not($mbx)) { 13: Start-Sleep 114: continue # with the for loop
15: } 16: else
17: {18: # Enable SingleItemRecovery
19: Set-Mailbox $mbx -SingleItemRecoveryEnabled $true20: WriteToLog (' enabled singleitemrecovery on ' + [string]$mbx.alias)
21: # set sharing permissoin on calendar folder
22: $CalendarName = (Get-MailboxFolderStatistics -Identity $mbx.alias -FolderScope Calendar | Select-Object -First 1).Name23: $folderID = $MBX.alias + ':\' + $CalendarName
24: Set-MailboxFolderPermission -Identity $folderID -User 'Default' -AccessRights 'LimitedDetails'
25: WriteToLog (' set sharing permission on calenderfolder on ' + [string]$mbx.alias)
26: break # out of for loop 27: } 28: } 29: } 30: $ErrorActionPreference = "Continue" 31: } 32: </ApiCall> 33: </Feature> 34: <Feature Name="MailboxProvisioning" Cmdlets="New-Mailbox"> 35: <ApiCall Name="OnComplete"> 36: if($succeeded) { 37: $ErrorActionPreference = "SilentlyContinue" 38: $MaxTime = 60 39: for ($LoopVar = 0;$LoopVar -lt $MaxTime;$LoopVar++) { 40: if($provisioningHandler.UserSpecifiedParameters["Name"] -ne $null) { 41: $user = Get-user $provisioningHandler.UserSpecifiedParameters["Name"] 42: $mbx = Get-Mailbox $user.DistinguishedName 43: If (-not($mbx)) { 44: Start-Sleep 1 45: continue # with the for loop 46: } 47: else 48: { 49: # Enable SingleItemRecovery 50: Set-Mailbox $mbx -SingleItemRecoveryEnabled $true51: WriteToLog (' enabled singleitemrecovery on ' + [string]$mbx.alias)
52: # set sharing permissoin on calendar folder 53: $CalendarName = (Get-MailboxFolderStatistics -Identity $mbx.alias -FolderScope Calendar | Select-Object -First 1).Name54: $folderID = $MBX.alias + ':\' + $CalendarName
55: Set-MailboxFolderPermission -Identity $folderID -User 'Default' -AccessRights 'LimitedDetails'
56: WriteToLog (' set sharing permission on calenderfolder on ' + [string]$mbx.alias)
57: break # out of for loop 58: } 59: } 60: } 61: $ErrorActionPreference = "Continue" 62: } 63: </ApiCall> 64: </Feature> 65: 66: <Common> 67: <!-- common functions --> 68: 69: function WriteToLog {param ([string]$text) 70: $t = Get-Date -Format yyyyMM71: $LogFile = 'C:\temp\scriptingAgent_' + $t + '.log'
72: 73: # $text = text to be written to logfile 74: $t = Get-Date -Format yyyyMMdd:HHmmss75: $text = '[' + $t + '] ' + $text
76: $text >> $LogFile77: } #end function LogToFile
78: </Common> 79: 80: </Configuration>the XML elements to notice here is Feature, ApiCall and Common. Feature hold the Cmdlet attribute , here you put in the Exchange cmdlet you want to do something with. ApiCall you enter what you want to do, I use OnComplete which will trigger after the cmdlet in feature element.
Both Feature and ApiCall can be in the XML file multiple times.
You can see in my example here (line 3 and 4) that the *Scripting Agent” will run a script block after Enable-mailbox is completed. I start by doing a trick to allow the Active Directory replication have a chance to finish before we actually do something. line 19 to 25 is where the stuff I actually want to happen after Enable-Mailbox.
Line 34,35 is when you run New-Mailbox. I could have have the New-Mailbox and Enable-Mailbox together but separated them because in they use different anchor to the mailbox (line 10 and 41).
The common section in the XML file contains a small powershell function to write some information to a text file.
Other things I hear customer do is to apply some policies to mailboxes and disable things such as pop/imap.
So now that you have a XML file to work with you can simply add your own logic when some Exchange cmdlet is run and not only to when provisioning mailboxes, it could be for DL’s or whatever your imagination can come up with.
Of course you must enable “Scripting Agent” with
Enable-CmdletExtensionAgent “Scripting Agent” and also copy your XML file to every Exchange server in your environment.
