共用方式為

撰寫外掛程式

  • 發行項

 

發行︰ 2016年11月

適用於： Dynamics CRM 2015

角色是實作 IPlugin 介面的自訂類別。 您可以使用 .NET Framework 4.5.2 CLR-相容語言例如 Microsoft Visual C# 和 Microsoft Visual Basic .NET 編撰程式。 如要組譯外掛程式碼，您必須新增 Microsoft.Xrm.Sdk.dll 和 Microsoft.Crm.Sdk.Proxy.dll 組件參照至您的專案。 這些組件可以在 SDK\Bin SDK 資料夾中找到。下載 Microsoft Dynamics CRM SDK 套件。

本主題內容

外掛程式設計

撰寫基本外掛程式

撰寫程式碼建構函式

支援離線執行

網路存取隔離的 (沙箱) 外掛程式

使用早期繫結類型

外掛程式組件

外掛程式設計

您的外掛程式設計應該考慮在 Microsoft Dynamics CRM 2015 和 Microsoft Dynamics CRM Online 2015 更新 加入的 Web 應用程式 自動儲存 功能。 自動儲存是預設為啟用，但是可以在組織等級停用。 啟用自動儲存時就不會有儲存按鈕。 Web 應用程式會在上次為儲存變更後的 30 秒自動於表單中儲存資料。 您可以套用表單指令碼停用在表單層級上的自動儲存行為。 依據您登錄外掛程式的方是，自動儲存可能會導致頻繁呼叫外掛程式以取得個別欄位，而非外掛程式針對所有變更啟動。 您應該假設，所有使用者可以隨時儲存任何紀錄，您可以使用 Ctrl+S、透過按下儲存按鈕或使用自動儲存功能。

最好能夠在最重要的實體和特定欄位登錄您的外掛程式或工作流程。 避免將外掛程式或工作流程登錄至所有實體欄位。 您有一個在可以使用自動儲存功能前，已經實作了一個外掛程式或工作流程，您應要重新測試該程式碼，驗證是否能正確運作。 如需詳細資訊，請參閱 TechNet：管理自動儲存。

撰寫基本外掛程式

下列範例顯示在外掛程式中可以找到的一般城市碼。 在範例中，程式碼會省略任何外掛程式所要執行的自訂商務規則。 不過，程式碼會顯示實作 IPlugin 介面和所需 Execute 方法的外掛程式類型。

using System;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

public class MyPlugin: IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Extract the tracing service for use in debugging sandboxed plug-ins.
        // If you are not registering the plug-in in the sandbox, then you do
        // not have to add any tracing service related code.
        ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

        // 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"] is Entity)
        {
            // Obtain the target entity from the input parameters.
            Entity entity = (Entity)context.InputParameters["Target"];

            // Verify that the target entity represents an entity type you are expecting. 
            // For example, an account. If not, the plug-in was not registered correctly.
            if (entity.LogicalName != "account")
                return;

            // Obtain the organization service reference which you will need for
            // web service calls.
            IOrganizationServiceFactory serviceFactory = 
                (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
            IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

            try
            {
                // Plug-in business logic goes here.
            }

            catch (FaultException<OrganizationServiceFault> ex)
            {
                throw new InvalidPluginExecutionException("An error occurred in MyPlug-in.", ex);
            }

            catch (Exception ex)
            {
                tracingService.Trace("MyPlugin: {0}", ex.ToString());
                throw;
            }
        }
    }
}

Execute 方法的 IServiceProvider 參數是一種內有多種實用服務物件，可以用外掛程式存取的容器。 服務提供者包含執行內容 IOrganizationServiceFactory，ITracingService 以及更多執行個體參照。 範例程式碼示範如何從服務提供者參數取得對執行內容、IOrganizationService和 ITracingService 的參照。 如需更多關於追蹤服務的相關資訊，請參閱 偵錯外掛程式。

此執行內容包括許多關於使外掛程式執行的資訊，以及包含在訊息中且正由準銷售案源處理的訊息。 如需的更多關於資料內容的資訊，請參閱 了解傳遞至外掛程式的資料內容。

平台會在您從服務提供者取得組織 Web 服務參照時提供正確的 Web 服務 URL 以及網路認證時。 不支援具現化您自己的 Web 服務 Proxy，因為這會造成死結和驗證問題。 在您建立組織服務參照之後，您可以用方法呼叫組織 Web 服務。 您可以透過發行一個或多個訊息請求至 Web 服務在單一 Microsoft Dynamics 365 組織擷取或變更商務資料。 如需此訊息請求的詳細資訊，請參閱 使用訊息 (請求和回覆類別) 搭配 Execute 方法。

一般外掛程式應該存取內容的資訊，執行需要業務作業和處理程序例外。 如需更多關於在外掛程式中處理例外的詳細資訊，請參閱 在外掛程式中處理例外。 如需更完整的外掛程式範例請參閱，範例：建立基本外掛程式。

重要

如需改善效能，Microsoft Dynamics 365 會快取外掛程式執行個體。 外掛程式的 Execute 方法應該撰寫為無狀態，因為不會為外掛程式的每個引動過程呼叫建構函式。 此外，多個系統執行緒可能會同時執行外掛程式。 每個引動狀態資訊都儲存在內容中，所以請勿使用全域變數或試圖在下次的外掛程式引動時於成員變數中儲存任何資料，除非該資料是由設定參數為建構函式提供。 針對外掛程式登錄的變更會導致外掛程式重新初始化。

撰寫程式碼建構函式

Microsoft Dynamics 365 平台支援選用的外掛程式建構函式，可接受一或兩個字串參數。 如果您撰寫這樣的建構函式，您可以在執行階段中傳遞任何資訊字串至外掛程式中。

下列範例示範建構函式的格式。 在以下範例中，外掛程式的名稱為 SamplePlugin。

public SamplePlugin()
public SamplePlugin(string unsecure)
public SamplePlugin(string unsecure, string secure)

建構函式的第一字串參數包含公開 (不安全) 資訊。 第二字串參數不包含非公開 (安全) 資訊。 在此討論中，安全指的是特別加密的值，而不安全指的則是未加密的值。 在使用 Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access 時，安全字串不會在 Dynamics CRM for Outlook 離線時傳送給執行的外掛程式。

當指定外掛程式已登錄 Microsoft Dynamics 365 時，傳送已指定的資訊到字串中的外掛程式建構函式。 在使用外掛程式登錄工具登錄外掛程式時，您可以在 [登錄新步驟] 表單中的 [安全設定] 和 [不安全設定] 欄位輸入安全或不安全的資訊。 當以程式方式使用 Microsoft Dynamics CRM SDK 登錄外掛程式時，SdkMessageProcessingStep.Configuration 包含不安全的值且 SdkMessageProcessingStep.SecureConfigId 參照包含安全值的 SdkMessageProcessingStepSecureConfig 記錄。

支援離線執行

您可以登錄外掛程式，在線上模式、離線模式或兩者可的狀態下執行外掛程式。Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access 僅支援離線模式。 您可以透過檢查 IsExecutingOffline 屬性，用程式碼確認是否在離線模式下執行。

在您設計一個將會登錄於線上和離線執行的運用程式時，請記得外掛程式可以執行兩次。 第一次是在 Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access 離線。 外掛程式會在 Dynamics CRM for Outlook 連線時和在 Dynamics CRM for Outlook 和 Microsoft Dynamics 365 伺服器之間的同步時再次執行。 您可以檢查 IsOfflinePlayback 屬性決定外掛程式是否因為同步處理而執行。

網路存取隔離的 (沙箱) 外掛程式

若您計劃要在沙箱中註冊外掛程式，您仍能從外掛程式碼中存取 Web 位址。 您可以在外掛程式碼中使用任何提供網頁存取 .NET Framework 的類別，提供了網頁存取限制列出的 外掛程式隔離、信任和統計資料。 例如，下列外掛程式碼會下載網頁。


// Download the target URI using a Web client. Any .NET class that uses the
// HTTP or HTTPS protocols and a DNS lookup should work.
using (WebClient client = new WebClient())
{
    byte[] responseBytes = client.DownloadData(webAddress);
    string response = Encoding.UTF8.GetString(responseBytes);
System_CAPS_security 安全性 注意

對於讓沙箱的外掛程式可以存取外部 Web 服務，安裝沙箱處理服務角色的伺服器必須能顯示在網際網路中，且在帳戶中執行的沙箱服務必須可以存取網路服務。 需要連接埠 80 或 443 來對外連線。 不需要連入連線存取。 使用 Windows 防火牆控制台來為 Microsoft.Crm.Sandbox.WorkerProcess 應用程式啟用對外連線，可以在伺服器的 %PROGRAMFILES%\Microsoft Dynamics CRM\Server\bin 資料夾找到此項目。

使用早期繫結類型

若要在您的外掛程式中使用早期繫節 Microsoft Dynamics 365 中，請在您的 CrmSvcUtil 專案中內含用 Microsoft Visual Studio 程式產生類型檔案。

轉換晚期繫結實體為早期繫結實體的處理過程如下：

Account acct = entity.ToEntity<Account>();

前面的程式碼中，acct 變數是一種早期繫結類型。 所有指派給 IPluginExecutionContext 的 Entity 值必須是晚期繫結類型。 如果一個早期繫結類型指派給內容，則會發生 SerializationException。 如需詳細資訊，請參閱了解傳遞至外掛程式的資料內容。 確定您不會混用您的類型，並在晚期細節類型呼叫的場合使用早期繫結類型，如以下程式碼所顯示。

context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.

在上述的範例中，您不會想要在晚期繫結執行個體前往的外掛程式中儲存早期繫結執行個體。 這是為避免在呼叫外掛程式前，以及從外掛程式回傳至平台時，要求平台在早期繫結與晚期細節類型間轉換。

外掛程式組件

在組件中可能會有一個或多個外掛程式類型。 在外掛程式組件登錄並部署之後，外掛程式可以執行必要的作業，以回覆 Microsoft Dynamics 365 執行階段事件。

System_CAPS_security 安全性 注意

在 Microsoft Dynamics 365 中，外掛程式組件必須讓每個人都能讀取，以正確運作。 因此，安全性最佳外掛程式碼的開發作法就是不包含任何系統登入資訊、機密資訊，或是公司商務秘密。

每個外掛程式組件必須簽署，您可以使用 Microsoft Visual Studio 專案屬性表中的 [簽署] 索引標籤或是強式名稱工具，在登錄和部署至 Microsoft Dynamics 365 前處理。 如需更多關於強式名稱工具，請在 Microsoft Visual Studio 命令提示字元視窗中執行 sn.exe 程式，並不使用任何引數。

如果您的組件包含可以在 Dynamics CRM for Outlook 離線時執行的外掛程式，Microsoft Dynamics 365 平台將會把另外的安全性加在組件上。 如需詳細資訊，請參閱逐步解說：設定離線外掛程式的組件安全性。

另請參閱

外掛程式開發
了解傳遞至外掛程式的資料內容
撰寫自訂的 Azure 感知外掛程式
註冊和部署外掛程式
在外掛程式中處理例外
範例：建立基本外掛程式
範例：從沙箱化外掛程式存取 Web
執行程式碼產生工具
部落格文章：使用外掛程式修改檢視表

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權