了解传递给插件的数据上下文

 

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

当插件响应于自己为之注册的执行管道事件而运行时，插件的 Execute 方法被调用。 那个方法通过 IServiceProvider 对象作为参数，包含一定数量的有用对象。 以下部分说明了传递到插件中的正在执行的某些信息。

本主题内容

访问插件执行上下文

访问组织服务

访问通知服务

输入和输出参数

前期事件和后期实体映像

访问插件执行上下文

IPluginExecutionContext 包含描述执行插件的运行时环境的信息、与执行管道相关的信息以及实体业务信息。 上下文包含在 System.IServiceProvider 参数中，该参数通过其 Execute 方法在运行时传递到插件。

// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
    serviceProvider.GetService(typeof(IPluginExecutionContext));

在触发了已注册插件的系统事件时，系统会创建和填充上下文，并通过上述的类和方法将其传递到插件。 执行上下文会在插件执行时被传递到管道中的每一个注册插件。 执行管道中的每个插件都可以修改上下文中的可写属性。 例如，对于一个为前期事件注册的插件和另一个为后期事件注册的插件，后期事件插件可以接收前期事件插件修改的上下文。 同样，相同阶段中注册的插件也可以如此。

IPluginExecutionContext 中的所有属性都是只读的。 不过，您的插件可以修改那些为集合的属性内容。 有关预防无线循环的详细信息，请参阅 Depth。

访问组织服务

若要访问 Microsoft Dynamics 365 组织服务，则要求插件代码通过 ServiceProvider.GetService 方法来创建该服务的一个实例。

// Obtain the organization service reference.
IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

当您使用此方法时，平台会为您提供正确的 Web 服务 URL 和网络凭证。 不支持对您自己的 Web 服务代理进行实例化，因为它会产生死锁和身份验证问题。

访问通知服务

同步注册的插件可以将执行上下文发布到 Microsoft Azure 服务总线。 传递至插件中的服务提供商对象包含对 IServiceEndpointNotificationService 的引用。 它凭借的是可让同步插件向 Microsoft Azure 服务总线 发送中介消息的通知服务。 有关 Microsoft Azure 的详细信息，请参阅Azure 与 Microsoft Dynamics 365 的集成。 有关编写可以发布到 Microsoft Azure 服务总线 的插件的详细信息，请参阅编写 Azure 感知自定义插件。

输入和输出参数

InputParameters 属性包含目前由事件执行管道处理的请求消息中的数据。 您的插件代码可以访问此数据。 属性为 ParameterCollection 类型，其中访问请求数据的键是请求中实际公共属性的名称。 举例来说，让我们看一下 CreateRequest。CreateRequest 中的一个属性被命名为 Target， Entity 类型。 这是目前平台正在操作的实体。 若要访问实体的数据，您需要使用“Target”名称作为输入参数集合中的键。 您还需要发送返回的实例。

// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&
    context.InputParameters["Target"] is Entity)
{
    // Obtain the target entity from the input parameters.
    Entity entity = (Entity)context.InputParameters["Target"];

请注意，不是所有的请求都包含类型 Entity 的 Target 属性，因此您需查看每个请求或响应。 例如，DeleteRequest 有 Target 属性，但是它的类型是 EntityReference。 先前的代码示例将在下文中更改。

// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&    context.InputParameters["Target"] is EntityReference)
{
    // Obtain the target entity from the input parameters.
    EntityReference entity = (EntityReference)context.InputParameters["Target"];
}

只要您可以访问实体数据，就可以对其进行读取和修改。 注册的插件在管道的阶段 10 或 20 中执行的任何数据更改将在上下文中被传递到阶段 30 中的核心操作。

重要

并非通过上下文传递到插件实体记录中的所有字段都是可以修改的。 您应检查字段的 IsValidForUpdate元数据特性验证它未被设置为 false。 尝试更改出现异常的无法更新字段的值。

同样，OutputParameters 属性包含响应消息中的数据，例如 CreateResponse，目前正通过事件执行管道进行传递。 不过,只有同步的后期事件和异步的注册插件填充了 OutputParameters，因为响应是核心平台操作的结果。 该属性类型为 ParameterCollection，其中访问响应数据的键是响应中实际公共属性的名称。

前期事件和后期实体映像

PreEntityImages和PostEntityImages包含核心平台操作之前或之后的主要实体属性快照。Microsoft Dynamics 365 基于模拟的系统用户的安全权限填充前期实体和后期实体映像。 只有设置为某个值或值为空的实体属性才在前期或后期实体映像中可用。 当您注册您的插件时，可以指定让平台填充这些 PreEntityImages 和 PostEntityImages 属性。 插件代码会将您在插件注册期间指定的实体别名值用作插件代码中图像集合的键值。

某些事件没有可用的映像。 例如，只有同步的后期事件和异步的注册插件填充了 PostEntityImages。 创建操作不支持前期映像，删除操作不支持后期映像。 另外，如下表所显示，消息中仅有一个小子集支持前期和后期图像。

消息请求	属性	说明
AssignRequest	目标	被分配的实体。
CreateRequest	目标	被创建的实体。
DeleteRequest	目标	已删除的实体。
DeliverIncomingEmailRequest	电子邮件 ID	已递送的电子邮件 ID。
DeliverPromoteEmailRequest	电子邮件 ID	已递送的电子邮件 ID。
ExecuteWorkflowRequest	目标	工作流实体。
MergeRequest	目标	父实体，由子实体的数据合并而成。
MergeRequest	实体 ID	子实体，被合并成父实体。
SendEmailRequest	电子邮件 ID	已发送的实体 ID。
SetStateRequest	实体名称	状态已设置的实体。
UpdateRequest	目标	已更新的实体。

注册前期映像和后期映像来访问实体属性值相对于通过 RetrieveRequest 或 RetrieveMultipleRequest 请求在插件代码中获取实体属性而言，提升了插件性能。

安全性 说明
在执行上下文中传递到插件的前期映像或自定义工作流活动可能包含已登录的用户无权访问的数据。Microsoft Dynamics 365 管理员及其他高级权限用户才能注册插件，以便在“系统”用户帐户下运行，或插件代码可充当“系统”用户以登录用户的名义进行调用。 如果发生此种情况，则登录用户可访问自己的字段级别安全性不允许访问的数据。详细信息：插件中的模拟

另请参阅

插件开发
处理插件中的异常
事件执行管道
将消息（请求和响应类）与 Execute 方法结合使用
使用组织服务读取和写入数据或元数据
注册和部署插件

Microsoft Dynamics 365

© 2017 Microsoft。 保留所有权利。 版权