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

Applies To: Dynamics CRM 2013

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, CRM 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 CRM 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 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 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 choose to 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 IOrganizationService web 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
CRM messages in the organization service
ExecuteAsync message privileges