Applies to: Exchange Server 2010 SP3, Exchange Server 2010 SP2

Topic Last Modified: 2012-07-23

This topic explains how to use the Exchange Management Shell to add values to and remove values from a multivalued property on an object.

Multivalued Property Overview

A multivalued property is a property that can contain more than one value. For example, the BlockedRecipients property on the RecipientFilterConfig object can accept multiple recipient addresses as in the following examples:

  • john@contoso.com

  • kim@northwindtraders.com

  • david@adatum.com

Because the BlockedRecipients property can accept more than one value, it's called a multivalued property.

For more information about objects, see Structured Data.

Modifying a Multivalued Property vs. Modifying a Property That Accepts Only a Single Value

How you modify a multivalued property is slightly different from how you modify a property that accepts only one value. When you modify a property that accepts only a single value, you can assign a value directly to it, as in the following command.

Copy Code
Set-TransportConfig -MaxSendSize 12MB

When you use this command to provide a new value to the MaxSendSize property, the stored value is overwritten. This isn't a problem with properties that accept only one value. However, it becomes a problem with multivalued properties. For example, assume that the BlockedRecipients property on the RecipientFilterConfig object is configured to have the three values that are listed in the previous section. When you run the command Get-RecipientFilterConfig | Format-List BlockedRecipients, the following is displayed.

Copy Code
BlockedRecipients : {david@adatum.com, kim@northwindtraders.com, john@contoso.com}

Now assume that you've received a request to add a new SMTP address to the blocked recipients list. You run the following command to add the new SMTP address.

Copy Code
Set-RecipientFilterConfig -BlockedRecipients chris@contoso.com

When you run the Get-RecipientFilterConfig | Format-List BlockedRecipients command again, you will see the following.

Copy Code
BlockedRecipients : {chris@contoso.com}

This isn't what you expected. You wanted to add the new SMTP address to the existing list of blocked recipients, but instead the existing list of blocked recipients was overwritten by the new SMTP address. This unintended result exemplifies how modifying a multivalued property differs from modifying a property that accepts only a single value. When you modify a multivalued property, you must make sure that you append or remove values instead of overwriting the whole list of values. The following sections show you how to do exactly that.

Note:
Some cmdlets, such as Set-TransportRule, don't support modifying properties on objects in the manner described in this topic. For more information about how to add values to and remove values from the multivalued properties of these cmdlets, see the topics for those cmdlets, such as Set-TransportRule.

Modifying Multivalued Properties

Modifying multivalued properties is similar to modifying single-valued properties. You just need to add some additional syntax to tell the Shell that you want to add or remove values to or from the multivalued property rather than replace everything that’s stored in the property. The syntax is included, along with the value or values to add or remove to or from the property, as a value on a parameter when you run a cmdlet. The following table shows the syntax that you need to add to a parameter on a cmdlet to modify multivalued properties.

Multivalue property syntax

Action Syntax

Add one or more values to a multivalued property

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

Remove one or more values from a multivalued property

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

The syntax that you choose from the Multivalue property syntax table is specified as a parameter value on a cmdlet. For example, the following command adds multiple values to a multivalued property:

Copy Code
Set-ExampleCmdlet -Parameter @{Add="Red", "Blue", "Green"}

When you use this syntax, the values that you specify are added or removed from the list of values already present on the property. Taking the BlockedRecipients example earlier in this topic, we can now add chris@contoso.com without overwriting the rest of the values on this property by using the following command:

Copy Code
Set-RecipientFilterConfig -BlockedRecipients @{Add="chris@contoso.com"}

If you wanted to remove david@adatum.com from the list of values, you would use this command:

Copy Code
Set-RecipientFilterConfig -BlockedRecipients @{Remove="david@adatum.com"}

More complex combinations can be used, such as adding or removing values to and from a property at the same time. To do so, insert a semicolon (; ) between Add and Remove actions. For example:

Copy Code
Set-RecipientFilterConfig -BlockedRecipients @{Add="carter@contoso.com", "sam@northwindtraders.com", "brian@adatum.com"; Remove="john@contoso.com"}

If we use the Get-RecipientFilterConfig | Format-List BlockedRecipients command again, we can see that the email addresses for Carter, Sam, and Brian have been added while the address for John has been removed.

Copy Code
BlockedRecipients : {brian@adatum.com, sam@northwindtraders.com, carter@contoso.com, chris@contoso.com, kim@northwindtraders.com}