Use messages with the Organization service

All data operations in the organization service are defined as messages. While the IOrganizationService provides 7 methods to perform data operations (Create, Retrieve, RetrieveMultiple, Update, Delete, Associate, and Disassociate ), each of these methods is a convenience wrapper around the underlying message which is ultimately invoked using the Execute method. The underlying organization service only has the Execute method which as a single parameter: an instance of the OrganizationRequest class. The value returned by the Execute method is an instance of the OrganizationResponse class.

To make your experience better when you write code, all the standard system data operations have a pair of *Request and *Response classes defined in the SDK assemblies. Each of these classes inherit from the respective OrganizationRequest and OrganizationResponse classes and provide a more productive experience for you when you write code.

The following examples show three different ways to create an account entity record defined this way:

var account = new Account();
account.Name = "Test account";

Using IOrganizationService.Create

var id = svc.Create(account);

Using CreateRequest with IOrganizationService.Execute

CreateRequest request = new CreateRequest()
{ Target = account };
var id = ((CreateResponse)svc.Execute(request)).id;

Using OrganizationRequest with IOrganizationService.Execute

ParameterCollection parameters = new ParameterCollection();
parameters.Add("Target", account);

OrganizationRequest request = new OrganizationRequest() {
RequestName = "Create",
Parameters = parameters
};

OrganizationResponse response = svc.Execute(request);

var id = (Guid)response.Results["id"];

As you can see, common data operations have been streamlined using the IOrganizationService methods and system messages are simplified by the *Request and *Response classes in the SDK assemblies. Most of the time you will not need to use the underlying OrganizationRequest and OrganizationResponse classes except for the following cases.

Working with messages in Plug-ins

The data describing an operation in a plug-in will be in the form of IExecutionContext.InputParameters and IExecutionContext.OutputParameters. These ParameterCollection properties contain the values used for the OrganizationRequest in the first two stages of the event execution pipeline and the OrganizationResponse class in the stage after the main operation.

Understanding the structure of the messages will help you understand where to find the data you want to check or change within the plug-in.

More information:

Using Custom actions

When you use a custom action there are no classes in the SDK assemblies for these operations. You can generate classes for them using the CrmSvcUtil.exe code generation tool by using the generateActions parameter, or you can instantiate an OrganizationRequest instance and set the RequestName and Parameters to use them without the generated classes. To work with the results, you will need to parse the values returned from the OrganizationResponse.Results property.

More information:

Passing optional parameters with a request

You can pass optional parameters in messages using the Parameters property that is exposed for all the *Request message classes in the SDK assemblies. There are two optional parameters you can pass with messages

Parameter Description Messages
SolutionUniqueName A String that specifies the unique name of the solution to which the operation applies. More information: Dependency tracking for solution components. AddPrivilegesRoleRequest
CreateRequest
DeleteRequest
MakeAvailableToOrganizationTemplateRequest
UpdateRequest
SuppressDuplicateDetection A Boolean used to disable duplicate detection on a create or update operation. More information: Use SuppressDuplicateDetection parameter to throw errors when you create or update record . CreateRequest
UpdateRequest

The following sample shows how to pass an optional parameter:

Account account = new Account();  
account.Name = "Fabrikam";  
CreateRequest req = new CreateRequest();  
req.Target = account;  
req["SuppressDuplicateDetection"] = true;  
CreateResponse response = (CreateResponse)svc.Execute(req);  

See also

Entity Operations using the Organization service
Use ExecuteAsync to execute messages asynchronously
Execute messages in a single database transaction
Execute multiple requests using the Organization service