Modifying Multivalued Properties

Applies to: Exchange Server 2010

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.

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 property 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.

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.

Set-RecipientFilterConfig -BlockedRecipients chris@contoso.com

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

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 is 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.

To modify multivalued properties, you must understand the following concepts:

• User-Defined Variables
• Pipelining
• Syntax
• Working with Command Output

Append a Value to a Multivalued Property

Appending a value to a multivalued property is simple. It just takes a few extra steps. Again, assume that the BlockedRecipients property contains the values that are listed in the first section of this topic.

First, you have to retrieve the object that you want to modify and assign it to a variable. For example, use the following command to assign the RecipientFilterConfig object to the variable $Example.

$Example = Get-RecipientFilterConfig

If you run the command $Example | Format-List BlockedRecipients, the following is returned.

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

Next, you have to add the value that you want to append to the BlockedRecipients property on the object that's stored in the variable $Example. Be aware that this step only adds the value to the object that's stored in the variable. To add chris@contoso.com to the BlockedRecipients property on the object that's stored in the variable $Example, run the following command.

$Example.BlockedRecipients += "chris@contoso.com"

If you run the command $Example | Format-List BlockedRecipients again, the following is returned.

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

As you can see, the SMTP address chris@contoso.com has been added to the list of values that are stored in the BlockedRecipients property.

Finally, you have to save the object that's stored in $Example by using the following command.

Set-RecipientFilterConfig -BlockedRecipients $Example.BlockedRecipients

Now, when you run the Get-RecipientFilterConfig | Format-List BlockedRecipients command, you will see that the SMTP address chris@contoso.com has been added to the server.

Appending Multiple Values to a Multivalued Property

If you want to append many values at the same time to a multivalued property, perform the same step as described earlier. When you specify the values that you want to append, separate the values by using commas as in the following example.

$Example.BlockedRecipients += "user1@contoso.com", "user2@contoso.com", "user3@contoso.com"

After you've specified the values that you want to add, use the Set-RecipientFilterConfig cmdlet to save the object.

Remove a Value from a Multivalued Property

You may want to remove only one value from a multivalued property instead of removing all the values at the same time. Removing a value from a multivalued property is like appending a value. However, unlike appending values, you must remove values one at a time. Again, assume that the BlockedRecipients property contains the values that are listed in the first section of this topic.

First, you must assign the object that you want to modify to a variable, as in the following example.

$Example = Get-RecipientFilterConfig

Then, run the following command, which specifies the exact value that you want to remove.

$Example.BlockedRecipients -= "david@contoso.com"

Finally, save the object that's stored in the variable as follows.

Set-RecipientFilterConfig -BlockedRecipients $Example.BlockedRecipients

Examples of Appending Values to Multivalued Properties

The following Shell procedures are examples of how to append values to some of the multivalued properties that are available on various objects in Microsoft Exchange Server 2010, and then display the updated results.

This example appends an SMTP address to the mailbox Kim Akers.

$Mailbox = Get-Mailbox "Kim Akers"
$Mailbox.EmailAddresses += "kim@contoso.com"
Set-Mailbox "Kim Akers" -EmailAddresses $Mailbox.EmailAddresses

This example retrieves the name and e-mail addresses for the updated mailbox Kim Akers.

Get-Mailbox "Kim Akers" | Format-List Name, EmailAddresses

This example appends additional delivery status notification (DSN) codes on the GenerateCopyOfDSNFor property.

$DsnList = Get-TransportConfig
$DsnList.GenerateCopyOfDSNFor += "5.4.7", "5.7.1", "5.7.2"
Set-TransportConfig -GenerateCopyOfDSNFor $DsnList.GenerateCopyOfDSNFor

This example retrieves the DSN codes, including the added codes.

Get-TransportConfig | Format-List GenerateCopyOfDSNFor

Examples of Removing Values from Multivalued Properties

The following procedures are examples of how to remove values from some of the multivalued properties that are available on various objects in Exchange 2010, and then display the updated results.

This example removes the device ID of an enabled Microsoft Exchange ActiveSync device from a Client Access server mailbox.

$CasDevice = Get-CasMailbox "David Simpson"
$CasDevice.ActiveSyncAllowedDeviceIDs -= "4B9207650054767AD0AEE83A414BCD7F"
Set-CasMailbox "David Simpson" -ActiveSyncAllowedDeviceIDs $CasDevice.ActiveSyncAllowedDeviceIDs

This example retrieves the updated list of device IDs.

Get-CasMailbox "David Simpson" | Format-List Name, ActiveSyncAllowedDeviceIDs

This example removes a mailbox from the list of mailboxes that are granted "send on behalf of" permissions on the distribution group Sales Group.

$DistributionGroup = Get-DistributionGroup "Sales Group"
$DistributionGroup.GrantSendOnBehalfTo -= (Get-Mailbox "Christine Koch").Identity
Set-DistributionGroup "Sales Group" -GrantSendOnBehalfTo $DistributionGroup.GrantSendOnBehalfTo

This example retrieves the updated list of mailboxes that are granted "send on behalf of" permissions on the distribution group Sales Group.

Get-DistributionGroup "Sales Group" | Format-List Name, GrantSendOnBehalfTo