Use messages with the Organization service
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:
- For .NET projects using PowerPlatform.Dataverse.Client.ServiceClient, use the pac modelbuilder command that is part of the Power Platform CLI. Use the --generateActions parameter to generate classes for custom actions.
- For .NET Framework projects, such as plug-ins, use
CrmSvcUtil.exe
code generation tool by using thegenerateActions
parameter.
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:
- Generate classes for early-bound programming using the Organization service
- Create your own messages
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
Feedback
Submit and view feedback for