Microsoft Dataverse 中的事件框架

通过 Microsoft Dataverse 事件框架，可以检测服务器上何时发生事件并运行自定义代码以响应。使用事件框架通过注册插件、工作流、Azure 集成和 Webhook 来扩展默认平台行为。

扩展平台默认行为的所有功能都取决于事件框架。配置工作流以使用工作流设计器响应事件时，无需编写代码，事件框架将提供该事件。

作为开发人员，使用 插件注册工具 配置插件、Azure 集成、虚拟表数据提供程序和 Webhook 以响应事件框架提供的事件。当事件发生并且您注册扩展以响应这些事件时，框架会将操作中涉及的数据的上下文信息传递给扩展。根据您为事件配置注册的方式，扩展可以修改传入的数据，启动一些自动流程以便立即应用，或者定义将一个操作添加到队列中以便稍后执行。

若要利用自定义扩展的事件框架，必须了解：

哪些事件可用
事件处理方式
事件发生时自定义扩展可以使用哪种类型的数据
适用的时间和资源约束
性能监视方法

可用事件

如在 SDK for .NET 中使用消息中所述，Dataverse 平台基于消息执行数据作，并且每个消息都有一个名称。该平台包括Create、Retrieve、RetrieveMultiple、Update、Delete、Associate和Disassociate消息，这些消息涵盖表执行的基本数据操作。该平台还包括用于更复杂操作的专用消息，以及自定义操作添加新消息。

使用插件注册工具将扩展与特定消息相关联时，请将其注册为步骤。以下屏幕截图是注册插件时使用的 “注册新步骤 ”对话框。

插件注册工具中“注册新步骤”对话框的屏幕截图，其中显示了消息、实体和管道阶段字段。

步骤提供有关扩展应响应哪些消息以及许多其他配置选项的信息。使用 “消息 ”字段选择扩展响应的消息。

通常，你可以期待在或Microsoft.Crm.Sdk.Messages命名空间中，为大多数Microsoft.Xrm.Sdk.Messages类找到一条消息。您还可以查找为组织中创建的任何自定义操作的消息。平台不支持任何涉及表定义的操作。

系统将有关消息的数据存储在 SdkMessage 和 SdkMessageFilter 表中。插件注册工具将此信息筛选为仅显示有效消息。

若要验证消息和表组合是否支持使用数据库查询执行插件，请使用以下 Web API 查询：

[Organization URI]/api/data/v9.2/sdkmessages?$select=name
&$filter=isprivate eq false 
and (name ne 'SetStateDynamicEntity' 
and name ne 'RemoveRelated' 
and name ne 'SetRelated' and 
name ne 'Execute') 
and sdkmessageid_sdkmessagefilter/any(s:s/iscustomprocessingstepallowed eq true 
and s/isvisible eq true)
&$expand=sdkmessageid_sdkmessagefilter($select=primaryobjecttypecode;
$filter=iscustomprocessingstepallowed eq true and isvisible eq true)
&$orderby=name

小窍门

可以使用此查询将此数据导出到 Excel 工作表，以及此博客文章中提供的说明：使用 Dataverse 查找符合插件条件的消息和表。

还可以使用以下 FetchXML 检索此信息。 FetchXML Builder 是执行此类查询的有用工具。

<fetch>
  <entity name='sdkmessage'>
    <attribute name='name' />
    <link-entity name='sdkmessagefilter'
      alias='filter'
      to='sdkmessageid'
      from='sdkmessageid'
      link-type='inner'>
      <filter type='and'>
        <condition attribute='iscustomprocessingstepallowed' 
          operator='eq' 
          value='1' />
        <condition attribute='isvisible' 
          operator='eq' 
          value='1' />
      </filter>
      <attribute name='primaryobjecttypecode' />
    </link-entity>
    <filter>
      <condition attribute='isprivate' 
        operator='eq' 
        value='0' />
      <condition attribute='name' 
        operator='not-in'>
        <value>SetStateDynamicEntity</value>
        <value>RemoveRelated</value>
        <value>SetRelated</value>
        <value>Execute</value>
      </condition>
    </filter>
    <order attribute='name' />
  </entity>
</fetch>

注意

该 Execute 消息可用，但你不应为其注册扩展，因为每次操作都会调用它。

注释

在某些情况下，平台可能会调用您为更新事件注册的插件和工作流两次。有关详细信息，请参阅专用更新操作的行为。

事件执行管道

使用插件注册工具注册步骤时，还必须选择 事件管道执行阶段。每条消息在一系列四个阶段中进行处理，如下表所述：

名称	说明
预验证	对于初始操作，这一阶段将在主系统操作之前进行。这提供了在进行数据库事务之前取消操作的逻辑的机会。在其他阶段注册的扩展触发的后续操作也将通过此阶段，但会包含在调用扩展的事务中。此阶段在预先进行安全检查之前发生，以验证调用或登录用户是否具有执行预期作的正确权限。
PreOperation	发生在主系统操作之前，并且在数据库事务中。如果要更改消息中包含的实体的任何值，则应在此处执行此作。请避免在此处取消操作。取消操作将会触发事务回滚，并且会产生重大的性能影响。
主要操作	仅供内部使用，但自定义 API 和自定义虚拟表数据提供程序除外。详细信息：创建和使用自定义 API 自定义虚拟表数据源
PostOperation	在主要系统操作之后发生，并且在数据库事务中进行。使用此阶段可以修改消息的任何属性，然后再将其返回到调用方。避免对消息中包含的实体应用更改，因为这将触发新的更新事件。在 PostOperation 阶段中，可以注册使用异步执行模式的步骤。这些步骤将使用异步服务在数据库事务外部运行。如果插件旨在执行更新作并在用户（SystemUser）实体的“创建”消息上注册，则必须在注册插件时使用异步模式。详细信息：异步服务。

选择的阶段取决于扩展的用途。您不需要在一个步骤中应用所有业务逻辑。可以应用多个步骤，以便关于是否允许操作继续的逻辑可以在PreValidation阶段进行，并且修改消息属性的逻辑可以在PostOperation阶段进行。

重要

代码在数据库事务中的任何同步阶段引发的异常会导致整个事务回滚。确保代码处理任何可能的异常情况。如果要取消操作，可以在PreValidation阶段检测此条件，然后抛出一个包含为什么操作被取消的相应消息的InvalidPluginExecutionException。

可以为同一消息和阶段注册多个扩展。在步骤注册中， 执行顺序 值确定系统处理给定阶段的多个扩展的顺序。

系统将有关已注册步骤的信息存储在 SdkMessageProcessingStep 表中。

异步插件步骤

处理与当前记录关联的记录但在其他进程中创建的记录时，通常需要此行为。例如，只有在创建UserSettings行后，才会创建与特定SystemUser记录相关的SystemUser。

详细信息：异步服务

事件上下文

如果扩展是插件，它将接收实现 IPluginExecutionContext 接口的参数。此类提供有关插件所注册的Stage的信息。它还提供有关ParentContext操作的信息，该信息详细说明了在触发当前操作的另一个插件中的任何操作。

如果扩展是 Azure 服务总线终结点、Azure 事件中心主题或 Webhook，那么发布到已注册终结点的数据将以某种 RemoteExecutionContext 的形式呈现。此类同时实现 IPluginExecutionContext 和 IExecutionContext。

有关执行上下文的详细信息，请参阅 “了解执行上下文”。

反馈

此页面是否有帮助？

Last updated on 2026-05-01