了解傳遞至外掛程式的資料內容

 

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

當外掛程式執行以回應已註冊的執行管線事件時，會呼叫外掛程式的 Execute 方法。 該方法傳遞 IServiceProvider 物件為參數，包含許多有用的物件。 下列各節提供在執行時傳送至外掛程式的某些資訊。

本主題內容

存取外掛程式執行內容

存取組織服務

存取通知服務

輸入和輸出參數

前置和後置實體影像

存取外掛程式執行內容

IPluginExecutionContext 包含描述外掛程式執行之執行階段環境的資訊、執行管線的相關資訊，以及實體商務資訊。 內容包含在 System.IServiceProvider 參數中，透過 Execute 方法在執行階段傳送至外掛程式。

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

當外掛程式註冊的系統事件引發時，系統會透過之前提及的類別和方法，建立並填入內容並將它傳遞至外掛程式。 執行時，執行內容傳遞給管線中每個已註冊的外掛程式。 在執行管線中的每個外掛程式可以修改內容中可寫入的屬性。 例如，如果某個外掛程式註冊前置事件，另一個外掛程式註冊後置事件，後置事件外掛程式可以接受前置事件外掛程式已修改的內容。 相同情況適用在相同階段中註冊的外掛程式。

在 IPluginExecutionContext 的所有屬性都是唯讀。 不過，您的外掛程式可以修改本身是集合的這些屬性的內容。 如需無限迴圈預防的詳細資訊，請參閱 Depth。

存取組織服務

若要存取 Microsoft Dynamics 365 組織服務，則外掛程式碼必須透過 ServiceProvider.GetService 方法建立服務執行個體。

// Obtain the organization service reference.
IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

當您使用此方法時，平台為您提供正確 Web 服務 URL 與網路認證。 不支援具現化您自己的 Web 服務 Proxy，因為這會造成死結和驗證問題。

存取通知服務

同步的已註冊外掛程式可以張貼執行內容至 Microsoft Azure 服務匯流排。 傳遞至外掛程式的服務提供者物件會包含 IServiceEndpointNotificationService 的參照。 透過通知服務，同步外掛程式將代理訊息傳送至 Microsoft Azure 服務匯流排。 如需更多 Microsoft Azure 的資訊，請參閱 Azure 與 Microsoft Dynamics 365 整合。 如需撰寫可以張貼至 Microsoft Azure 服務匯流排 的外掛程式的詳細資訊，請參閱 撰寫自訂的 Azure 感知外掛程式。

輸入和輸出參數

InputParameters 屬性包含事件執行管線目前處理之要求訊息的資料。 您的外掛程式碼可以存取此資料。 屬性是類型 ParameterCollection，而存取要求資料的金鑰是要求中實際公用屬性名稱。 舉例來說，請查看 CreateRequest。CreateRequest 的一個屬性的名稱是 Target，其類型是 Entity。 這是平台目前所操作的實體。 若要存取實體的資料，您會使用名稱「Target」做為輸入參數集合的金鑰。 您也必須轉換傳回的執行個體。

// 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"];

請注意，不是所有的要求包含是類型 Entity 的 Target 屬性，因此，您必須檢視每個要求或回覆。 例如，DeleteRequest 有 Target 屬性，但是，其類型是 EntityReference。 前述程式碼範例變更如下。

// The InputParameters collection contains all the data passed in the message request.
if (context.InputParameters.Contains("Target") &&    context.InputParameters["Target"] is EntityReference)
{
    // Obtain the target entity from the input parameters.
    EntityReference entity = (EntityReference)context.InputParameters["Target"];
}

存取實體資料之後，您可以讀取並修改它。 對準銷售案源階段 10 或 20 中註冊的外掛程式所執行內容進行的任何資料變更，會在內容中傳遞至階段 30 中的核心作業。

重要

並非實體記錄所有透過內容傳遞至外掛程式的欄位皆可加以修改。 您應該檢查欄位的 IsValidForUpdate 中繼資料屬性，確認它不是設定為 false。 嘗試變更無法更新之欄位的值會造成例外狀況。

同樣地，OutputParameters 屬性包含目前透過事件執行管線傳送之回覆訊息 (例如 CreateResponse) 的資料。 不過，只有同步的後置事件和非同步的已註冊外掛程式會填入 OutputParameters，因為回覆是平台核心作業的結果。 屬性是類型 ParameterCollection，而存取回覆資料的金鑰是回覆中實際公用屬性名稱。

前置和後置實體影像

PreEntityImages 和 PostEntityImages 包含主要實體的屬性的快照，在核心平台作業之前 (前) 和之後 (後)。Microsoft Dynamics 365 會根據模擬的系統使用者的安全性權限，填入前置實體和後置實體影像。 只有設定值或是 null 的實體屬性才能用於前置或後置實體影像。 在您註冊您的外掛程式時，您可以指定要平台填入這些 PreEntityImages 和 PostEntityImages 屬性。 註冊外掛程式期間，您指定的實體別名值會做為外掛程式碼中影像集合的金鑰。

某些事件沒有影像。 例如，只有同步的後置事件和非同步的已註冊外掛程式會填入 PostEntityImages。 建立作業不支援前置影像，而刪除作業不支援後置影像。 此外，如下表所示，僅訊息的一個小部分支援前置影像和後置影像。

訊息要求	屬性	描述
AssignRequest	目標	指定的實體。
CreateRequest	目標	建立的實體。
DeleteRequest	目標	刪除的實體。
DeliverIncomingEmailRequest	EmailId	傳遞的電子郵件識別碼。
DeliverPromoteEmailRequest	EmailId	傳遞的電子郵件識別碼。
ExecuteWorkflowRequest	目標	工作流程實體。
MergeRequest	目標	上層實體，從下層實體的資料合併至其中。
MergeRequest	SubordinateId	正在合併至上層實體的下層實體。
SendEmailRequest	EmailId	傳送的實體識別碼。
SetStateRequest	EntityMoniker	設定狀態的實體。
UpdateRequest	目標	更新的實體。

相較於透過 RetrieveRequest 或 RetrieveMultipleRequest 要求取得外掛程式碼中的實體屬性，註冊前置或後置影像存取實體屬性值，會改善外掛程式效能。

安全性 注意
在執行內容中傳遞至外掛程式或自訂工作流程活動的前置影像，可能包含登入的使用者沒有存取權限的資料。Microsoft Dynamics 365 管理員和其他使用者具有高階權限，就可以註冊外掛程式以「系統」使用者帳戶執行，或者外掛程式碼可代表登入使用者做為「系統」使用者進行呼叫。 如果發生這種情況，登入使用者可以存取他們的欄位層級安全性不允許存取的資料。其他資訊：外掛程式中的模擬

另請參閱

外掛程式開發
在外掛程式中處理例外
事件執行準銷售案源
使用訊息 (請求和回覆類別) 搭配 Execute 方法
使用組織服務讀取和寫入資料或中繼資料
註冊和部署外掛程式

Microsoft Dynamics 365

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