There are scenarios in which you will be integrating with the Common Data Service from outside the platform. This could be a console application designed to create records or an integration process designed to send data from an external system into Dynamics 365 CE. Creating, Updating or Deleting data on a single record basis could adversely affect performance and reach your organization’s API limits.
The API limits only apply to online instances. Due to the shared nature of the online hosts, the limits are put in place by Microsoft to ensure the stability of the online platform for all customers. Microsoft limits the number of concurrent requests as well as limiting the number of requests per user. The request per user limit is 60,000 API calls in five minutes, subject to change. Microsoft doesn’t specify the number of concurrent requests, but the ExecuteMultipleRequest does state that it is limited to two concurrent connections. If the API limits are exceeded, a FaultException is returned.
There are two useful messages in the SDK that reduce the number of API calls by executing requests in bulk. ExecuteMultipleRequest and ExecuteTransactionRequest both execute batch requests against the API. Both messages have a batch size limit of 1000 calls and two concurrent connections, so you may need to use multiple batches to complete your calls. An ExecuteTransactionRequest will execute all calls in a single transaction, rolling back if an error has occurred. ExecuteMultipleRequest is not in a transaction and it will not rollback previously completed requests if an error occurs. ExecuteMultipleRequests can be configured to either stop processing when the first error is received or continue processing, keeping a record of each failed call.
Note that an ExecuteMultipleRequest is allowed to contain one or more ExecuteTransactionRequest calls, but an ExecuteTransactionRequest cannot contain any ExecuteMultipleRequests. ExecuteMultipleRequests cannot include another ExecuteMultipleRequest nor can an ExecuteTransactionRequest include another ExecuteTransactionRequest. Neither of these messages should be used in plugins or custom workflow activities, as they will adversely affect performance and could trigger the two-minute channel timeout exception.
Microsoft guidance on when to use ExecuteMultipleRequest or ExecuteTransactionRequest is:
- Use ExecuteMultipleRequest to bulk load data or external processes that are intentional about executing long-running operations (greater than two minutes).
- Use ExecuteMultipleRequest to minimize the round trips between custom client and Dynamics 365 servers, thereby reducing the cumulative latency incurred.
- Use ExecuteTransactionRequest for external clients that require the batch of operations to be committed as a single, atomic database transaction or rollback if any exception is encountered. Be aware of the potential for database blocking for the duration of the long-running transaction.
Using ExecuteMultipleRequest and ExecuteTransactionRequest are both good methods for reducing the number of API calls as well as increasing the performance of external calls. Neither is meant to be used from within plugins nor custom workflow activities. To learn how to use these methods, and to view sample code, use the Microsoft Docs references listed below.