Skip to main content
Dynamics 365
·
3 min read

Using PowerShell to Enable SDK Message Throttling

Microsoft Dynamics CRM 2011 comes with a set of PowerShell commands to enable command line administration and deployment. The commands
expose a subset of the Deployment Web Service to enable getting and setting advanced settings, among other things. The complete list of supported
PowerShell commands can be found on MSDN. In this article we will walkthrough how to configure throttling on a subset of SDK messages.

Scenario

Consider a scenario where an organization has many users who utilize the Outlook Client. The Outlook Client has the ability to go offline and reconnect to sync new data. An administrator notices that the
organization’s CRM instance is experiencing poor performance due to many users attempting to sync data simultaneously. One solution is to throttle the number of simultaneous sync jobs.

Configuration

Add PowerShell Snapin

Add-PSSnapin Microsoft.Crm.Powershell

Enable Throttling

#Get the current throttle settings object from ConfigDB and

#store it in a variable.

$eTmSettings = Get-CrmSetting -SettingType EtmSettings

#Change the settings object’s properties to enable throttling.

$eTmSettings.Enabled = 1 $eTmSettings.ThrottlingEnabled = 1

#Update the settings by saving the updated settings object.

Set-CrmSetting -Setting $eTmSettings

 

Get Throttle Settings

# Get the current throttle settings object from ConfigDB and

# store it in a variable.

$settings = Get-CrmSetting -SettingType ThrottleSettings

Executing the above command will yield an object with the following properties:

MapiSyncMaxConnectionsPerServer

-1

MapiSyncPerOrgMaxConnectionsPerServer

-1

MaxBackgroundSendEmailRequestsPerOrgPerServer

-1

MaxBackgroundSendEmailRequestsPerServer

-1

OfflineSyncMaxConnectionsPerServer

-1

OfflineSyncPerOrgMaxConnectionsPerServer

-1

OutlookSyncMaxConnectionsPerServer

-1

OutlookSyncPerOrgMaxConnectionsPerServer

-1

 

Here we see there are multiple throttle settings that affect the Outlook Client sync behavior. In our scenario we wish to throttle all Outlook Client sync jobs. Therefore, the settings of
interest are OutlookSyncMaxConnectionsPerServer and OutlookSyncPerOrgMaxConnectionsPerServer.

The following logic demonstrates how the two settings interact with each other:

if ( (_organizationMax
>= 0 && organizationCount >= _organizationMax)

|| (_serverMax >= 0 && _totalCount >= _serverMax) )

// reject job request

else

// execute job request

Set Throttle Settings

By default all the throttle settings are set to -1, which implies there is no throttling. Setting the value to 0 or greater enables throttling. Using a value of 0 will disable all requests. In our scenario let’s
use 1 as a test value. Next we need to decide if we want to throttle requests Per Organization or Per Server. If there were 3 organizations, then the maximum number of simultaneous requests for the entire CRM server is 3 if we use our test value of 1. If we wish, we could set the Per Server setting to a value different from the Per Organization setting. In this case, the aforementioned logic will be used to determine whether a request is to be rejected.

$settings. OutlookSyncMaxConnectionsPerServer = -1

$settings. OutlookSyncPerOrgMaxConnectionsPerServer = 1

Set-CrmSetting -Setting $settings

Test the Configuration

No competent developer would be done without testing first! Let’s  examine how we can verify the new configuration.

Using the Application

You can setup two Outlook Clients on two separate machines (virtualization technology is helpful here). Next, connect both clients to the same CRM server and request to sync with both clients. One of the clients
should succeed while the other one fails.

Using Performance Counters

Each throttle setting is accompanied by a performance counter (Per Organization & Per Server both share the same performance counter). We can use these counters to verify our configuration. Using the same
PowerShell window execute perfmon to launch the Performance Monitor tool.

Add the following performance counter:

 
Now attempt to perform a sync job with 2 or more Outlook Clients at the same time. You should see the trend line spike up to 1 if all Outlook Clients are attempting to sync with the same organization. If each client is connecting to a different organization, then you should see the trend line spike up to X, where X is the number of clients connecting to a unique organization.

Summary

This walkthrough demonstrated how to enable and configure throttle settings for the Outlook Sync SDK message. This was done by adding the PowerShell command first and then getting, setting, and saving the settings objects. Then we verified out configuration by connecting to a CRM Server using multiple Outlook Clients and attempting to a sync job. We also verified the configuration by inspecting the relevant performance counters.

From the Get-CrmSetting -SettingType ThrottleSettings command we could see there were more throttle settings for other SDK messages. If more are added in future releases we can use the same steps to discover and configure throttle settings for those messages as well. We will leave that as another exercise.

Bao Nguyen <baonguy@microsoft.com>