Edit

Use messages with the Organization service

  • Article
  • 2 minutes to read

Note

Unsure about entity vs. table? See Developers: Understand terminology in Microsoft Dataverse.

All data operations in the organization service are defined as messages. While the IOrganizationService provides seven 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 that 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 inherits 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 row 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 made easier to use with the *Request and *Response classes in the SDK assemblies. Most of the time you don't 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 are in the form of IExecutionContext.InputParameters and IExecutionContext.OutputParameters.

In the PreValidation and PreOperation stages before the main operation of the event pipeline, the InputParameters represent the OrganizationRequest.Parameters. After the main operation, in the PostOperation stage, the OutputParameters represent the OrganizationResponse.Results.

Understanding the structure of the messages helps 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:

Alternatively, 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'll parse the values returned from the OrganizationResponse.Results property.

More information:

Passing optional parameters with a request

There are several optional parameters you can pass to apply special behaviors to messages. More information: Use optional parameters

Private Messages

Microsoft Dataverse contains some messages that aren't intended for third party developers to use. Microsoft added these messages enable feature functionality, but third party solutions can also add them with the Custom API feature. The SdkMessage.IsPrivate property tells you which messages are private.

Caution

You should not use private messages unless you created them as a Custom API. By marking a message as private, the solution publisher is explicitly calling out that they do not support other apps to use the message. They may remove the message or introduce breaking changes at any time. Use of these messages by anyone other than the solution publisher are not supported. Calling private messages from plug-ins is not supported.

More information: Create and use Custom APIs

See also

Table 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