Multivalued Properties in Exchange 2010

This blog article is based on a wiki page that I created for our Exchange 2010 SP2 Technology Adoption Program (TAP) private wiki site. This new syntax will make it into the Modifying Multivalued Properties topic when SP2 ships. Since the syntax also works with SP1 (the update just happens to be timed with SP2), I wanted to get this out. I hope you find it useful!

If you work with the Exchange Management Shell, you’re probably aware that some parameters on cmdlets can accept multiple values. These parameters are associated with “multivalued properties". If you’ve worked with multivalued properties, you’re probably also aware that it’s very easy to accidentally overwrite these properties when you attempt to add a value to them. That’s because the behavior in the shell is generally to overwrite the existing value in a property, rather than add to it. For example, assume that you have a distribution group, and you’ve configured David, Chris, and Susan to be able to manage them:

 Get-DistributionGroup Sales | Format-List ManagedBy

ManagedBy : {Contoso.com/Users/david, Contoso.com/Users/susan, Contoso.com/Users/chris}

And now you want to allow a fourth user, Gary, to manage the distribution list. So you go and run the following command:

 Set-DistributionGroup Sales -ManagedBy Gary

To your dismay, this is what you see when you re-run the Get-DistributionGroup cmdlet from above:

ManagedBy : {Contoso.com/Users/gary}

When you ran the Set-DistributionGroup cmdlet, the value that you specified with the ManagedBy parameter overwrote the existing value of that property. You probably didn’t want to do that. Previously there was a way to get around this by storing values in a temporary variable, adding a value to that, and then hefting all of that back to the actual property (see Modifying Multivalued Properties for all the gory details). Removing values from a multivalued property was just as cumbersome.

In Microsoft Exchange Server 2010 Service Pack 1, however, there’s a much easier way to add and remove values from a multivalued property. With this new syntax, you simply specify the syntax, along with the value or values to add or remove to or from the property, as a value on the parameter when you run the cmdlet. Here’s the new syntax:

To add a value:

 @{Add="<value1>", "<value2>", "<value3>"}

To remove a value:

 @{Remove="<value1>", "<value2>", "<value3>"}

The syntax is then specified as a parameter value on a cmdlet:

 Set-SomeCmdlet -Parameter @{Add="<value1>", "<value2>", "<value3>"}

If we use the example with the distribution above again and want to add Gary, we would use the following command:

 Set-DistributionGroup Sales -ManagedBy @{Add="Gary"}

Now when you run the following command again:

 Get-DistributionGroup Sales | Format-List ManagedBy 

Here’s what you’ll see:

ManagedBy : {Contoso.com/Users/david, Contoso.com/Users/gary, Contoso.com/Users/susan, Contoso.com/Users/chris}

As you can see, Gary’s been added to the ManagedBy property and the other users remain. Now, let’s assume you want to remove David from the ManagedBy property and add Gerald at the same time. You can combine Add and Remove operations in the same command by separating the Add and Remove commands with a semi-colon. Here’s the syntax to use:

 @{Add="<value1>", "<value2>"; Remove="<value1>", "<value2>"}

So to remove David and add Gerald at the same time, you’d use the following command:

 Set-DistributionGroup Sales -ManagedBy @{Remove="David"; Add="Gerald"}

When you run the following command:

 Get-DistributionGroup Sales | Format-List ManagedBy 

You’ll see that David has been removed from the property and Gerald has been added.

Hopefully you’ll agree that this new syntax makes it much simpler to manage multi-valued properties. Of course, you can continue to replace all the values stored in a multi-valued property by assigning new values directly.