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 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 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 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:
- Generate classes for early-bound programming using the Organization service
- Create your own messages
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 several 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 row . |
CreateRequest UpdateRequest |
tag |
A value to include within the ExecutionContext SharedVariables collection. |
Any message that can have a plug-in step registered. More information: Add a shared variable from the Organization Service |
PartitionId |
A unique String value used to access non-relational table data in NoSql tables within a storage partition. Used to improve performance when accessing table data in Azure heterogenous storage. More information: Improve performance when accessing table data using storage partitions |
CreateRequest UpdateRequest RetrieveRequest DeleteRequest |
BypassCustomPluginExecution |
Bypasses custom plug-ins when included in a request sent by someone with the prvBypassCustomPlugins privilege. More information: Bypass Custom Business Logic |
Any request that could include custom plug-ins. |
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);
Add a shared variable from the Organization Service
You can set a string value that will be available to plug-ins within the ExecutionContext in the SharedVariables collection. More information: Shared variables
var account = new Entity("account");
account["name"] = "Contoso";
var request = new CreateRequest() { Target = account };
request["tag"] = "This is a value passed.";
var response = (CreateResponse)svc.Execute(request);
Will result in the following value within the SharedVariables collection when sent using a webhook.
{
"key": "tag",
"value": "This is a value passed."
}
This can also be done using the Web API: Add a Shared Variable from the Web API
Private Messages
Microsoft Dataverse contains some messages which are not intended for 3rd party developers to use. These messages are typically added by Microsoft to enable feature functionality, but can also be added by 3rd party solutions with the Custom API feature. Private messages are indicated by the SdkMessage.IsPrivate property.
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
Зворотний зв’язок
Надіслати й переглянути відгук про