Throttling Policy Associations in Exchange 2010 SP1

[The_Exchange_Team]

Exchange 2010 SP1 introduces two new throttling cmdlets: get-ThrottlingPolicyAssociation and set-ThrottlingPolicyAssociation. In Exchange 2010 RTM, in order to determine which throttling policy was associated with a given user, you would use something like:

Get-Mailbox JohnDoe | fl ThrottlingPolicy

To assign a non-default throttling policy to a user you would call

set-Mailbox JohnDoe -ThrottlingPolicy Foo

One thing that should stand out with these two CMDlets is that policies could only be associated with mailbox accounts. Why would you ever want throttling policies associated with anything else? I'm glad you asked. There are at least two valid scenarios to consider:

Scenario 1 - A machine account: Let's say you write a web site that uses Exchange Impersonation to call into EWS and perform actions on behalf of a user that logged onto your web site. Further assuming that your web site is configured to run as Network Service, the EWS call will come from the *machine* account (such as MyDomain/MyMachine$). When such a call is encountered by EWS, it tries to determine which throttling policy to apply to the machine account. Given that set-Mailbox is not applicable to Active Directory Computer objects, and given that a computer is not *in* any of the organizations defined in the Active Directory, the throttling framework must use the fallback policy for the computer account. Given that the fallback policy is hardcoded within the Exchange binaries, you have no control over reducing or increasing its policy values.

Scenario 2 - A cross forest contact: In cross forest scenarios, you have the option of creating a linked mailbox in the Exchange forest or a linked contact. If an account from user forest A is given Exchange Impersonation rights and needs custom throttling values defined, your only option in Exchange 2010 RTM is to use a linked mailbox so that you can assign a non-default throttling policy using the set-Mailbox cmdlets. When a cross forest account calls into Exchange via EWS, the user is authenticated via the user forest (via the trust), but the Active Directory object that Exchange uses to gather "Exchange" information is contained in the Exchange forest. If that Exchange object is a linked contact, the throttling framework must use the fallback policy to throttle the call, which as mentioned above cannot be modified since it is hardcoded.

To cover these scenarios, we added the get/set-ThrottlingPolicyAssociation cmdlets which operate on "virtual" ThrottlingPolicyAssociation objects. By virtual, I mean that there is no ThrottlingPolicyAssociation class in the Active Directory schema. The association represents the link between some "account" and its throttling policy. And what is an "account"? Well, it could be a mailbox, a computer object or a contact.

So let's see how this works. I created a factious mailbox account for JohnDoe. Let's call get-ThrottlingPolicyAssociation on JohnDoe and see what happens.

[PS] D:\Windows\system32>get-throttlingPolicyAssociation JohnDoe

RunspaceId : b84e9a5e-b4c9-4e58-ad86-26d2fffd9b32
ObjectId : MyDomain/Users/JohnDoe
ThrottlingPolicyId :
Name : JohnDoe
IsValid : True
ExchangeVersion : 0.10 (14.0.100.0)
DistinguishedName : CN=JohnDoe,CN=Users,DC=MyDomain
Identity : MyDomain/Users/JohnDoe
Guid : 4f617494-2542-480d-9db1-2720ddf3c013
ObjectCategory : MyDomain/Configuration/Schema/Person
ObjectClass : {top, person, organizationalPerson, user}
WhenChanged : 7/26/2010 8:13:48 AM
WhenCreated : 7/26/2010 8:13:48 AM
WhenChangedUTC : 7/26/2010 3:13:48 PM
WhenCreatedUTC : 7/26/2010 3:13:48 PM
OrganizationId :
OriginatingServer : MyServer.MyDomain

The association is embodied in the ThrottlingPolicyId and Name properties (in red above). If you look closely at the other properties that were returned, they are all properties on the user object. In fact, all of that data is coming from the mailbox object and not from the throttling policy. Now, let's try a mail contact. This time, I will only ask for interesting properties to save on space.

[PS] D:\Windows\system32>get-throttlingPolicyAssociation MyContact | fl ThrottlingPolicyId, Name, DistinguishedName, Identity, ObjectCategory, ObjectClass

ThrottlingPolicyId :
Name : MyContact
DistinguishedName : CN=MyContact,CN=Users,DC=MyDomain
Identity : MyDomain/Users/MyContact
ObjectCategory : MyDomain/Configuration/Schema/Person
ObjectClass : {top, person, organizationalPerson, contact}

And of course, we can't forget about computers.

[PS] D:\Windows\system32>get-throttlingPolicyAssociation MyComputer | fl ThrottlingPolicyId, Name, DistinguishedName, Identity, ObjectCategory, ObjectClass

ThrottlingPolicyId :
Name : MyComputer
DistinguishedName : CN=MyComputer,OU=Domain Controllers,DC=MyDomain
Identity : MyDomain/Domain Controllers/MyComputer
ObjectCategory : MyDomain/Configuration/Schema/Computer
ObjectClass : {top, person, organizationalPerson, user, computer}

The magic comes from the fact that the throttling policy "stamp" is made available on users, contacts and computers via the mailRecipient auxiliary class in the Active Directory schema. The attribute was actually available in Exchange 2010 RTM on users, contacts and computers, but it was not "PowerShell" accessible until these new cmdlets were added. To change the throttling policy association for a user, contact or computer, simply call set-throttlingPolicyAssociation with the identity of the account to change and the throttling policy identity to associate it with:

set-throttlingPolicyAssociation JohnDoe -ThrottlingPolicy Foo

In fact, we can assign users, contacts and computers in one shot:

[PS] D:\Windows\system32>$identity = "JohnDoe", "MyContact", "MyMachine"

[PS] D:\Windows\system32>foreach ($id in $identity){set-throttlingPolicyAssociation $id -ThrottlingPolicy Foo}

And just to confirm that it did indeed work:

[PS] D:\Windows\system32>foreach ($id in $identity){get-throttlingPolicyAssociation $id | fl Name, ThrottlingPolicyId}

Name : JohnDoe
ThrottlingPolicyId : Foo

Name : MyContact
ThrottlingPolicyId : Foo

Name : MyMachine
ThrottlingPolicyId : Foo

You may be relieved to know that getting and setting the throttling policy for a mailbox still works through get/set-Mailbox. However, for new scripts moving forward, we suggest you use the new, shiny get/set-ThrottlingPolicyAssociation cmdlets.

One important thing to note is that you use the ThrottlingPolicy parameter in set-ThrottlingPolicyAssociation whereas the property that is returned in get-ThrottlingPolicyAssociation is called ThrottlingPolicyId. Th is difference continues to trip me up when using these cmdlets, so when you encounter this difference, know that you are in good company.

- David Sterling