Use messages (request and response classes) with the Execute method

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

You can use the methods in the IOrganizationService to perform common operations. In addition to the common methods, methods, you can use the IOrganizationService.Execute method to execute messages that are not exposed as methods. The Execute method takes a message request class as a parameter and returns a message response class. Request message class names end with "Request" and response message class names end with "Response". For more information about all messages supported by the Execute method, see xRM messages in the Organization service, Dynamics 365 messages in the organization service. The IDiscoveryServiceand the IDeploymentService web services use a similar execute request and response pattern.

OrganizationRequest is the base class for all messages requests. You can use this base class to execute any messages, specifying the message name and the parameter collection for the request. However, when you use a derived class, such as AssociateRequest, the parameter collection is populated when you use the properties on the request class.

The Execute method returns the corresponding response class for the request, a derived class of the OrganizationResponse class. As with the request class, the derived class contains a property for each value in the results parameter collection. All messages have a response, but many do not have any properties on the response. .

Messages are pre-defined in metadata and stored as records in the SDK message entities. For each message you can determine whether it works while connected to the server or from Microsoft Dynamics 365 for Microsoft Office Outlook with Offline Access. This information can be found in the SdkMessage.Availability attribute. For more information, see Plug-in registration entities.

In This Topic

Pass optional parameters in messages

Execute messages in a single database transaction

Execute messages in the background (asynchronously)

Pass optional parameters in messages

You can pass optional parameters to any message request by adding a value to the Parameters property. Some parameters are not exposed properties on request classes. In order to set these parameters, they must be set in the Parameters collection on the Request class.

The following table lists these parameters.

The following sample shows how to pass an optional parameter:

Account target = new Account();
target.Name = "Fabrikam";
CreateRequest req = new CreateRequest();
req.Target = target;
req["SuppressDuplicateDetection"] = true;
req["CalculateMatchCodeSynchronously"] = true;
req["SolutionUniqueName"] = "MySolutionName";
CreateResponse response = (CreateResponse)_service.Execute(req);

Execute messages in a single database transaction

It is a common requirement in business applications to coordinate changes of multiple records in the system so that either all the data changes succeed, or none of them do. In database terms, this is known as executing multiple operations in a single transaction with the ability to roll back all data changes should any one operation fail.

You can execute two or more organization service requests in a single database transaction using the ExecuteTransactionRequest message request. To use this message, populate the Requests collection with two or more organization requests that are to be executed in the transaction. Set ReturnResponses to true if you want to get back a collection of responses, one for each message request executed, in the Responses collection. Message requests in the Requests collection are executed in order as they appear in the collection, where the element at index 0 is executed first. This same order is preserved in the Responses collection.

Should any one of the requests fail and the transaction is rolled back, any data changes completed during the transaction are undone. In addition, a ExecuteTransactionFault is returned identifying the index into the request collection of the request message that caused the fault.

An ExecuteMultipleRequest may contain one or more ExecuteTransactionRequest instances. An ExecuteTransactionRequest instance may not contain a ExecuteMultipleRequest or ExecuteTransactionRequest. For more information on ExecuteMultipleRequest, see Use ExecuteMultiple to improve performance for bulk data load.

For sample code that demonstrates ExecuteTransactionRequest see Sample: Execute multiple requests in transaction.

Execute messages in the background (asynchronously)

In addition to executing message requests immediately, as is the case with calling Execute and passing a message request, you can also execute a message request in the background (asynchronously). This improves system performance by postponing message execution until some later time when the server load may be less. Interactive users do not have to wait for the target message to execute before they can continue. This is especially useful when processing messages that take a few minutes or more to execute.

Use the ExecuteAsyncRequest message to execute a message asynchronously. You configure the request and pass the request instance as an argument to Execute. ExecuteAsyncResponse returns with the ID of the asynchronous job. You can (optionally) query the job using the ID to find out its current state.

You can also execute multiple messages at a time using the ExecuteMultipleRequest message. To do this, add one or more ExecuteAsync message requests to an ExecuteMultiple message request. Due to throttling restrictions that improve overall system performance, only one message running asynchronously is allowed to execute at a time for each organization. You cannot execute an ExecuteMultiple message request from an ExecuteAsync message request. For more information about the ExecuteMultiple message request, see Use ExecuteMultiple to improve performance for bulk data load.

See Also

Execute
OrganizationRequest
OrganizationResponse
ExecuteAsyncMaxConnectionsPerServer
ExecuteAsyncPerOrgMaxConnectionsPerServer
Use the Organization Service to read and write data or metadata
Use ExecuteMultiple to improve performance for bulk data load
Use messages (request and response classes) with the ExecuteCrmOrganizationRequest method
Messages in the discovery service
xRM messages in the Organization service
Dynamics 365 messages in the organization service
ExecuteAsync message privileges

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright