プラグインに渡されるデータ コンテキストについて

 

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

プラグインが登録されている実行パイプライン イベントに応答してプラグインが実行されると、プラグインの Execute メソッドが呼び出されます。 このメソッドは、IServiceProvider オブジェクトをパラメータとして渡します。これには多数の有用なオブジェクトが含まれています。 次のセクションでは、実行時にプラグインに渡される情報の一部を説明します。

このトピックの内容

プラグイン実行コンテキストへのアクセス

組織サービスへのアクセス

通知サービスへのアクセス

入力および出力パラメーター

プレ エンティティ イメージとポスト エンティティ イメージ

プラグイン実行コンテキストへのアクセス

IPluginExecutionContext には、プラグインを実行する実行時環境に関する情報、実行パイプラインに関する情報、およびエンティティの事業情報が含まれます。 このコンテキストは、Execute メソッドによってプラグインに実行時に渡される System.IServiceProvider パラメーターに格納されています。

// 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 サービス プロキシのインスタンスを作成することは、デッドロックと認証の問題が発生するためにサポートされていません。

通知サービスへのアクセス

非同期に登録されたプラグインは Microsoft Azure サービス バス に実行コンテキストを投稿できます。 プラグインに渡されるサービス プロバイダ オブジェクトには、 IServiceEndpointNotificationService への参照が含まれています。 同期プラグインが仲介メッセージを Microsoft Azure サービス バス へ送ることができるのは、通知サービスによってです。Microsoft Azure の詳細については、「Microsoft Dynamics 365 との Azure 統合」を参照してください。Microsoft Azure サービス バス への投稿を可能にするプラグインの記述方法の詳細については、「Azure 対応のカスタム プラグインの記述」を参照してください。

入力および出力パラメーター

InputParameters プロパティには、イベント実行パイプラインによって現在処理されている要求メッセージ内のデータが格納されます。 プラグインのコードでこのデータにアクセスできます。 このプロパティは ParameterCollection 型で、要求データにアクセスするためのキーは要求での実際のパブリック プロパティの名前です。 例としては、CreateRequest を参照してください。CreateRequest の 1 つのプロパティは 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	配布された電子メール ID。
DeliverPromoteEmailRequest	EmailId	配布された電子メール ID。
ExecuteWorkflowRequest	達成目標	ワークフロー エンティティ。
MergeRequest	達成目標	子エンティティからのデータが統合される親エンティティ。
MergeRequest	SubordinateId	親エンティティに統合される子エンティティ。
SendEmailRequest	EmailId	送信済みのエンティティ ID。
SetStateRequest	EntityMoniker	状態が設定されるエンティティ。
UpdateRequest	達成目標	更新されたエンティティ。

プレ イメージまたはポスト イメージに登録することによってエンティティ属性値にアクセスすると、プラグイン コードから RetrieveRequest 要求または RetrieveMultipleRequest 要求を使ってエンティティの属性を取得した場合と比べて、プラグインのパフォーマンスが向上します。

セキュリティ メモ
実行コンテキストでプラグインまたはユーザー定義ワークフロー活動に対して渡されるプレ イメージには、ログオンしているユーザーがアクセスするための特権を持たないデータを含む場合があります。Microsoft Dynamics 365 管理者および高レベルのアクセス許可を持つ他のユーザーは、「システム」ユーザー アカウントで実行するプラグインに登録することができます。または、プラグイン コードはログオンしているユーザーのために「システム」ユーザーとして呼び出しを実行することができます。 そうなった場合、ログオンしたユーザーは、フィールド レベルのセキュリティではアクセスが許されないデータにアクセスできます。詳細:プラグインの偽装

関連項目

プラグインの開発
プラグインでの例外の処理
イベント実行パイプライン
Execute メソッドでメッセージ (要求クラスおよび応答クラス) を使用する
組織サービスを使用したデータまたはメタデータの読み取りと書き込み
プラグインの登録および展開

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 著作権