Microsoft Dataverse イベント フレームワークを使用すると、サーバー上でイベントがいつ発生するかを検出し、応答としてカスタム コードを実行できます。 イベント フレームワークを使用して、プラグイン、ワークフロー、Azure 統合、Webhook を登録することで、既定のプラットフォーム動作を拡張します。
プラットフォームの既定の動作を拡張するすべての機能は、イベント フレームワークによって異なります。 コードを記述せずにワークフロー デザイナーを使用してイベントに応答するようにワークフローを構成すると、イベント フレームワークはそのイベントを提供します。
開発者は、 プラグイン登録ツール を使用して、プラグイン、Azure 統合、仮想テーブル データ プロバイダー、および Webhook を構成して、イベント フレームワークが提供するイベントに応答します。 イベントが発生し、拡張機能を登録してそれらに応答すると、フレームワークは操作に関連するデータに関するコンテキスト情報を拡張機能に渡します。 イベントの登録を構成する方法に応じて、拡張機能は、イベントに渡されるデータを変更したり、すぐに適用する自動化されたプロセスを開始したり、後で実行するアクションをキューに追加することを定義したりできます。
カスタム拡張機能のイベント フレームワークを活用するには、次の内容を理解する必要があります。
- 利用可能なイベント
- イベントの処理方法
- イベントが発生したときにカスタム拡張機能で使用できるデータの種類
- 適用される時間とリソースの制約
- パフォーマンスを監視する方法
使用可能なイベント
「 SDK for .NET でメッセージを使用する」で説明されているように、Dataverse プラットフォームはメッセージに対するデータ操作をベースにしており、すべてのメッセージに名前があります。 プラットフォームには、テーブルで発生する基本的なデータ操作に対応する Create、 Retrieve、 RetrieveMultiple、 Update、 Delete、 Associate、および Disassociate メッセージが含まれます。 プラットフォームには、より複雑な操作用の特殊なメッセージも含まれており、カスタム アクションによって新しいメッセージが追加されます。
プラグイン登録ツールを使用して拡張機能を特定のメッセージに関連付ける場合は、 手順として登録します。 次のスクリーンショットは、プラグインの登録時に使用される [新しいステップ の登録] ダイアログです。
![プラグイン登録ツールの [新しいステップの登録] ダイアログのスクリーンショット。メッセージ、エンティティ、パイプライン ステージのフィールドが表示されています。](media/register-new-step-plug-in.png)
手順では、拡張機能が応答するメッセージに関する情報と、その他の多くの構成の選択肢を提供します。 [ メッセージ ] フィールドを使用して、拡張機能が応答するメッセージを選択します。
一般に、またはMicrosoft.Crm.Sdk.Messages名前空間のMicrosoft.Xrm.Sdk.Messages クラスに関するメッセージが見つかる可能性があります。 また、組織内で作成したカスタム アクションのメッセージも見つかります。 プラットフォームでは、テーブル定義を含む操作は使用できません。
システムは、 SdkMessage テーブルと SdkMessageFilter テーブルにメッセージに関するデータ を 格納します。 プラグイン登録ツールは、有効なメッセージのみを表示するようにこの情報をフィルター処理します。
データベース クエリを使用して、メッセージとテーブルの組み合わせでプラグインの実行がサポートされているかどうかを確認するには、次の Web API クエリを使用します。
[Organization URI]/api/data/v9.2/sdkmessages?$select=name
&$filter=isprivate eq false
and (name ne 'SetStateDynamicEntity'
and name ne 'RemoveRelated'
and name ne 'SetRelated' and
name ne 'Execute')
and sdkmessageid_sdkmessagefilter/any(s:s/iscustomprocessingstepallowed eq true
and s/isvisible eq true)
&$expand=sdkmessageid_sdkmessagefilter($select=primaryobjecttypecode;
$filter=iscustomprocessingstepallowed eq true and isvisible eq true)
&$orderby=name
ヒント
このデータを Excel ワークシートにエクスポートするには、このクエリと、 Dataverse を使用したプラグインの対象となるメッセージとテーブルの検索に関するブログ記事に記載されている手順を使用します。
次の FetchXML を使用して、この情報を取得することもできます。 FetchXML Builder は、この種のクエリを実行するのに便利なツールです。
<fetch>
<entity name='sdkmessage'>
<attribute name='name' />
<link-entity name='sdkmessagefilter'
alias='filter'
to='sdkmessageid'
from='sdkmessageid'
link-type='inner'>
<filter type='and'>
<condition attribute='iscustomprocessingstepallowed'
operator='eq'
value='1' />
<condition attribute='isvisible'
operator='eq'
value='1' />
</filter>
<attribute name='primaryobjecttypecode' />
</link-entity>
<filter>
<condition attribute='isprivate'
operator='eq'
value='0' />
<condition attribute='name'
operator='not-in'>
<value>SetStateDynamicEntity</value>
<value>RemoveRelated</value>
<value>SetRelated</value>
<value>Execute</value>
</condition>
</filter>
<order attribute='name' />
</entity>
</fetch>
注意事項
Executeメッセージは使用できますが、すべての操作で呼び出されるため、拡張機能を登録しないでください。
注
場合によっては、プラットフォームは Update イベントに登録したプラグインとワークフローを 2 回呼び出すことができます。 詳細については、「 特殊な更新操作の動作」を参照してください。
イベント実行パイプライン
プラグイン登録ツールを使用してステップを登録する場合は、 実行のイベント パイプライン ステージも選択する必要があります。 各メッセージは、次の表に示すように、4 つのステージのシリーズで処理されます。
| 名前 | Description |
|---|---|
| PreValidation | 初期操作の場合、このステージはメイン システム操作の前に行われます。 これにより、データベース トランザクションの前に操作を取り消すロジックを含めることができます。 他のステージで登録された拡張機能によってトリガーされる後続の操作も、このステージを通過しますが、呼び出し元の拡張機能のトランザクションに含まれます。 このステージは、呼び出し元またはログオンしているユーザーが目的の操作を実行するための適切なアクセス許可を持っていることを確認するために、セキュリティ チェックが実行される前に発生します。 |
| PreOperation | メイン システム操作の前、およびデータベース トランザクション内で発生します。 メッセージに含まれるエンティティの値を変更する場合は、ここで行う必要があります。 ここで操作を取り消さないようにします。 取り消すとトランザクションのロールバックがトリガーされ、パフォーマンスに大きな影響を与えます。 |
| MainOperation | 内部使用の場合は、カスタム API とカスタム仮想テーブル データ プロバイダーを除きます。 詳細: カスタム API の作成と使用 カスタム仮想テーブル データ プロバイダー |
| PostOperation | メイン システム操作の後、およびデータベース トランザクション内で発生します。 このステージを使用して、メッセージが呼び出し元に返される前にメッセージのプロパティを変更します。 新しい Update イベントがトリガーされるため、メッセージに含まれるエンティティに変更を適用しないでください。 PostOperation ステージ内で、非同期実行モードを使用するステップを登録できます。 これらの手順は、非同期サービスを使用してデータベース トランザクションの外部で実行されます。 プラグインが更新操作を実行するように設計されており、 ユーザー (SystemUser) エンティティの作成メッセージに登録されている場合は、プラグインの登録時に非同期モードを使用する必要があります。 詳細: 非同期サービス。 |
選択するステージは、拡張機能の目的によって異なります。 1 つのステップ内ですべてのビジネス ロジックを適用する必要はありません。 操作の続行を許可するかどうかに関するロジックを PreValidation ステージに配置し、メッセージ プロパティに変更を加えるロジックを PostOperation ステージで実行できるように、複数の手順を適用できます。
Important
データベース トランザクション内の任意の同期ステージでコードによってスローされた例外により、トランザクション全体がロールバックされます。 発生する可能性のある例外ケースをコードで処理していることを確認します。 操作を取り消す場合は、 PreValidation ステージでこの条件を検出し、操作が取り消された理由を説明する適切なメッセージを含む InvalidPluginExecutionException をスローします。
同じメッセージとステージに対して複数の拡張機能を登録できます。 ステップ登録内で、 実行順序 の値によって、システムが特定のステージの複数の拡張を処理する順序が決まります。
システムは、登録されたステップに関する情報 を SdkMessageProcessingStep テーブルに格納します。
非同期プラグインの手順
PostOperation ステージに登録するときに、非同期実行モードで実行するステップを登録できます。 これらのプラグインは、レコード操作の完了後に実行されます。
この動作は、現在のレコードに関連付けられているが、別のプロセスで作成されたレコードを操作する場合に必要になることがよくあります。 たとえば、特定のUserSettings レコードに関連するSystemUserは、SystemUser行が作成されるまで作成されません。
詳細情報: 非同期サービス
イベント コンテキスト
拡張機能がプラグインの場合は、 IPluginExecutionContext インターフェイスを実装するパラメーターを受け取ります。 このクラスは、プラグインが登録する Stage に関する情報を提供します。 また、現在の操作をトリガーした別のプラグイン内の操作の詳細を示す、 ParentContextに関する情報も提供します。
拡張機能が Azure Service Bus エンドポイント、Azure Event Hubs トピック、または Web フックである場合、登録されたエンドポイントにポストされるデータは RemoteExecutionContextの形式で提供されます。 このクラスは、 IPluginExecutionContext と IExecutionContextの両方を実装します。
実行コンテキストの詳細については、「 実行コンテキストについて」を参照してください。