実行コンテキストを理解する
イベント実行パイプライン は、登録されているプラグインに、処理中の現在の操作とカスタム コードの実行環境に関する豊富なデータを渡します。 次のセクションでは、プラグインまたはカスタム ワークフロー活動に渡されるデータについて説明します。
プラグインの場合
プラグインを使用して、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 を参照してください。 |
| StageName | プロセス インスタンスのステージ情報を入手します。 |
| WorkflowCategory | プロセス インスタンスのプロセスのカテゴリ情報を入手します。これは、ワークフローまたはダイアログです (削除)。 |
| WorkflowMode | ワークフローを実行する方法を示します。 0 = 非同期、1 = 同期 |
ParentContext
ParentContext では、実行するプラグインまたはカスタム ワークフロー活動をトリガーするために必要なすべての操作に関して説明します。
確認済みの特定のケースを除けば、ParentContext で見つける値への依存関係を取り入れるのを防いで自分のビジネス ロジックを適用する必要があります。 動作が発生する特定の順序は保証されないため、時間の経過に伴って変化する場合があります。
ParentContext にある値の依存関係を取得するような選択をすると、コードが可能性がある変更に適応するような弾力性があることを保証するための手順を実行する必要があります。 依存する条件が時が経過しても効果性を保持することを確認するためにロジックを定期的にテストする必要があります。
ExecutionContext
ここでの残りの説明は、この IPluginExecutionContext および IWorkflowContext クラスが実装する IExecutionContext インターフェイスを用いて説明します。
プラグインに関しては、この実行コンテキスト クラスのすべてのプロパティで、自分のコードでアクセスする際に必要となり得る有用な情報が提供されます。
注意
カスタム ワークフロー活動に関しては、これらのプロパティは一般的に使用されません。
最も重要な 2 つは、InputParameters および OutputParameters プロパティです。
よく使用する他のプロパティは、SharedVariables、PreEntityImages、および PostEntityImages です。
ヒント
実行コンテキストに渡されたデータを視覚化する良い方法は、プラグイン登録ツールの一部として使用できるプラグイン プロファイラー ソリューションをインストールすることです。 プロファイラーは、コンテキスト情報のほか、デバッグできるようにローカルでイベントを再現できる情報も取得します。 プラグイン登録ツール内で、ワークフローを開始したイベントの全データを含む XML ドキュメントをダウンロードできます。 詳細: プラグイン プロファイル データの表示
ParameterCollections
実行コンテキストのすべてのプロパティは読み取り専用になっています。 しかし InputParameters、OutputParameters、および SharedVariables は、ParameterCollection 値です。 プラグインが登録されているイベント実行パイプラインのステージに応じて、運用動作を変更するためにこれらのコレクションの項目の値を操作することができます。
ParameterCollection 値は KeyValuePair 構造として定義されます。 プロパティにアクセスするために、メッセージによって公開されるプロパティの名前について知る必要があります。 たとえば、CreateRequest の一部として渡す Entity プロパティにアクセスするには、そのプロパティの名前が Target であることを確認する必要があります。 次に、このようなコードを使用して、この値にアクセスできます:
var entity = (Entity)context.InputParameters["Target"];
SDK アセンブリで定義されているメッセージの名前を理解するには、Microsoft.Xrm.Sdk.Messages と Microsoft.Crm.Sdk.Messages のドキュメントを使用します。 ユーザー定義アクションについては、システムで定義されるパラメーターの名前を参照してください。
InputParameters
InputParameters は、OrganizationRequest.Parameters の値を表します Web サービスから入力する操作を表すプロパティ。
メッセージを .NET 用 SDK と共に使用する で説明されているように、システムで発生するすべての操作は最終的に、IOrganizationService.Execute よって処理されている OrganizationRequest クラスのインスタンスです。 メソッド。
イベント フレームワーク で説明されているように、操作が一連のステージに移動し、データがデータベースに記述される前に実行するステージでプラグインを登録できます。 PreValidationおよび PreOperationステージ内で、データ操作の予測結果をコントロールできるように InputParameters の値を確認して変更できます。
InputParameters コレクションの値が許容できない条件を表す場合、操作を取り消して同期プラグインを持つユーザーにエラーを表示する InvalidPluginExecutionException (好適にはPreValidationステージで) をスローするか、またはプラグインが非同期の場合には、エラーをログ記録することができます。 詳細: 操作のキャンセル
OutputParameters
OutputParameters は、OrganizationResponse.Results の値を表します 操作の戻り値を表すプロパティ。 OrganizationResponse から派生したそれぞれのメッセージ応答クラスには、特定のプロパティーが含まれています。 これらのプロパティにアクセスするには、 通常 は応答クラスのプロパティ名と同じキー値を使用する必要があります。 ただし、これは場合によっては異なることがあります。 以下のリストに、プロパティーの名前とは異なるキーを持つ、メッセージ応答クラスプロパティーを示します。
OutputParameters はデータベースのトランザクション後まで設定されないので、PostOperationステージに登録されたプラグインに対してのみ使用できます。 操作により戻った値を変更する場合、OutputParameters 内で変更できます。
共有変数
SharedVariables プロパティは、API またはプラグインから実行パイプラインの後の発生するステップに渡すことができるデータを含めることを可能にします。 これは ParameterCollection 値なので、プラグインはプロパティを追加、読み取り、または変更して後続のステップでデータを共有できます。
次の例は、PrimaryContact 値を、PreOperation ステップから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.
}
}
}
重要
共有される変数のコレクションに追加されたデータは、シリアル化可能な種類のデータである必要があります。そうしないと、データをシリアル化する方法をサーバーが判断できず、プラグインの実行が失敗します。
注意
PreOperation または PostOperation ステージ向けに登録されたプラグインの場合、作成、更新、削除を実行する PreValidation ステージ向けに登録されたプラグインから共有された変数または RetrieveExchangeRateRequestによる変数にアクセスするには、ParentContext にアクセスする必要があります。SharedVariables コレクション。 それ以外の場合は、IPluginExecutionContext.SharedVariables にコレクションが格納されます。
API から共有変数を渡す
API を呼び出すときに共有変数を導入する必要がある場合は、Web API または .NET 用 SDK サービスのいずれかから、キーワード tag を使用して文字列の値を渡します。
この値は、tag キーを使用して共有変数コレクションでアクセス可能です。 一度設定すると、この値は変更できず、変更不可能です。
詳細: 共有された変数をプラグイン実行コンテキストに追加する
エンティティ イメージ
テーブルをパラメータの 1 つとして含むプラグインのステップを登録すると、PreEntityImages および/または PostEntityImages プロパティを使用してテーブル データのコピーをスナップショットまたはイメージとして含めるように指定するオプションがあります。
このデータは、イベント パイプラインを介して渡されるテーブル データの比較ポイントを提供します。 これらのイメージを使用すると、プラグインにコードを含めて属性値を比較するだけのテーブルを取得するよりもはるかに優れたパフォーマンスが得られます。
エンティティ イメージを定義するには、固有イメージにアクセスするために使用できるエンティティ エイリアス値を指定します。 たとえば、プレエンティティ イメージをエイリアス「a」で定義する場合、次のコードを使用して、name 属性値にアクセスすることができます。
var oldAccountName = (string)context.PreEntityImages["a"]["name"];
詳細:
関連項目
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示