Microsoft Dynamics CRM – 插件

插件是与 Microsoft Dynamics CRM 集成以修改或扩展平台标准行为的自定义业务逻辑。插件充当事件处理程序并注册为在 CRM 中的特定事件上执行。插件是用 C# 或 VB 编写的，可以在同步或异步模式下运行。

您将编写插件的一些场景是 –

• 您希望在创建或更新 CRM 记录时执行一些业务逻辑，例如更新记录的某些字段或更新相关记录等。

• 您希望针对某些事件（例如保存或更新记录）调用外部 Web 服务。

• 您希望在打开任何记录时动态计算字段值。

• 您希望自动化流程，例如针对 CRM 中的某些事件向您的客户发送电子邮件。

事件框架

CRM 中的事件处理框架通过将其传递到事件执行管道来处理同步和异步插件请求。每当事件触发插件逻辑时，都会向 CRM 组织 Web 服务发送一条消息，其他插件或平台的任何核心操作可以在其中读取或修改该消息。

插件管道阶段

整个插件管道分为多个阶段，您可以在其中注册自定义业务逻辑。指定的管道阶段指示插件代码在插件执行周期的哪个阶段运行。在下表中所有指定的管道阶段中，您只能在事件前和事件后注册您的自定义插件。您无法在 Platform Core Main Operations 上注册插件。

每当 CRM 应用程序调用事件（如保存或更新记录）时，就会发生以下操作序列 –

• 事件触发 Web 服务调用，执行通过事件管道阶段（事件前、平台核心操作、事件后）传递。

• 信息在内部被打包成一个OrganizationRequest消息，最终发送到内部CRM Web服务方法和平台核心操作。

• OrganizationRequest 消息首先由事件前插件接收，它可以在将信息传递给平台核心操作之前修改信息。平台核心操作后，将消息打包为OrganizationResponse，传递给后期操作插件。后操作插件可以选择修改此信息，然后再将其传递给异步插件。

• 插件以上下文对象的形式接收此信息，该对象传递给 Execute 方法，然后进行进一步处理。

• 在所有插件处理完成后，执行将传递回触发事件的应用程序。

插件消息

消息是插件（或业务逻辑）注册的事件。例如，您可以在 Create Message of Contact 实体上注册一个插件。每当创建新的联系人记录时，这都会触发业务逻辑。

对于自定义实体，以下是基于实体是用户所有还是组织所有的受支持消息。

对于默认的现成实体，支持的消息超过 100 条。其中一些消息适用于所有实体，而其中一些消息特定于某些实体。您可以在 SDK 内的 excel 文件中找到支持消息的完整列表：SDK\Message-entity support for plugins.xlsx

编写插件

在本节中，我们将学习编写插件的基础知识。我们将创建一个示例插件，该插件创建一个任务活动以在新客户添加到系统时跟进客户，即每当在 CRM 中创建新的 Contactrecord 时。

首先，您需要包含对Microsoft.Xrm.Sdk命名空间的引用。CRM SDK 包含所有必需的 SDK 程序集。假设您已经下载并安装了第 2 章中的 SDK，打开 Visual Studio。创建一个类库类型的新项目。您可以将项目命名为 SamplePlugins，然后单击 OK。

将Microsoft.Xrm.Sdk程序集的引用添加到您的项目中。该程序集存在于SDK/Bin 中。

现在，创建一个名为PostCreateContact.cs的类并从IPlugin扩展该类。到目前为止，您的代码将类似于以下内容。

您还需要添加对 System.Runtime.Serialization 的引用。添加所需的引用后，将以下代码复制到PostCreateContact类中。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Microsoft.Xrm.Sdk;

namespace SamplePlugins {
   public class PostCreateContact:IPlugin {
      /// A plug-in that creates a follow-up task activity when a new account is created.
      /// Register this plug-in on the Create message, account entity,
      /// and asynchronous mode.

      public void Execute(IServiceProviderserviceProvider) {
         // Obtain the execution context from the service provider.
         IPluginExecutionContext context =(IPluginExecutionContext)
            serviceProvider.GetService(typeof(IPluginExecutionContext));

         // The InputParameters collection contains all the data
            passed in the message request.

         if(context.InputParameters.Contains("Target")&&
            context.InputParameters["Target"]isEntity) {
            
            // Obtain the target entity from the input parameters.
            Entity entity = (Entity)context.InputParameters["Target"];
            try {
               
               // Create a task activity to follow up with the account customer in 7 days
               Entity followup = new Entity("task");
               followup["subject"] = "Send e-mail to the new customer.";
               followup["description"] =
                  "Follow up with the customer. Check if there are any new issues
                  that need resolution.";
               
               followup["scheduledstart"] = DateTime.Now;
               followup["scheduledend"] = DateTime.Now.AddDays(2);
               followup["category"] = context.PrimaryEntityName;

               // Refer to the contact in the task activity.
               if(context.OutputParameters.Contains("id")) {
                  Guid regardingobjectid = new Guid(context.OutputParameter
                     s["id"].ToString());
                  string regardingobjectidType = "contact";
                  followup["regardingobjectid"] = 
                     new EntityReference(rega rdingobjectidType,regardingobjectid);
               }
               
               // Obtain the organization service reference.
               IOrganizationServiceFactory serviceFactory =
                  (IOrganizationSer viceFactory)serviceProvider.GetService
                  (typeof(IOrganizationServiceFactory));
               IOrganizationService service = 
                  serviceFactory.CreateOrganizationService(context.UserId);

               // Create the followup activity
               service.Create(followup);
            } catch(Exception ex) {
               throw new InvalidPluginExecutionException(ex.Message);
            }
         }
      }
   }
}

以下是此代码功能的分步说明 –

步骤 1 – 通过将 IServiceProvider 对象作为其参数来实现 Execute 方法。服务提供者包含对您将在插件中使用的许多有用对象的引用。

Step 2 – 使用 IServiceProvider 的 GetService 方法获取 IPluginExecutionContext 对象。

Step 3 – 从上下文对象的 InputParameters 集合中获取目标实体的对象。这个实体类对象指的是我们的插件将在其上注册的联系人实体记录。

第 4 步– 然后创建任务实体的对象并设置适当的主题、描述、日期、类别和关于对象 ID。aboutobjectid 指示正在为哪个联系人记录创建此活动记录。您可以看到代码使用 context.OutputParameters 获取父 Contact 记录的 id，并将其与您创建的 Task 实体记录相关联。

第 5 步– 使用 IServiceProvider 对象创建 IOrganizationServiceFactory 对象。

第 6 步– 使用 IOrganizationServiceFactory 对象创建 IOrganizationService 对象。

步骤 7 – 最后，使用此服务对象的 Create 方法。它创建了保存在 CRM 中的后续活动。

签署插件程序集

本节仅适用于首次注册插件程序集的情况。您需要使用密钥登录程序集才能部署插件。右键单击解决方案，然后单击属性。

从左侧选项中选择签名选项卡，然后选中“签署程序集”选项。然后，从选择强名称密钥文件选项中选择新建。

输入密钥文件名作为示例插件（这可以是您想要的任何其他名称）。取消选中使用密码保护我的密钥文件选项，然后单击确定。单击保存。

最后，构建解决方案。右键单击 → 构建。构建解决方案将生成程序集 DLL，我们将在下一章中使用它来注册此插件。

插件中的异常处理

通常情况下，您的插件逻辑需要处理运行时异常。对于同步插件，您可以返回InvalidPluginExecutionException异常，该异常将向用户显示错误对话框。错误对话框将包含您传递给异常对象的 Message 对象的自定义错误消息。

如果您查看我们的代码，我们会在 catch 块中抛出 InvalidPluginExecutionException 异常。

throw new InvalidPluginExecutionException(ex.Message); 

结论

插件对于任何自定义 CRM 实施来说绝对是至关重要的。在本章中，我们重点了解事件框架模型、管道阶段、消息和编写示例插件。在下一章中，我们将在 CRM 中注册此插件并查看它在端到端场景中的工作情况。