偵錯外掛程式

 

發行︰ 2016年11月

適用於： Dynamics CRM 2015

下列步驟說明如何偵錯在 Microsoft Dynamics CRM 2015 內部部署上執行的外掛程式。 若要偵錯在 Microsoft Dynamics CRM Online 沙箱中執行的外掛程式，則必須使用追蹤，如本主題中稍後描述。

本主題內容

Debug a plug-in

偵錯沙箱化外掛程式

記錄與追蹤

偵錯外掛程式

1. 註冊與部署外掛程式組件。

   如果在相同位置有組件的其他複本，而且不可以覆寫該複本，因為它是 Microsoft Dynamics 365 鎖定，您必須重新啟動執行外掛程式的服務處理序。 請參閱下表正確的服務處理序。其他資訊：註冊和部署外掛程式

2. 設定偵錯工具。

   將偵錯工具附加至執行您的外掛程式的 Microsoft Dynamics 365 伺服器處理序。 請參閱下表識別處理序。

   外掛程式註冊設定	服務處理
   線上	w3wp.exe
   離線	Microsoft.Crm.Application.Hoster.exe
   非同步已註冊的外掛程式 (或自訂工作流程組件)	CrmAsyncService.exe
   沙箱 (隔離模式)	Microsoft.Crm.Sandbox.WorkerProcess.exe

   如果有多個處理序執行同一個可執行檔，例如多個 w3wp.exe 處理序，將偵錯工具附加至執行可執行處理序的所有執行個體。 接著，在外掛程式碼中設定一個或多個中斷點。

3. 測試外掛程式。

   執行 Microsoft Dynamics 365 應用程式，或使用 SDK 的其他自訂應用程式，並執行導致外掛程式執行所需的任何動作。 例如，如果外掛程式註冊用於客戶建立事件，建立新的客戶。

4. 偵錯您的外掛程式碼。

   對您的程式碼進行所有必要的變更，使其如預期執行。 如果變更代碼，請將程式碼編譯為組件，並視需要重複此程序的步驟 1 到 4。 不過，如果變更外掛程式組件的主要或次要版本號碼，您必須取消註冊組件的舊版並註冊新版本。其他資訊：註冊和部署外掛程式

5. 在資料庫中註冊外掛程式。

   在外掛程式的編輯/編譯/部署/測試/偵錯週期完成之後，取消註冊 (磁碟上) 外掛程式組件，然後在 Microsoft Dynamics 365 資料庫中重新註冊外掛程式。其他資訊：註冊和部署外掛程式

提示

偵錯資料庫部署的外掛程式是可能的。 已編譯外掛程式組件的符號檔案 (.pdb) 必須複製至伺服器的 <crm-root>\Server\bin\assembly 資料夾，而且必須重新啟動 Internet Information Services (IIS)。 在偵錯完成後，您必須移除符號檔案並重新設定 IIS，避免執行外掛程式的處理序耗用其他記憶體。

如需使用外掛程式分析工具來偵錯外掛程式的詳細資訊，請參閱分析外掛程式效能。

偵錯沙箱化外掛程式

在第一次執行沙箱化外掛程式之前執行這些步驟是很重要的。 如果外掛程式已執行時，變更組件的程式碼 (導致伺服器上組件的雜湊變更) 或重新啟動沙箱伺服器的 Microsoft Dynamics 365 沙箱處理服務。

設定伺服器

沙箱主機處理序監控執行外掛程式的沙箱工作者處理序。 主機處理序檢查外掛程式是否停止回應，是否超過記憶體閾值及其他。 如果工作者處理序超過 30 秒沒有回應，則會關閉它。 為了偵錯沙箱外掛程式，必須停用此關閉功能。 若要停用關閉功能，設定下列登錄機碼為 1 (DWORD)：

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSCRM\SandboxDebugPlugins

偵錯外掛程式

執行下列步驟，偵錯沙箱化外掛程式。

1. 在沙箱中 (隔離模式) 註冊外掛程式，並將其部署至 Microsoft Dynamics 365 伺服器資料庫。

2. 將已編譯外掛程式組件的符號檔案 (.pdb) 複製至執行沙箱工作者處理序 (名稱為 Microsoft.Crm.Sandbox.WorkerProcess.exe) 之伺服器的 server\bin\assembly 資料夾。 這是裝載沙箱處理服務角色的伺服器。

3. 遵循本主題開頭步驟 2 到 4 的指示執行。

如需使用外掛程式分析工具來偵錯外掛程式的詳細資訊，請參閱分析外掛程式效能。

記錄與追蹤

相較於在 Microsoft Visual Studio 中偵錯，對外掛程式或自訂工作流程活動 (自訂程式碼) 進行疑難排解的另一種方法是使用追蹤。 追蹤可幫助開發人員記錄執行階段自訂資訊，協助診斷程式碼失敗的原因。 追蹤特別適用於疑難排解 Microsoft Dynamics CRM Online 註冊的自訂程式碼，因為這是該案例唯一支援的疑難排解方法。 追蹤可針對沙箱 (部分信任) 和完全信任的註冊自訂程式碼支援，以及在同步處理或非同步處理執行時。 追蹤不支援在 Microsoft Dynamics CRM for Outlook 或其他行動用戶端執行的自訂程式碼。

Microsoft Dynamics 365 的執行階段追蹤資訊記錄是由名為 ITracingService 的服務提供。 自訂程式碼提供給此服務的資訊可記錄在三個不同的地方，如此處所識別。

• 追蹤記錄

  PluginTraceLog 類型的追蹤記錄可在 Web 應用程式中找到，藉由導覽至 [設定] 並選擇 [外掛程式追蹤記錄] 磚。 磚只有在指派給您的資訊安全角色具備存取追蹤記錄實體記錄的權限時，才可看見。 這些記錄的寫入是由下一節中提及的追蹤設定所控制。 如需所需權限的詳細資訊，請參閱 TraceLog entity privileges。

  注意

  追蹤記錄功能於 Microsoft Dynamics CRM Online 2015 更新 1 中導入，不適用於內部部署的部署。

  追蹤記錄會佔用組織的儲存空間，尤其是產生許多追蹤和例外狀況時。 您應只針對偵錯和疑難排解開啟追蹤記錄，並於調查完成後將它關閉。

• 錯誤對話方塊

  傳回例外狀況至平台的同步註冊外掛程式或自訂工作流程活動，會導致在 Web 應用程式中對登入的使用者顯示錯誤對話方塊。 使用者可以選擇選取對話方塊中的 [下載記錄檔] 按鈕，檢視包含例外狀況和追蹤輸出的記錄檔。

• 系統作業

  若是傳回例外狀況的非同步註冊外掛程式或自訂工作流程活動，追蹤資訊會在 Web 應用程式中 [系統作業] 表單的 [詳細資料] 區域中顯示。

啟用追蹤記錄

若要在支援此功能的組織中啟用追蹤記錄，請在 Web 應用程式中導覽至 [設定] > [管理] > [系統設定]。 在 [自訂] 索引標籤中，尋找標籤為 [啟用記錄到外掛程式追蹤記錄] 的下拉式功能表，並選擇其中一個可用的選項。

選項	描述
關閉	寫入追蹤記錄已停用。 不會建立任何 PluginTraceLog 記錄。 不過，自訂程式碼仍然可以呼叫 Trace 方法，即使不會寫入任何記錄。
例外狀況	如果例外狀況從自訂程式碼傳回至平台，則追蹤資訊會寫入記錄檔中。
全部	當程式碼完成或例外狀況從自訂程式碼傳回至平台時，追蹤資訊就會寫入記錄檔中。

如果追蹤記錄設定設為 [例外狀況] 且您的自訂程式碼將例外狀況傳回至平台，則會建立追蹤記錄，且追蹤資訊也會寫入另一個位置。 若是同步執行的自訂程式碼，則會使用錯誤對話方塊對使用者顯示資訊，若是非同步程式碼，則資訊會寫入相關的系統作業中。

根據預設，系統管理員和系統自訂員角色具有必要的權限，可變更追蹤記錄設定，該設定儲存於 TraceSettings 實體記錄中。 追蹤設定的適用範圍包括整個組織。

寫入追蹤服務

在寫入追蹤服務之前，您必須先從傳遞的執行內容中擷取追蹤服務物件。 之後只要新增 Trace 呼叫至您的自訂程式碼的適當位置，就能在該方法呼叫中傳遞任何相關的診斷資訊。

//Extract the tracing service for use in debugging sandboxed plug-ins.
ITracingService tracingService =
    (ITracingService)serviceProvider.GetService(typeof(ITracingService));

// Obtain the execution context from the service provider.
IPluginExecutionContext context = (IPluginExecutionContext)
    serviceProvider.GetService(typeof(IPluginExecutionContext));

// For this sample, execute the plug-in code only while the client is online. 
tracingService.Trace("AdvancedPlugin: Verifying the client is not offline.");
if (context.IsExecutingOffline || context.IsOfflinePlayback)
    return;

// 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.
    tracingService.Trace
        ("AdvancedPlugin: Getting the target entity from Input Parameters.");
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the image entity from the Pre Entity Images.
    tracingService.Trace
        ("AdvancedPlugin: Getting image entity from PreEntityImages.");
    Entity image = (Entity)context.PreEntityImages["Target"];

接著，建置和部署外掛程式或自訂工作流程活動。 在執行自訂程式碼的過程中，Trace 方法呼叫中提供的資訊會由 ITracingService 寫入追蹤記錄實體記錄中 (如果組織支援且已啟用)，而且也可在 Web 對話方塊或系統作業中對使用者提供，如上一節所述。 寫入追蹤記錄的追蹤資訊是在追蹤設定中設定。 如需詳細資訊，請參閱啟用追蹤記錄。

注意

如果您的自訂程式碼是在資料庫交易內執行，而發生例外狀況導致交易回復，則程式碼所做的所有實體資料變更都將復原。 不過，回復完成後，PluginTraceLog 記錄將會保留。

關於追蹤服務

ITracingService 會透過 Trace 方法將收到的資訊分批。 在自訂程式碼成功執行至完成或擲回例外狀況之後，資訊就會寫入新的 PluginTraceLog 記錄中。

PluginTraceLog 記錄的存留期有限。 大量刪除背景工作每天執行一次，刪除建立之後超過 24 小時的記錄。 此工作可依需要停用。

另請參閱

外掛程式開發
分析外掛程式效能
註冊和部署外掛程式
事件執行準銷售案源
撰寫外掛程式
外掛程式隔離、信任和統計資料
PluginTraceLog 實體訊息和方法

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