Dataverse 提供了一组可选参数和请求标头值,可用于修改单个请求的行为。 本文介绍可用于获取所需行为的参数值和请求标头。
Note
本文介绍这些参数,但不深入说明这些参数。 若要充分了解这些参数的使用场景,请点击以下链接了解详细信息。
如何使用
如何使用这些可选参数取决于你使用的是 Dataverse SDK for .NET 还是 Web API。
通常,将参数添加到命名请求类的 OrganizationRequest.Parameters 集合 。
Note
无法使用公开 IOrganizationService的七种快捷方法来指定这些参数。 必须将命名请求类与 IOrganizationService.Execute 方法一起使用。
一个例外是设置partitionid时。 将 partitionid 设置为实体实例的属性。 有关详细信息,请参阅: 使用指定的分区执行数据操作
详细信息:
- 将消息与用于 .NET 的 SDK 配合使用
- 请参阅以下示例
将解决方案组件与解决方案相关联
对解决方案组件执行数据操作时,可以通过使用 SolutionUniqueName 参数指定解决方案唯一名称来将其与解决方案相关联。
可以将此参数用于以下消息:
AddPrivilegesRoleCopySystemForm-
Create(POST) -
Delete(DELETE) MakeAvailableToOrganizationTemplateRemovePrivilegeRoleReplacePrivilegesRole-
Update(PATCH) Upsert
当 SolutionUniqueName 值出现以下情况时,该操作将返回错误:
- 包含无效字符。 仅允许字母、数字和下划线字符。
- 是空字符串或使用受限的解决方案名称。
- 与任何解决方案
UniqueName值不匹配。
Important
SolutionUniqueName参数值与托管解决方案匹配时,不返回错误。 该值会被忽略。 无法将解决方案组件添加到托管解决方案。
以下示例创建一个 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 该权限。
以下示例在使用 .NET SDK 中的 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);
}
绕 过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 请求并处理错误:其他标头
绕过自定义业务逻辑