Harnessing Messages with the SDK for .NET in Dataverse

Understanding and utilizing messages in Dataverse is essential for developers working with the SDK for .NET. Messages in Dataverse represent operations on data, like creating, updating, or retrieving records. Each message is defined by a unique name and includes collections of input and output parameters. Here, we’ll walk through different methods of working with these messages and discuss the contexts in which each is useful.

How Messages Work in Dataverse

Messages are the fundamental building blocks of data interactions in Dataverse, stored in the SdkMessage table. Messages are used in three primary ways:

1. Using OrganizationRequest and OrganizationResponse Classes: This approach allows you to work with a message directly, setting specific parameters.
2. SDK Request and Response Classes: The SDK provides classes for many standard messages, reducing the complexity of setting parameters manually.
3. IOrganizationService Methods: Common data operations like Create, Retrieve, and Update have corresponding methods in the IOrganizationService interface, simplifying usage.

Method 1: OrganizationRequest and OrganizationResponse Classes

When should you use OrganizationRequest and OrganizationResponse classes? These classes are helpful when SDK Request/Response classes aren’t available or for direct access to message parameters. Here’s an example that creates an account using OrganizationRequest:

public static Guid OrganizationRequestExample(IOrganizationService service) {
    var account = new Entity("account");
    account["name"] = "Test account";
    var parameters = new ParameterCollection { { "Target", account } };
    var request = new OrganizationRequest { RequestName = "Create", Parameters = parameters };
    OrganizationResponse response = service.Execute(request);
    return (Guid)response.Results["id"];
}

Method 2: SDK Request and Response Classes

Using SDK-defined classes, like CreateRequest and CreateResponse, simplifies the process since they manage input and output parameters. This method is especially beneficial for common tasks. Here’s a similar example using CreateRequest:

public static Guid CreateRequestExample(IOrganizationService service) {
    var account = new Account { Name = "Test account" };
    var request = new CreateRequest { Target = account };
    var response = (CreateResponse)service.Execute(request);
    return response.id;
}

Custom Actions

If you’re working with custom actions, SDK classes might not exist. In such cases, you can generate *Request and *Response classes for custom actions using the Power Platform CLI.

Method 3: IOrganizationService Methods

The IOrganizationService interface provides straightforward methods for frequent operations without the need for explicit SDK classes. Here’s how you would create an account with IOrganizationService.Create:

public static Guid CreateMethodExample(IOrganizationService service) {
    var account = new Account { Name = "Test account" };
    return service.Create(account);
}

This method allows you to manage data operations in fewer lines of code, ideal for standard tasks.

Advanced Use: Working with Messages in Plug-Ins

Messages also play a significant role in plug-ins. When developing plug-ins, you’ll interact with IExecutionContext.InputParameters and OutputParameters. Understanding how to manipulate these parameters allows you to customize data operations within the plug-in stages (e.g., PreOperation, PostOperation).

Filtering Messages by Table Support

Some messages apply only to certain tables. For instance, RetrieveUnpublishedMultiple applies to tables with publishable data. You can query the SdkMessageFilter table to find messages specific to certain tables. Here’s an example to list supported messages for a table:

static void OutputTableMessageNames(IOrganizationService service, string tableName) {
    var query = new QueryExpression("sdkmessagefilter") {
        Criteria = { Conditions = { new ConditionExpression("primaryobjecttypecode", ConditionOperator.Equal, tableName) }},
        LinkEntities = {
            new LinkEntity("sdkmessagefilter", "sdkmessage", "sdkmessageid", "sdkmessageid", JoinOperator.Inner) {
                EntityAlias = "sdkmessage", Columns = new ColumnSet("name"), LinkCriteria = { Conditions = { new ConditionExpression("isprivate", ConditionOperator.Equal, false) }}
            }
        }
    };
    EntityCollection results = service.RetrieveMultiple(query);
    foreach (var entity in results.Entities) Console.WriteLine(((AliasedValue)entity["sdkmessage.name"]).Value);
}

This example retrieves and lists the names of applicable messages for the specified table.

Key Takeaways

1. Selecting the Right Approach: Choose OrganizationRequest for flexibility, SDK classes for ease, and IOrganizationService methods for quick operations.
2. Plug-In Development: Use messages to influence plug-in behavior through InputParameters and OutputParameters.
3. Filtering Messages: The SdkMessageFilter table helps verify message applicability to tables, which is valuable when working with publishable data or specific tables.

Messages in Dataverse streamline data operations, making the SDK for .NET a powerful tool for developers. By leveraging the right method for each scenario, you can optimize your applications and customize operations to suit business needs.