使用可选参数

Dataverse 提供了一组可选参数或请求标头值，客户端应用程序的开发人员可以使用这些值来修改单个请求的行为。 本文介绍可用于获取所需行为的参数值和请求标头。

Note

本文介绍这些参数，但不深入说明这些参数。 按照链接获取详细信息，以充分了解这些参数的使用场景。

如何使用

如何使用这些可选参数取决于你使用的是 Dataverse SDK for .NET 还是 Web API。

通常，您会将参数添加到相应的请求类的 OrganizationRequest.Parameters 集合 中。

Note

不能使用通过 IOrganizationService 公开的七种快捷方法指定这些参数。 必须将命名请求类与 IOrganizationService.Execute 方法一起使用。

一个例外是设置partitionid时。 将partitionid设置为实体实例的一个属性。 详细信息： 使用指定的分区执行数据操作

详细信息：

将解决方案组件与解决方案相关联

对解决方案组件执行数据操作时，可以通过使用 SolutionUniqueName 参数指定解决方案唯一名称来将其与解决方案相关联。

可以将此参数用于以下消息：

  • AddPrivilegesRole
  • Create （POST）
  • Delete （DELETE）
  • MakeAvailableToOrganizationTemplate
  • Update （PATCH）

以下示例创建一个 Web 资源解决方案组件，并将其添加到唯一名称为 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);
}

详细信息：

详细信息：

抑制重复检测

如果要让 Dataverse 在创建的新记录或更新的记录与另一条记录的重复检测规则匹配时引发错误，则必须在创建或更新行时将 SuppressDuplicateDetection 参数的值设置为 false。

以下示例在出现以下情况时返回错误：

  • 环境已启用重复检测，以便在创建或更新行时进行检测。
  • 表 account 已启用重复检测
  • 发布重复检测规则，用于检查帐户 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,
        };
    }
}

详细信息：

将共享变量添加到插件执行上下文

使用 tag 参数包含可在插件中访问的共享变量值。 此额外信息允许插件执行依赖于客户端应用程序的逻辑。

Note

此参数供客户端应用程序设置为任意值。 任何 Microsoft 功能都不应要求你在客户端应用程序代码中设置特定值以启用不同的行为。

若要在插件中访问该值，请使用 IExecutionContext.SharedVariables 集合

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

以下示例在创建帐户记录时可接受此值：A string value

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);
}

详细信息： 共享变量

使用指定的分区执行数据操作

将弹性表与分区策略结合使用时，可以通过 partitionid 参数传递唯一的字符串值，以访问存储分区中的非关系表数据。

以下示例在检索deviceId记录时使用contoso_sensordata的partitionid值。

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;

}

或者，可以使用替代键样式来使用 partitionid 值。

绕过自定义 Dataverse 逻辑

同步逻辑必须在事务期间应用，并且可能会显著影响单个操作的性能。 对于批量操作，这些单独操作的额外时间可能会增加所需的时间。 如果要在执行大容量数据操作时提高性能， BypassBusinessLogicExecution 请使用此参数。

Important

呼叫用户必须具有 prvBypassCustomBusinessLogic 该权限。

以下示例在使用 SDK for .NET CreateRequest 类创建新帐户记录时，为同步和异步自定义逻辑设置 BypassBusinessLogicExecution。

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);
}

详细了解绕过自定义 Dataverse 逻辑的方法

跳过 Power Automate 流程

当发生触发流的大容量数据操作时，Dataverse 会创建系统作业来执行流。 当系统作业数很大时，可能会导致系统出现性能问题。 如果出现性能问题，可以选择使用 SuppressCallbackRegistrationExpanderJob 可选参数绕过触发这些流。

CallbackRegistration 表管理流触发器，并且有一个名为expander的内部操作调用已注册的流触发器。

Note

使用此选项时，流所有者不会收到其流逻辑被绕过的通知。

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);
}

详细信息：绕过Power Automate流

返回未屏蔽的数据

如果列配置为使用 掩码规则 预览功能，则可以使用 UnMaskedData 可选参数请求返回未屏蔽的值。

RetrieveMultipleRequest request = new()
{
   Query = query,
   ["UnMaskedData"] = true
};

var response = (RetrieveMultipleResponse)service.Execute(request);

详细了解如何检索未屏蔽的数据。

另请参阅

将消息与用于 .NET 的 SDK 配合使用
Web API：撰写 HTTP 请求并处理错误：其他标头
绕过自定义业务逻辑

  • 上次更新时间为