Cmdlet Extension Agents & XML Case Sensitivity

Ex2013 LogoOccasionally, I get requests to come to the aid of a fellow IT professional (I seldomly get requests to come to the aid of fair maidens. Oh, well). This weekend I responded to one of those distress calls by someone who couldn’t get his Cmdlet Extension Agent to work. This post is a quick heads-up for the collective memory of IT Professionals as it took me quiet a bit of screen staring to spot the issue.

For those unfamiliar with Cmdlet Extension Agents, they are modules which allow you to enhance or customize the behavior of cmdlets in Exchange. For example, the built-in Mailbox Resources Management agent is responsible for picking the database when creating new mailboxes when a database hasn’t been specified. By means of the Script Agent and an XML file named ScriptingAgentConfig.xml containing PowerShell code fragments, you can enhance and tailor Exchange cmdlets to your own needs. For those interested in Cmdlet Extension Agents, I did two earlier articles on Cmdlet Extension Agents, here and here.

The code provided was a simple agent to enhance New-Mailbox with enabling SingleItemRecovery after the mailbox was created:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration version="1.0">    
        <Feature Name="Mailbox Provisioning" cmdlets="new-mailbox">
         <ApiCall Name="OnComplete">
             if($succeeded) {
                $newmailbox = $provisioningHandler.UserSpecifiedParameters["Name"]
                set-mailbox $newmailbox -SingleItemRecoveryEnabled $true
                }
        </ApiCall>
        </Feature>
</Configuration>

The Scripting Agent was enabled using Enable-CmdletExtensionAgent. Yet, for some reason after creating a new mailbox, SingleItemRecoveryEnabled wasn’t enabled. Running New-Mailbox in Verbose mode showed that the Scripting Agent did not come into play:

Capture1Now know that debugging and troubleshooting Cmdlet Extension Agents can be an unpleasant task since you put PowerShell code in XML files and there is no way to easily perform simple tests except running the Cmdlet you’re customizing or developing script fragments in an external PowerShell script and copy/paste it in the Scripting Agent XML file when you think it’s ready for and want to perform some final tests.

I didn’t immediately spot it, so to see if the problem was actually in the XML I picked the example of my 2nd article on Cmdlet Extension Agents and I compared it with the non-working XML using WinMerge (which by the way is an excellent tool to compare code or plain texts):

WinMergeIt took some time to discover why the Scripting Agent wouldn’t pick up the XML and it can be easily overlooked. The culprit in underlined in red: the C of the Cmdlets attribute in the Feature tag should be uppercase. Doh! This case sensitivity is perhaps not a primary suspect by Windows folks, as mostly we don’t have to worry about it and things “just work”, but in the case of XML it is essential. The XML standard prescribes that element names (<Feature> .. </Feature>) and attribute names (<Feature Cmdlets=..>) are case-sensitive entitling the Scripting Agent to be strict.

2 thoughts on “Cmdlet Extension Agents & XML Case Sensitivity

  1. Pingback: The UC Architects » Episode 33: Managing, Migrating, and Moving

    • Nothing wrong, but it’s more flexibile and can be used in more scenarios:
      – You can’t scope Search-Mailbox to message class
      – Search-Mailbox not available in Ex2007 (as in this scenario)
      – No control over soft/hard delete
      – Requires EMS
      – DeleteContent switch requires additional permissions

      Also, this EWS script can be extended, like filtering or excluding specific mailboxes (not possible with Search-Mailbox, a request for this script but didn’t have time yet).

      I’d always opt for the proper tools (or cmdlets) of the trade 🙂

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s