Edit

Share via

Use optional parameters

  • Article

Dataverse provides a set of optional parameters or request header values a developer of a client application can use to modify the behavior of individual requests. This article describes the parameter values and request headers that you can use to get the behaviors you need.

Note

This article introduces these parameters but does not explain them in depth. Please follow the links for more information to fully understand the scenarios for using these parameters.

How to use

How you use these optional parameters depends on whether you're using the Dataverse SDK for .NET or Web API.

Usually, you will add the parameter to the OrganizationRequest.Parameters Collection of the named request class.

Note

You cannot specify these parameters using the 7 shortcut methods exposed with the IOrganizationService. You must use the named request class with the IOrganizationService.Execute method.

One exception is when setting the partitionid, this is set as an attribute of the entity instance. More information: Perform a data operation with specified partition

More information:

Associate a solution component with a solution

When you perform data operations on a solution component, you can associate it with a solution by specifying the solution unique name with the SolutionUniqueName parameter.

You can use this parameter with these messages:

  • AddPrivilegesRole
  • Create (POST)
  • Delete (DELETE)
  • MakeAvailableToOrganizationTemplate
  • Update (PATCH)

The following examples create a web resource solution component and add it to the solution with the unique name of ExampleSolution.

static void CreateWebResourceInSolution(IOrganizationService service)
{
    Entity webResource = new("webresource");

    webResource["displayname"] = "Simple HTML web resource";
    webResource["content"] = "PCFET0NUWVBFIGh0bWw+CjxodG1sPgogIDxib2R5PgogICAgPGgxPkhlbGxvIFdvcmxkPC9oMT4KICA8L2JvZHk+CjwvaHRtbD4=";
    webResource["webresourcetype"] = new OptionSetValue(1);
    webResource["name"] = "sample_SimpleHTMLWebResource.htm";
    webResource["description"] = "An example HTML web resource";

    CreateRequest request = new();
    request.Target = webResource;
    request["SolutionUniqueName"] = "ExampleSolution";

    service.Execute(request);
}

More information:

More information:

Suppress duplicate detection

If you want to have Dataverse throw an error when a new record you create or a record you update matches the duplicate detection rules for another record, you must create or update the row using the SuppressDuplicateDetection parameter with a value of false.

The following examples return an error when the following are true:

  • Duplicate Detection is enabled for the environment when a row is created or updated.
  • The account table has duplicate detection enabled
  • A Duplicate Detection Rule is published that checks whether the account name value is an exact match for an existing row
  • There's an existing account with the name Sample Account.
static void DemonstrateSuppressDuplicateDetection(IOrganizationService service)
{
    Entity account = new("account");
    account["name"] = "Sample Account";

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("SuppressDuplicateDetection", false);

    try
    {
        service.Execute(request);
    }
    catch (FaultException<OrganizationServiceFault> ex)
    {
        throw ex.Detail.ErrorCode switch
        {
            -2147220685 => new InvalidOperationException(ex.Detail.Message),
            _ => ex,
        };
    }
}

More information:

Add a shared variable to the plugin execution context

Use the tag parameter to include a shared variable value that is accessible within a plug-in. This extra information allows a plug-in to apply logic that depends on the client application.

Note

This parameter is intended for client applications to be able to set any value they wish. No Microsoft feature should require that you set a specific value in your client application code to enable different behaviors.

To access the value in a plug-in, use the IExecutionContext.SharedVariables collection

if (context.SharedVariables.ContainsKey("tag")){
    string tagValue = context.SharedVariables["tag"];
}

The following examples pass this value: A string value while creating an account record.

static void DemonstrateTag(IOrganizationService service)
{
    Entity account = new("account");
    account["name"] = "Sample Account";

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("tag", "A string value");
    service.Execute(request);
}

More information: Shared variables

Perform a data operation with specified partition

When using elastic tables with a partitioning strategy, you can pass a unique string value with the partitionid parameter to access non-relational table data within a storage partition.

The following examples use the partitionid value of deviceId when retrieving a contoso_sensordata record.

private static Entity RetrieveRecord(
    IOrganizationService service,
    Guid contosoSensorDataId,
    string deviceId,
    string sessionToken)
{
    EntityReference entityReference = new("contoso_sensordata", contosoSensorDataId);

    RetrieveRequest request = new()
    {
        ColumnSet = new ColumnSet("contoso_value"),
        Target = entityReference,
        ["partitionId"] = deviceId, //To identify the record
        ["SessionToken"] = sessionToken //Pass the session token for strong consistency
    };
    var response = (RetrieveResponse)service.Execute(request);
    return response.Entity;

}

Alternatively, you can use the partitionid value using alternate key style.

Bypass custom Dataverse logic

Synchronous logic must be applied during the transaction and can significantly impact performance of individual operations. When performing bulk operations, the additional time for these individual operations can increase the time required. Use the BypassBusinessLogicExecution parameter when you want to improve performance while performing bulk data operations.

Important

The calling user must have the prvBypassCustomBusinessLogic privilege.

The following example sets the BypassBusinessLogicExecution optional parameter for both synchronous and asynchronous custom logic when creating a new account record using the SDK for .NET CreateRequest class.

static void DemonstrateBypassBusinessLogicExecution(IOrganizationService service)
{
    Entity account = new("account");
    account["name"] = "Sample Account";

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("BypassBusinessLogicExecution", "CustomSync,CustomAsync");
    service.Execute(request);
}

Learn more about ways to bypass custom Dataverse logic

Bypass Power Automate Flows

When bulk data operations occur that trigger flows, Dataverse creates system jobs to execute the flows. When the number of system jobs is very large, it may cause performance issues for the system. If this occurs, you can choose to bypass triggering the flows by using the SuppressCallbackRegistrationExpanderJob optional parameter.

The CallbackRegistration table manages flow triggers, and there's an internal operation called expander that calls the registered flow triggers.

Note

When this option is used, the flow owners will not receive a notification that their flow logic was bypassed.

static void DemonstrateSuppressCallbackRegistrationExpanderJob(IOrganizationService service)
{
    Entity account = new("account");
    account["name"] = "Sample Account";

    CreateRequest request = new()
    {
        Target = account
    };
    request.Parameters.Add("SuppressCallbackRegistrationExpanderJob", true);
    service.Execute(request);
}

More information: Bypass Power Automate Flows

See also

Use messages with the SDK for .NET
Web API: Compose HTTP requests and handle errors : Other headers
Bypass Custom Business Logic