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 中註冊此外掛，並從端到端場景中看到它的執行。