编写和编译插件后，必须向 event 框架注册该插件，以在Microsoft Dataverse处理特定实体（表行）和消息（操作）时执行。 使用 Dataverse 注册插件需要使用工具——即插件注册工具（PRT）或 Visual Studio 的 Power Platform Tools 扩展。
PRT 创建 Dataverse 对象注册，并支持编辑这些注册。 本文介绍如何注册插件程序集和消息处理步骤、将程序集添加到解决方案，以及使用插件注册工具执行其他常见的插件相关操作。
Visual Studio扩展提供了功能更丰富的开发环境，涵盖整个编码、部署和调试/分析开发过程。 有关使用适用于 Visual Studio 的 Power Platform Tools 扩展的信息，请参阅 quickstart。
关于插件注册工具
插件注册工具（PRT）支持使用 Dataverse 注册插件程序集、消息处理步骤和其他类型的对象。 PRT 是可从 NuGet.org 下载的多个 Dataverse 工具之一。按照 Dataverse 开发工具 中的说明下载 PRT 和其他开发工具（可选）。
下载 PRT 后，按照 “使用插件注册”工具 说明进行连接，将该工具连接到要注册插件的目标 Dataverse 环境。
程序集注册
注册程序集包括将程序集上传到 Dataverse 数据库，该工具为你处理该数据库。 请参阅在教程中 注册程序集 时找到的说明 ：编写和注册插件
注释
你将找到与程序集的 隔离模式 和 位置 相关的选项。 这些选项适用于本地部署。 Dataverse 不适用于本地部署，因此请始终接受 SandBox 和 Database 的默认选项。
上传程序集后，该程序集将存储在 PluginAssembly 表中。 大多数属性都是使用导入程序集的反射设置的。 程序集的 base64 编码字节存储在 Content 列中。 在 PRT 中查看程序集 的属性 时，只能编辑 Description 值。 实现 IPlugin 接口或派生自 CodeActivity 的程序集中的所有已编译类都将自动注册。
查看已注册的程序集
可以在 Power Apps 和 PRT 程序集视图中访问有关已注册插件程序集和步骤的信息。 若要访问Power Apps中的插件信息，请在左侧导航窗格中选择 Solutions，然后从列表中选择可用的解决方案。 接下来，选择左侧“插件程序集”或“插件步骤”的对象窗格。
注释
注册的每个程序集都会添加到 默认解决方案 ，不应与 Common Data Services 默认解决方案混淆。 有关解决方案的详细信息，请参阅 解决方案简介
将程序集添加到解决方案
如 “查看已注册的程序集”中所述，创建的程序集注册已添加到系统 默认解决方案。 应将程序集添加到非托管解决方案，以便将其分发给其他组织。 PRT 不允许在注册程序集或步骤时指定解决方案。
若要详细了解解决方案以及如何创建解决方案，请参阅 解决方案概述 和 创建解决方案。 创建解决方案后，可以通过先在解决方案列表中选择解决方案，将插件程序集添加到Power Apps中， 然后选择 Add existing>More>Developer>Plug-in 程序集。
注释
任何现有或后续的步骤注册（请参阅下一部分）都不会添加到包含插件程序集的非托管解决方案中。 必须将每个注册步骤单独添加到解决方案中。 详细信息： 向解决方案添加步骤
步骤注册
注册消息处理步骤会告知 Dataverse 插件应执行的情况，以及如何执行它。 根据条件，我们指的是 Dataverse 处理的表和消息操作。 可以在步骤注册期间指定其他配置选项，例如同步或异步执行，在核心操作之前或之后指定其他配置选项。 下一部分详细介绍了这些运行时配置选项。
加载或更新程序集时，PRT 中提供了实现 IPlugin 的任何类。 使用教程：编写并注册插件中的步骤注册新步骤部分中的说明，来创建新的步骤注册。
常规配置信息字段
| 领域 | 说明 |
|---|---|
| Message | 由 Dataverse 处理的消息会导致插件执行。
如果没有为核心消息（如 |
| 主要实体 | 在 Dataverse 处理实体（表）后，会触发插件执行。
消息具有接受 |
| 辅助实体 | 对于接受EntityReference数组作为Target参数的已弃用消息，此字段仍保持向后兼容性。 此字段通常不再使用。 |
| 筛选属性 | 对于UpdateOnExternalUpdated消息或其他消息，当您设置主要实体时，筛选属性（列）将把插件的执行限制在更新中包含指定列的情况下。 仅在更新操作中包含具有已更改值的列。 如果请求包含筛选属性，则无论属性的值是否已更改，都会触发插件。设置此字段是性能的最佳做法。 不要在筛选属性中包含实体的主键。 主键始终包含在更新操作中，因此这样做会否定所有其他筛选属性。 |
| 事件处理程序 | 此字段值基于程序集的名称和插件类在 PRT 中填充。 |
| 步骤名称 | 消息处理步骤的名称。 根据步骤的配置预填充值，但可以覆写此值。 |
| 在用户的上下文中运行 | 提供用于应用步骤模拟的选项。 默认值为 “呼叫用户”。 如果调用用户无权在步骤中执行操作，则可能需要将此字段值设置为具有这些权限的用户。 详细信息： 为步骤设置用户模拟 |
| 执行顺序 | 可以为同一阶段和消息注册多个步骤。 此字段中的数字确定步骤在从最低到最高阶段中应用的顺序。 应将此字段设置为控制在同一阶段中执行插件的顺序。 不建议只接受默认值。 具有相同执行顺序值的插件的实际执行顺序（对于同一阶段、表和消息）是不能保证的，并且可以是随机的。 |
| 说明 | 步骤的说明。 此值已预填充，但可以手动覆盖。 |
事件管道的执行阶段
选择最适合插件用途的事件管道中的阶段。 前缀“Pre”和“Post”是指 Dataverse main （core） 操作之前或之后。 主操作是处理消息和实体组合的阶段。
| 选项 | 说明 |
|---|---|
| 预验证 | 对于初始操作，这一阶段将在主系统操作之前进行。 这提供了在进行数据库事务之前取消操作的逻辑的机会。 在其他阶段注册的扩展触发的后续操作也将通过此阶段，但会包含在调用扩展的事务中。 此阶段在预先进行安全检查之前发生，以验证调用或登录用户是否具有执行预期作的正确权限。 |
| PreOperation | 发生在主系统操作之前，并且在数据库事务中。 如果要更改消息中包含的实体的任何值，则应在此处执行此作。 请避免在此处取消操作。 取消操作将会触发事务回滚，并且会产生重大的性能影响。 |
| PostOperation | 在主要系统操作之后发生，并且在数据库事务中进行。 使用此阶段可以修改消息的任何属性，然后再将其返回到调用方。 避免对消息中包含的实体应用更改，因为这将触发新的更新事件。 在 PostOperation 阶段中，可以注册使用异步执行模式的步骤。 这些步骤将使用异步服务在数据库事务外部运行。 如果插件旨在执行更新作并在 用户（SystemUser） 实体的“创建”消息上注册，则必须在注册插件时使用异步模式。 详细信息： 异步服务。 |
详细信息：事件执行管道
执行模式
有两种执行模式 - 异步和同步。
| 选项 | 说明 |
|---|---|
| 异步 | 要应用的业务逻辑的执行上下文和定义将移动到系统作业队列，该队列将在主操作完成后执行。 |
| 同步 | 插件会根据执行阶段和执行顺序即时运行。 整个操作将等待它们完成。 |
只能为 PostOperation 阶段注册异步插件。 有关系统作业工作原理的详细信息，请参阅 异步服务
特殊步骤注册方案
在某些情况下，步骤的注册和数据表的组合并不明显。 这是系统在内部设计方式的结果，即表或操作之间存在特殊关系。 此处提供的信息标识了这些情况，并提供步骤注册指南。
- 在某些情况下，可以调用为 Update 事件注册的插件两次。 详细信息：专业化更新操作的行为
- 在帐户或联系人上注册插件步骤，以便在要处理对customeraddress、leadaddress、publisheraddress或competitoraddress记录的数据更改时使用。
部署
| 选项 | 说明 |
|---|---|
| 服务器 | 插件在 Dataverse 服务器上运行。 |
| 脱机 | 当用户处于脱机模式时，该插件在Outlook客户端的Dynamics 365中运行。 |
设置配置数据
在 PRT 中，“非安全配置”和“安全配置”字段可以用于指定要传递给特定步骤插件的配置数据。
注释
导出解决方案时，步骤注册中不包括安全配置数据。
可以编写插件以接受构造函数中的字符串值，以使用此数据来控制插件对步骤的工作方式。 详细信息： 将配置数据传递到插件
定义实体图像
在插件中，可能需要引用未包含在操作中的主表属性值。 例如，在操作中 Update ，你可能想要知道值在更改之前的值，但执行上下文不提供此信息，它只包括更改的值。
如果在执行管道的 PreValidation 或 PreOperation 阶段中注册了插件步骤，则可以使用 IOrganizationService 实例检索属性的当前值，这对于性能来说不是一个好的做法。 更好的做法是通过插件步骤注册来定义预实体图像。 在操作前，实体前图像会捕获表中你感兴趣的字段的“快照”，以便于与被修改的值进行比较。
重要
创建实体映像时的默认行为是选择所有列。 请勿使用此默认行为。 返回所有列会对性能产生负面影响。 只包含插件逻辑必需的那些列。
支持实体图像的消息
在 Dataverse 中，只有以下消息支持实体映像：
| 消息 | Request 类属性 | 说明 |
|---|---|---|
Assign |
Target |
指定的表 |
Create |
Target |
创建的表。 |
Delete |
Target |
已删除的表。 |
DeliverIncoming |
EmailId |
传递的电子邮件 ID。 |
DeliverPromote |
EmailId |
传递的电子邮件 ID。 |
Merge |
Target 或 SubordinateId |
父表，子表中的数据正在合并或正在合并到父表中的子表。 |
Route |
Target |
正在路由的项。 |
Send |
FaxId、EmailId 或 TemplateId |
要发送的物品。 |
SetState |
EntityMoniker |
为其设置状态的表。 |
Update |
Target |
更新后的表。 |
实体图像的类型
实体映像有两种类型的： Pre Image 和 Post Image。 配置这些映像时，这些映像将分别在执行上下文中作为 PreEntityImages 属性和 PostEntityImages 属性提供。 顾名思义，这些快照表示表在主操作之前和之后的外观。 配置实体映像时，您将定义一个表别名* 值，此值是用于通过PreEntityImages或PostEntityImages属性访问特定实体映像的关键键值。
映像的可用性
配置实体映像时，必须认识到可用的实体映像的类型取决于已注册步骤的阶段和操作类型。 例如：
- 由于该表尚不存在，因此无法获取消息的预映像
Create。 - 由于表格将不再存在，您无法为消息添加
Delete。 - 只能在执行管道的 PostOperation 阶段注册的步骤使用 Post Image，因为在事务完成之前无法知道表属性会是什么。
-
Update对于在 PostOperation 阶段注册的操作，可以同时具有预映像和后映像。
添加实体图像
使用 Visual Studio 的 Power Platform Tools 扩展将实体图像添加到插件步骤。
或者，您可以使用插件注册工具，在教程的“更新插件”部分下的“添加映像”部分中按照说明将实体映像添加到步骤中。
向解决方案添加步骤
如 将程序集添加到解决方案中所述， 插件程序集 是可添加到非托管解决方案的解决方案组件。 SDK 消息处理步骤 也是解决方案组件，还必须添加到非托管解决方案中才能分发。
向解决方案添加步骤的过程类似于添加程序集。 你将使用 “添加现有” 命令将其移动到所需的非托管解决方案中。 唯一的区别是，如果你尝试添加步骤但尚未添加包含步骤中使用的类的程序集，系统将提示你添加缺少的必需组件。
如果遇到这种情况，通常应选择 “确定 ”将程序集引入非托管解决方案。 如果解决方案被设计为安装在已经有其他包含该程序集的解决方案的环境中，这是你唯一不选择它的情况。
同样，应注意，从解决方案中删除程序集不会删除依赖于它的任何步骤。
为步骤设置用户模拟
运行并登录到目标 Dataverse 环境的 插件注册工具 后，可以继续设置或更改插件步骤注册。 在本节中，我们将讨论如何更改插件执行操作时所代表的用户。 执行由插件启动的数据操作的用户，即为有效用户。 默认情况下，调用用户（在 Dataverse 中调用操作的用户）是上述操作的所有者。 但是，可以在步骤注册中指定其他用户。 需要具有系统管理员或系统定制器安全角色，或者包含 prvSetImpersonatingUserIdOnSdkMessageProcessingStep 权限的任何角色才能执行此操作。
设置插件步骤的用户上下文：
- 展开程序集视图中的目标插件程序集节点，直到看到所需的（步骤）注册节点。
- 选择步骤节点，然后在上下文菜单或工具栏中选择 “更新 ”。
- 从“ 在用户的上下文标签中运行 ”旁边的可用用户的下拉列表中选择一个用户。
- 选择 “更新步骤”。
详细信息： 模拟用户
更新程序集
更改并重新生成以前注册的程序集时，需要更新它。 请参阅教程：更新插件中的更新插件程序集注册步骤。
程序集版本控制
如果要更改作为已部署的托管解决方案的一部分的插件程序集，则需要考虑更新该托管解决方案时更改可能产生的影响。 程序集的版本将控制行为。
可以使用在Microsoft Visual Studio项目的 major.minor.build.revision 文件中定义的 Assembly.info 的语义版本控制格式对插件程序集进行版本控制。 根据较新的解决方案中程序集版本号的更改部分，在通过导入更新现有解决方案时，以下行为适用。
生成或修订程序集版本号已更改
这被视为原地升级。 导入包含已更新程序集的解决方案时，将删除程序集的较旧版本。 旧解决方案中的任何预先存在的步骤都会自动更改，以引用较新版本的程序集。
主程序集或次要程序集版本号已更改
导入包含修改后的程序集的更新解决方案时，该程序集被视为与现有解决方案中该程序集的以前版本不同的程序集。 现有解决方案中的插件注册步骤将继续引用程序集的早期版本。 如果希望以前的程序集的现有插件注册步骤指向修订的程序集，则需要使用插件注册工具手动更改步骤配置，以引用修订后的程序集类型。 在将更新的程序集导出到解决方案以供以后导入之前，应执行此操作。
注销或禁用插件和组件
可以使用插件注册工具（PRT）注销或禁用插件及其组件。
重要
无法再注销或禁用 Microsoft 或开箱即用的系统插件和系统步骤。 以前，你能够注销或禁用某些 Microsoft.* 和其他现用系统插件。我们已将此行为更改为不再允许此行为。 由于取消注册或禁用这些插件或步骤会导致产品功能无法按预期工作，因此发生了功能更改。 如果需要注销或禁用此类插件或步骤，请提交Microsoft支持请求。
禁用或启用插件步骤
运行并登录到目标 Dataverse 环境的 插件注册工具 后，可以继续禁用或启用插件步骤。 当 Dataverse 处理步骤中指定的实体和消息组合时，禁用步骤实际上会关闭插件的执行。
重要
禁用插件可能会对应用、解决方案或 Dataverse 系统的功能产生负面影响。 在继续操作之前，请确保了解含义。
若要禁用或启用已注册的插件步骤，请执行以下步骤：
- 在程序集视图中展开目标插件程序集节点，直至您看到所需的步骤注册节点。
- 选择该步骤，然后在上下文菜单或工具栏中选择“启用或禁用”。
还可以使用 Activate 和 Deactivate 命令选项禁用或启用旧 Dataverse 解决方案资源管理器 用户界面中的步骤。
在Power Apps中，使用所选步骤的“关闭”和“打开”选项禁用或启用插件步骤。 可以通过先导航到 解决方案、选择解决方案，然后在左侧 “对象 ”窗格中选择 “插件”步骤来访问步骤选项。
取消注册组件
PRT 提供注销程序集、类型、步骤和图像的命令。 请参阅教程中的 “取消注册程序集”、“插件”和步骤 说明 ：更新过程的插件 。
这些操作是 PluginAssembly、 PluginType、 SdkMessageProcessingStep 和 SdkMessageProcessingStepImage 表上的删除操作。
还可以删除解决方案资源管理器中的 插件程序集 和 SDK 消息处理步骤 ，以实现相同的结果。 下图显示了名为 Common Data Service 默认解决方案的自定义解决方案。
注释
无法删除（注销）任何插件程序集，因为现有SDK 消息处理步骤依赖于它们。 实体图像无法单独删除，但在删除使用它们的任何步骤时，它们也会被删除。