Applies to: Exchange Server 2007 SP3, Exchange Server 2007 SP2, Exchange Server 2007 SP1
Topic Last Modified: 2007-07-27

Use the Set-TransportRule cmdlet to modify an existing transport rule that the Transport Rules agent uses when it processes e-mail messages that pass through a computer that has the Hub Transport server role or the Edge Transport server role installed.

Syntax

Set-TransportRule -Identity <RuleIdParameter> [-Actions <TransportRuleAction[]>] [-Comments <String>] [-Conditions <TransportRulePredicate[]>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-Exceptions <TransportRulePredicate[]>] [-Name <String>] [-Priority <Int32>] [-WhatIf [<SwitchParameter>]]
Set-TransportRule [-Actions <TransportRuleAction[]>] [-Comments <String>] [-Conditions <TransportRulePredicate[]>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-Exceptions <TransportRulePredicate[]>] [-Instance <Rule>] [-Name <String>] [-Priority <Int32>] [-WhatIf [<SwitchParameter>]]

Parameters

Parameter Required Type Description

Identity

Required

Microsoft.Exchange.MessagingPolicies.Rules.Tasks.RuleIdParameter

Use this parameter to specify the GUID of the transport rule or the rule name that was configured by the administrator when the rule was created.

Actions

Optional

Microsoft.Exchange.MessagingPolicies.Rules.Tasks.TransportRuleAction[]

Use this parameter to specify the actions that the transport rule applies to the e-mail message if all conditions are met and if no exceptions are met. At least one action must be specified for each rule.

Comments

Optional

System.String

Use this parameter to add informative comments to the transport rule, such as what the rule is used for or how it has changed over time. The length of the comment cannot exceed 512 characters.

Conditions

Optional

Microsoft.Exchange.MessagingPolicies.Rules.Tasks.TransportRulePredicate[]

Use this parameter to specify the conditions that are applied by the transport rule to e-mail messages that are submitted to the Transport Rules agent. If you do not configure a condition on a rule, the rule will be applied to all messages if no exceptions are matched.

Confirm

Optional

System.Management.Automation.SwitchParameter

The Confirm parameter causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm parameter.

DomainController

Optional

Microsoft.Exchange.Data.Fqdn

To specify the fully qualified domain name (FQDN) of the domain controller that retrieves data from Active Directory, include the DomainController parameter in the command. The DomainController parameter is not supported on computers that run the Edge Transport server role. The Edge Transport server role writes only to the local Active Directory Application Mode (ADAM) instance.

Exceptions

Optional

Microsoft.Exchange.MessagingPolicies.Rules.Tasks.TransportRulePredicate[]

Use this parameter to specify the exceptions that the transport rule applies to the e-mail message. If a message matches any exception, no actions that are specified on this rule are applied to the message.

Instance

Optional

Microsoft.Exchange.MessagingPolicies.Rules.Tasks.Rule

Use this parameter to pass an entire object to the command to be processed. This parameter is mainly used in scripts where an entire object must be passed to the command.

Name

Optional

System.String

Use this parameter to specify the display name of the transport rule to be created. The length of the name cannot exceed 64 characters.

Priority

Optional

System.Int32

Use this parameter to specify the order in which the transport rules are applied. If you modify the priority of the rule, the position of the rule in the rule list changes to match the priority that you specified, and the Transport Rules agent increments all rules with a higher priority value. Rules with a lower priority value are processed first. The value of this parameter must be greater than or equal to 0.

WhatIf

Optional

System.Management.Automation.SwitchParameter

The WhatIf parameter instructs the command to simulate the actions that it would take on the object. By using the WhatIf parameter, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf parameter.

Detailed Description

The Set-TransportRule cmdlet lets you modify an existing transport rule that the Transport Rules agent uses when it processes e-mail messages that pass through a Hub Transport server or an Edge Transport server.

Each condition and exception must use a supported transport rule predicate. Each predicate consists of at least one condition, and the values that the condition tests against.

For a list of supported transport rule predicates, see Transport Rule Predicates.

Each action must use a supported transport rule action. Each action consists of at least one action, and the values that the action uses to perform its task.

For a list of supported rule actions, see Transport Rule Actions.

For detailed information about how to modify an existing transport rule, see How to Modify a Transport Rule.

For information about the Transport Rules agent, see Overview of Transport Rules.

To run the Set-TransportRule cmdlet, the account you use must be delegated the following:

  • Exchange Organization Administrator role

To run the Set-TransportRule cmdlet on a computer that has the Edge Transport server role installed, you must log on by using an account that is a member of the local Administrators group on that computer.

For more information about permissions, delegating roles, and the rights that are required to administer Microsoft Exchange Server 2007, see Permission Considerations.

Input Types

Return Types

Errors

Error Description

 

 

Exceptions

Exceptions Description

 

 

Example

The following is a complete example that shows how to modify an existing transport rule on a Hub Transport server. This example shows how you can modify the conditions on a transport rule without affecting the exceptions or actions on the same rule.

This rule will be modified to apply the following condition:

  • from member of distribution list   The value for this condition is the distribution group "Sales Group".

Copy Code
$Condition = Get-TransportRulePredicate FromMemberOf
$Condition.Addresses = @((Get-DistributionGroup "Sales Group"))
Set-TransportRule "Sales-Brokerage Wall" -Condition @($condition)