Sdílet prostřednictvím

Modifying Multivalued Properties

  • Článek

Microsoft Exchange Server 2007 will reach end of support on April 11, 2017. To stay supported, you will need to upgrade. For more information, see Resources to help you upgrade your Office 2007 servers and clients.

 

Applies to: Exchange Server 2007, Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3

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

What is a Multivalued Property?

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.

How is Modifying a Multivalued Property Different?

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 Simple Mail Transfer Protocol (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.

Note

Some cmdlets, such as Set-TransportRule, do not 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.

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

How to Append a Value to a Multivalued Property

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

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 is stored in the variable $Example. Be aware that this step only adds the value to the object that is stored in the variable. To add chris@contoso.com to the BlockedRecipients property on the object that is 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 is 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 have specified the values that you want to add, use the Set-RecipientFilterConfig cmdlet to save the object.

Note

Some cmdlets don't let you append multiple values at the same time.

How to Remove a Value from a Multivalued Property

Chances are that 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.

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 is stored in the variable as follows:

Set-RecipientFilterConfig -BlockedRecipients $Example.BlockedRecipients

Examples of Appending Values to Multivalued Properties

The following Exchange Management 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 2007.

To append an SMTP address to a mailbox

  1. Run the following commands:

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

  2. Run the following command to view the updated mailbox:

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

To append additional delivery status notification (DSN) codes on the GenerateCopyOfDSNFor property

  1. Run the following commands:

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

  2. Run the following command to view the updated DSN 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 2007.

To remove the device ID of an enabled Exchange ActiveSync device from a Client Access server (CAS) mailbox

  1. Run the following commands

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

  2. Run the following command to view the updated CAS mailbox:

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

To remove a mailbox from the list of mailboxes that are granted "send on behalf of" permissions on a distribution group

  1. Run the following command:

    $DistributionGroup = Get-DistributionGroup "Sales Group"
$DistributionGroup.GrantSendOnBehalfTo -= (Get-Maibox "Christine Hughes").Identity
Set-DistributionGroup "Sales Group" -GrantSendOnBehalfTo $DistributionGroup.GrantSendOnBehalfTo

  2. Run the following command to view the updated distribution group

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

For More Information

For more information about the features discussed in this topic, see the following topics: