Wednesday, August 10, 2011

ScriptingAgentConfig.xml Syntax

The Scripting Agent for Exchange 2010 SP1 uses ScriptingAgentConfig.xml to define additional content used when running specified cmdlets. This file needs to be located in in C:\Program Files\Microsoft\Exchange\v14\Bin\CmdletExtensionAgents. This file uses the following generic format:
Line 1 <?xml version “1.0” encoding=”utf-8”?>
Line 2 <Configuration version=”1.0”>
Line 3 <Feature Name=”YouPickName” Cmdlets=”CsvList”>
Line 4 <ApiCall Name=”NameOfAPI”>
Line 5 The script goes here
Line 6 </ApiCall>
Line 7 </Feature>
Line 8 </Configuration>
Description of example:
  • Line 1 defines the version of XML . This line is always here and always the same.
  • Line 2 opens the configuration tag. The configuration tag exists once in the file.
  • Line 3 opens the feature tag. There can be multiple feature tags in the file. Each feature tag has a name that you define. The name needs to be unique, but can be anything that makes sense to you. Each feature tag also has a list of cmdlets that it applies to. If the feature applies to multiple cmdlets the they are separated by commas.
  • Line 4 opens the ApiCall tag. This defines how/when the following script is used. The name defines the ApiCall that is used. Valid values are: ProvisionDefaultProperties, UpdateAffectedIConfigurable, Validate, and OnComplete. Multiple ApiCall tags can be used in each feature tag.
  • Line 5 the script within the ApiCall tag is run when defined by the ApiCall name used. This is a PowerShell script that is typically short, but can be complex. It can include ligic structures such as if statements. It can also use data in the ProvisioningHandler and IConfigurable objects. These objects contain information about the request.
  • Lines 6-8 close the open tags started in Lines 2-4. Notice that these tags are nested and the last tag to be opened is the first tag to be closed.
You can also use the <Common> </Common> tag to define functions that are used by scripts within multiple feature tags. The common tag is placed inside the configuration tag at the same level as the feature tag, but not inside the feature tag.

I suggest liberally using comments within your xml file to document what each section is doing. For a single line the # symbol designates a comment. Block quotes are done by placing content within <!--   -->.

I will be posting some specific examples with explanations. You can also view the example file that comes with Exchange 2010 sp1 at C:\Program Files\Microsoft\Exchange Server\V14\Bin\CmdletExtensionAgents\ScriptingAgentConfig.xml.sample.

No comments:

Post a Comment