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

Artykuł
11/28/2016

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.

Execute message flow

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.

Parameter	Description	Messages
SolutionUniqueName	A String that specifies the unique name of the solution to which the operation applies. For more information, see Dependency tracking for solution components.	AddPrivilegesRoleRequest CreateRequest DeleteRequest MakeAvailableToOrganizationTemplateRequest UpdateRequest
CalculateMatchCodeSynchronously	Specifying this parameter is no longer required. The match codes used to detect duplicates are calculated synchronously regardless of the value passed in this parameter. For more information, see Run duplicate detection.	CreateRequest UpdateRequest
SuppressDuplicateDetection	A Boolean used to disable duplicate detection on a create or update operation. For more information, see Run duplicate detection.	CreateRequest UpdateRequest

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.

Note

Currently, only the ImportSolutionRequest message can be used with the ExecuteAsync message.

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.

Udostępnij za pośrednictwem

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

In This Topic

Pass optional parameters in messages

Execute messages in a single database transaction

Execute messages in the background (asynchronously)

See Also

Dodatkowe zasoby