Microsoft Dynamics CRM - 插件

---

---

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

一些您需要编写插件的情况：

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

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

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

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

事件框架

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

插件管道阶段

整个插件管道分为多个阶段，您可以在这些阶段注册您的自定义业务逻辑。指定的管道阶段指示插件执行周期的哪个阶段运行您的插件代码。在以下表格中指定的所有管道阶段中，您只能在预事件和后事件上注册自定义插件。您不能在平台核心主操作上注册插件。

每当 CRM 应用程序调用事件（例如保存或更新记录）时，将发生以下一系列操作：

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

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

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

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

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

插件消息

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

对于自定义实体，以下是根据实体是用户拥有的还是组织拥有的而支持的消息。

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

编写插件

在本节中，我们将学习编写插件的基础知识。我们将创建一个示例插件，每当向系统添加新客户（即每当在 CRM 中创建新的联系人记录时）时，它都会创建一个任务活动以跟踪客户。

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

将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方法。服务提供程序包含对您将在插件中使用的许多有用对象的引用。

步骤 2 - 使用IServiceProvider的GetService方法获取IPluginExecutionContext对象。

步骤 3 - 从上下文对象的InputParameters集合中获取目标实体的对象。此Entity类对象引用将注册我们插件的联系人实体记录。

步骤 4 - 然后，它创建一个Task实体的对象，并设置正确的主题、描述、日期、类别和regardingobjectid。regardingobjectid指示为哪个联系人记录创建此活动记录。您可以看到代码使用context.OutputParameters获取父联系人记录的ID，并将其与您创建的任务实体记录关联。

步骤 5 - 使用IServiceProvider对象创建IOrganizationServiceFactory对象。

步骤 6 - 使用IOrganizationServiceFactory对象创建IOrganizationService对象。

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

签名插件程序集

此部分仅适用于您第一次注册插件程序集的情况。您需要使用密钥登录程序集才能部署插件。右键单击解决方案并单击“属性”。

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

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

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

插件中的异常处理

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

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

throw new InvalidPluginExecutionException(ex.Message); 

结论

插件对于任何自定义 CRM 实现都至关重要。在本章中，我们重点介绍了事件框架模型、管道阶段、消息和编写示例插件。在下一章中，我们将在此 CRM 中注册此插件，并从端到端场景中看到它的运行。