Automating tasks with the scripting agent_Microsoft Exchange 2010 PowerShell Cookbook-QQ阅读男生玄幻网

上QQ阅读APP看书，第一时间看更新

Automating tasks with the scripting agent

Exchange 2010 introduced the concept of cmdlet extension agents to extend the functionality of the Exchange Management Tools. The scripting extension agent can be used to trigger custom commands as changes are being made by administrators from the management console or the shell. In this recipe, we'll take a look at how to use the scripting agent to automate a task in the Exchange Management Shell.

Getting ready

To complete the steps in the recipe, you'll need to create an XML file. You can simply use Notepad or any XML editor of your choice.

How to do it...

Let's say that you need to enable single item recovery for every mailbox that gets created in your organization. By default, single item recovery is disabled when you create a mailbox. To automatically enable single item recovery for each mailbox as it is created, add the following code to a new file:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration version="1.0">
  <Feature Name="MailboxProvisioning" Cmdlets="New-Mailbox">
    <ApiCall Name="OnComplete">
      if($succeeded) {
        $mailbox = $provisioningHandler.UserSpecifiedParameters["Name"]
        Set-Mailbox $mailbox -SingleItemRecoveryEnabled $true
      }
    </ApiCall>
  </Feature>
</Configuration>

Next, save the file as ScriptingAgentConfig.xml on the Exchange server in the <install path>\V14\Bin\CmdletExtensionAgents directory.
Finally, you need to enable the scripting agent using the following command:
```
Enable-CmdletExtensionAgent "Scripting Agent"
```

If you have multiple Exchange servers in your environment, copy the ScriptingAgentConfig.xml file to each server into the CmdletExtentionAgents directory as described previously.

How it works...

When the scripting agent is enabled, it is called every time a cmdlet is run in your Exchange environment. This includes cmdlets run from within the shell or any of the graphical management tools.

You can see from the code that, in this example, we're using the OnComplete API, which runs immediately after the cmdlet has been completed. Using the Feature tag, we've specified that this block of code should only be executed upon completion of the New-Mailbox cmdlet.

After the New-Mailbox cmdlet has completed, we check the built-in $succedded variable to ensure the command was successful. If so, we retrieve the value that was used with the -Name parameter and store the result in the $mailbox variable. This value is then used to specify the identity when running the Set-Mailbox cmdlet to enable single item recovery.

There's more...

You can add multiple scripts to the XML file if needed by defining multiple Feature tags under the configuration tag. Each block of code within the Feature tag should have an ApiCall tag as shown in the previous example.

The state of the scripting agent is an organization-wide setting. If you enable the scripting agent, it is important that the ScriptingAgentConfig.xml is copied to every Exchange server in your organization.

Using multiple cmdlets with the OnComplete API

Let's take a look at another example. Imagine that, in addition to enabling single-item recovery for all newly-created mailboxes, we also want to disable the ActiveSync protocol for each mailbox. This means that, in addition to calling the Set-Mailbox cmdlet to enable single item recovery, we'll also need to call the Set-CASMailbox cmdlet to disable ActiveSync. Also, mailboxes can be created using both the New-Mailbox and Enable-Mailbox cmdlets . Since we'd like our custom settings to be applied regardless of how the mailbox is created, we can use the following code in our XML file:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration version="1.0">
  <Feature Name="Mailboxes" Cmdlets="new-mailbox,enable-mailbox">
    <ApiCall Name="OnComplete">
      if($succeeded) {
        $id = $provisioningHandler.UserSpecifiedParameters["Alias"]
        Set-Mailbox $id -SingleItemRecoveryEnabled $true
        Set-CASMailbox $id -ActiveSyncEnabled $false
      }
    </ApiCall>
  </Feature>
</Configuration>

This code is similar to our previous example, except in this version we've specified that our custom code will be called when both the New-Mailbox and Enable-Mailbox cmdlets are used. The code in the ApiCall tag captures the Alias of the mailbox and then uses the Set-Mailbox and Set-CASMailbox to modify the settings as required.

There are multiple scripting agent APIs that can be used to extend the Exchange Management Shell functionality even further. For examples on how to use these APIs, reference the ScriptingAgentConfig.xml.sample file in the <install path>\V14\Bin\CmdletExtensionAgents folder.