Sunday, November 30, 2014

Exchange cmdlet Extension Agents

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.

image

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 = 60



   8:                  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 1



  14:                         continue # with the for loop



  15:                     } 



  16:                     else



  17:                     {



  18:                         # Enable SingleItemRecovery



  19:                         Set-Mailbox $mbx -SingleItemRecoveryEnabled $true



  20:                         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).Name



  23:                         $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 $true



  51:                         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).Name



  54:                         $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 yyyyMM



  71:             $LogFile = 'C:\temp\scriptingAgent_' + $t + '.log'



  72:  



  73:             # $text = text to be written to logfile



  74:             $t = Get-Date -Format yyyyMMdd:HHmmss



  75:             $text = '[' + $t + '] ' + $text



  76:             $text >> $LogFile



  77:         } #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.