実行コンテキストを理解する

イベント実行パイプライン は、登録されているプラグインに、処理中の現在の操作とカスタム コードの実行環境に関する豊富なデータを渡します。 次のセクションでは、プラグインまたはカスタム ワークフロー活動に渡されるデータについて説明します。

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

プラグインでは、 IPluginExecutionContext インターフェイスを実装する変数を設定して、コード内のこのデータにアクセスします。

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

この IPluginExecutionContext は、プラグインが登録されている Stage に関する情報と、 ParentContextに関する情報を提供します。

詳細情報: ParentContext

カスタム ワークフロー アクティビティのアクセス実行コンテキスト

カスタム ワークフロー アクティビティでは、 IWorkflowContext インターフェイスを実装する変数を設定して、コード内のこのデータにアクセスします。

// Obtain the execution context using the GetExtension method.  
protected override void Execute(CodeActivityContext context)
{
 IWorkflowContext workflowContext = context.GetExtension<IWorkflowContext>();
...

このIWorkflowContextでは、カスタム ワークフロー活動が実行するワークフローについて説明します。

親コンテキスト

ParentContext では、実行するプラグインまたはカスタム ワークフロー活動をトリガーするために必要なすべての操作に関して説明します。

特定の文書化されたケースを除き、 ParentContext で見つけた値に依存してビジネス ロジックを適用しないでください。 操作が発生する特定の順序は保証されず、時間の経過と同時に変化する可能性があります。

ParentContextで見つかった値に依存することを選択した場合は、コードが潜在的な変更に適応できる回復力があることを確認する手順を実行します。 ロジックを定期的にテストして、依存する条件が時間の経過と同時に有効であることを確認します。

実行コンテキスト

IExecutionContext インターフェイスは、残りの情報を提供します。 IPluginExecutionContextクラスとIWorkflowContext クラスは、このインターフェイスを実装します。

プラグインの場合、この実行コンテキスト クラスのすべてのプロパティは、コード内でアクセスする必要がある可能性のある有用な情報を提供します。

最も重要なプロパティの 2 つには、 InputParameters プロパティと OutputParameters プロパティがあります。

よく使用する他のプロパティは、SharedVariables、PreEntityImages、および PostEntityImages です。

パラメータコレクション

実行コンテキストのすべてのプロパティは読み取り専用になっています。 しかし InputParameters、OutputParameters、および SharedVariables は、ParameterCollection 値です。 プラグインが登録されているイベント実行パイプラインのステージに応じて、これらのコレクション内の項目の値を変更することで、操作の動作を変更できます。

ParameterCollection 値は KeyValuePair 構造として定義されます。 プロパティにアクセスするには、メッセージが公開するプロパティの名前を知っている必要があります。 たとえば、Entityの一部として渡されるCreateRequest プロパティにアクセスするには、そのプロパティの名前がTargetされていることを確認する必要があります。 その後、次のようなコードを使用して、この値にアクセスできます。

var entity = (Entity)context.InputParameters["Target"];

SDK アセンブリで定義されているメッセージの名前を理解するには、Microsoft.Xrm.Sdk.Messages と Microsoft.Crm.Sdk.Messages のドキュメントを使用します。 ユーザー定義アクションについては、システムで定義されるパラメーターの名前を参照してください。

入力パラメーター

InputParameters は、Web サービスからの操作を表す OrganizationRequest.Parameters プロパティの値を表します。

「SDK for .NET でメッセージを使用する」で説明されているように、システムで発生するすべての操作は、最終的には、OrganizationRequest.IOrganizationService メソッドが処理するExecute クラスのインスタンスになります。

Event Framework で説明されているように、操作は一連のステージを経て行われます。 データがデータベースに書き込まれる前に発生するステージにプラグインを登録できます。 PreValidationおよび PreOperationステージ内で、データ操作の予測結果をコントロールできるように InputParameters の値を確認して変更できます。

InputParameters コレクション内の値が許可できない条件を表している場合は、操作をキャンセルし、エラーをユーザーに表示させる目的で、PreValidation ステージで同期プラグインを使用して InvalidPluginExecutionException をスローするか、プラグインが非同期の場合には、そのエラーをログに記録します。 詳細については、 操作の取り消しを参照してください。

出力パラメーター

OutputParameters は、操作の戻り値を表す OrganizationResponse.Results プロパティの値を表します。 OrganizationResponse から派生したそれぞれのメッセージ応答クラスには、特定のプロパティーが含まれています。 これらのプロパティにアクセスするには、 通常 、応答クラスのプロパティの名前と同じキー値を使用します。 ただし、これは常に当てはまるとは限りません。 以下のリストに、プロパティーの名前とは異なるキーを持つ、メッセージ応答クラスプロパティーを示します。

システムはデータベース トランザクションの後まで OutputParameters を設定しないため、 PostOperation ステージに登録されているプラグインでのみ使用できます。 操作により戻った値を変更する場合、OutputParameters 内で変更できます。

共有変数

SharedVariables プロパティを使用して、API またはプラグインから実行パイプラインの後半で発生するステップにデータを渡します。 このプロパティは ParameterCollection 値であるため、プラグインはプロパティを追加、読み取り、または変更して、後続の手順でデータを共有できます。

次の例は、PrimaryContact ステップに登録されているプラグインから PostOperation ステップに値を渡す方法を示しています。

public class PreOperation : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Obtain the execution context from the service provider.
        Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
            serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));

        // Create or retrieve some data that will be needed by the post event
        // plug-in. You could run a query, create an entity, or perform a calculation.
        //In this sample, the data to be passed to the post plug-in is
        // represented by a GUID.
        Guid contact = new Guid("{74882D5C-381A-4863-A5B9-B8604615C2D0}");

        // Pass the data to the post event plug-in in an execution context shared
        // variable named PrimaryContact.
        context.SharedVariables.Add("PrimaryContact", (Object)contact.ToString());
    }
}

public class PostOperation : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Obtain the execution context from the service provider.
        Microsoft.Xrm.Sdk.IPluginExecutionContext context = (Microsoft.Xrm.Sdk.IPluginExecutionContext)
            serviceProvider.GetService(typeof(Microsoft.Xrm.Sdk.IPluginExecutionContext));

        // Obtain the contact from the execution context shared variables.
        if (context.SharedVariables.Contains("PrimaryContact"))
        {
            Guid contact =
                new Guid((string)context.SharedVariables["PrimaryContact"]);

            // Do something with the contact.
        }
    }
}

API から共有変数を渡す

API を呼び出すときに共有変数を導入するには、Web API または SDK for .NET のキーワード tag を使用して文字列値を渡します。

共有変数コレクション内のこの値には、 tag キーを使用してアクセスできます。 一度設定すると、この値を変更することはできません。

詳細については、「 プラグインの実行コンテキストに共有変数を追加する」を参照してください。

エンティティ イメージ

テーブルをパラメーターの 1 つとして含むプラグインのステップを登録する場合は、プロパティとPreEntityImagesプロパティを使用して、テーブル データのコピーをPostEntityImagesまたはイメージとして含めることができます。

このデータは、イベント パイプラインを介して渡されるテーブル データの比較ポイントを提供します。 これらのイメージを使用すると、プラグインにコードを含めて属性値を比較するだけのテーブルを取得するよりもはるかに優れたパフォーマンスが得られます。

エンティティ イメージを定義するには、固有イメージにアクセスするために使用できるエンティティ エイリアス値を指定します。 たとえば、プレエンティティ イメージをエイリアス「a」で定義する場合、次のコードを使用して、name 属性値にアクセスすることができます。

var oldAccountName = (string)context.PreEntityImages["a"]["name"];

詳細:

• エンティティ イメージの定義
• ワークフロー拡張に関するエンティティ イメージ

関連項目

イベント フレームワーク
プラグインを記述する