Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Dataverse provides a set of optional parameters and request header values that you 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 doesn't explain them in depth. To fully understand the scenarios for using these parameters, follow the links for more information.
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 add the parameter to the OrganizationRequest.Parameters Collection of the named request class.
Note
You can't specify these parameters by using the seven shortcut methods exposed by IOrganizationService. You must use the named request class with the IOrganizationService.Execute method.
One exception is when setting the partitionid. Set the partitionid as an attribute of the entity instance. For more information, see: Perform a data operation with specified partition
More information:
- Use messages with the SDK for .NET
- See the following examples
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:
AddPrivilegesRoleCopySystemFormCreate(POST)Delete(DELETE)MakeAvailableToOrganizationTemplateRemovePrivilegeRoleReplacePrivilegesRoleUpdate(PATCH)Upsert
The operation returns an error when the SolutionUniqueName value:
- Includes invalid characters. Only letters, digits, and underscore characters are allowed.
- Is an empty string or uses a restricted solution name.
- Doesn't match any solution
UniqueNamevalue.
Important
No error is returned when the SolutionUniqueName parameter value matches a managed solution. The value is ignored. You can't add a solution component to a managed solution.
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 Dataverse to return 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 by using the SuppressDuplicateDetection parameter with a value of false.
The following examples return an error when the following conditions are true:
- Duplicate detection is enabled for the environment when you create or update a row.
- The
accounttable has duplicate detection enabled. - A duplicate detection rule is published that checks whether the account
namevalue 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 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 you use elastic tables with a partitioning strategy, pass a unique string value with the partitionid parameter to access nonrelational 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, use the partitionid value with the alternate key style.
Bypass custom Dataverse logic
Synchronous logic applies during the transaction and can significantly impact the performance of individual operations. With bulk operations, the extra 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 by 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 large, it might cause performance problems for the system. If performance problems occur, 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 you use this option, the flow owners don't 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
Return unmasked data
When you configure a column to use the masking rules preview feature, use the UnMaskedData optional parameter to request the unmasked value.
RetrieveMultipleRequest request = new()
{
Query = query,
["UnMaskedData"] = true
};
var response = (RetrieveMultipleResponse)service.Execute(request);
Learn more about retrieving unmasked data.
See also
Use messages with the SDK for .NET
Web API: Compose HTTP requests and handle errors : Other headers
Bypass Custom Business Logic