イベント フレームワーク

Microsoft Dataverse の既定の動作を拡張する機能は、サーバーでのイベント発生時の検出内容によって異なります。 イベント フレームワークは、特定のイベントに応答して実行されるカスタム コードを登録する機能を提供します。

プラットフォームの既定の動作を拡張するすべての機能は、イベント フレームワークによって異なります。 コードを記述することなくワークフロー デザイナを使用してイベントに応答するワークフローを構成する場合、そのイベントはイベント フレームワークによって提供されます。

開発者は、プラグイン、Azure 統合、仮想テーブルのデータ プロバイダー、および Webhook を構成して、イベント フレームワークによって提供されるイベントに応答するプラグイン登録ツールを使用します。 イベントが発生し、それらに応答するために拡張機能が登録されると、その操作に関連するデータに関するコンテキスト情報が拡張機能に渡されます。 イベントへの登録がどのように構成されているかに応じて、拡張機能は渡されたデータを修正したり、すぐに適用される自動化プロセスを導入したり、後で実行されるキューにアクションを追加することを定義できます。

カスタム拡張機能のイベント フレームワークを活用するには、以下を理解する必要があります。

• 指定できるイベント
• イベントの処理方法
• イベントが発生したときにカスタム拡張機能が利用できるデータの種類
• 時間とリソースの制約が適用される場合
• パフォーマンスを監視する方法

使用可能なイベント

メッセージを .NET 用 SDK と共に使用するで説明したように、Dataverse プラットフォームのデータ操作はメッセージに基づいており、すべてのメッセージに名前が付けられています。 テーブルで発生する基本的なデータ操作をカバーする Create、Retrieve、RetrieveMultiple、Update、Delete、Associate、Disassociate メッセージがあります。 より複雑な操作に特化したメッセージもあり、カスタム アクションは新しいメッセージを追加します。

プラグイン登録ツールを使用して拡張機能を特定のメッセージに関連付けると、ステップ として登録されます。 以下のスクリーンショットは、プラグインの登録時に使用される新しいステップの登録ダイアログです。

ステップは、拡張機能がどのメッセージに応答すべきか、および他の構成の選択に関する情報を提供します。 拡張機能が応答するメッセージを選択するには、メッセージ フィールドを使用します。

一般に、Microsoft.Crm.Sdk.Messages または Microsoft.Xrm.Sdk.Messages の名前空間にあるほとんどの *Request クラスのメッセージを見つけることができますが、組織内で作成されたユーザー定義アクションのメッセージも表示されます。 テーブル定義を含む操作は使用できません。

メッセージに関するデータは、SdkMessage テーブルと SdkMessageFilter テーブルに格納されます。 Plugin Registration Tool はこの情報をフィルタリングして有効なメッセージのみを表示します。

メッセージとテーブルの組合せが、データベース クエリを使用したプラグインの実行をサポートしているかどうかを確認するには、次の Web API クエリを使用できます:

[Organization URI]/api/data/v9.1/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 メッセージは利用可能ですが、すべての操作で呼び出されるため、拡張子を登録しないでください。

注意

更新イベント用に登録されたプラグインとワーク フローを 2 回呼び出すことができるケースがあります。 詳細: 特化された更新操作の動作

イベント実行パイプライン

プラグイン登録ツールを使用してステップを登録するときは、実行のイベント パイプライン ステージ も選択する必要があります。 各メッセージは、次の表に示すように一連の 4 つのステージで処理されます。

件名	内容
事前検証	初期操作の場合、このステージはメイン システム操作の前に発生します。 これにより、データベース トランザクションの前に操作をキャンセルするためのロジックを組み込む機会が提供されます。 他のステージに登録された拡張機能によってトリガーされる後続の操作も、このステージを通過しますが、呼び出し元拡張機能のトランザクション内に組み込まれます。 このステージはセキュリティ チェックが実行される前に発生し、呼び出し元ユーザーまたはログオンしたユーザーが目的の操作を実行するための適切なアクセス許可を持っていることを確認します。
事前操作	メイン システム操作の前に、データベース トランザクション内で発生します。 メッセージに含まれているエンティティの値を変更する必要がある場合は、ここで変更する必要があります。 ここではアクションをキャンセルしないでください。 キャンセルするとトランザクションのロールバックがトリガーされ、パフォーマンスに大きな影響があります。
MainOperation	カスタム API およびカスタム仮想テーブル データ プロバイダーを除き、内部のみで使用します。 詳細情報: カスタム API の作成と使用 カスタム仮想テーブル データ プロバイダー
PostOperation	メイン システム操作の後、データベース トランザクション内で発生します。 このステージは、呼び出し元にメッセージを戻す前に、メッセージのプロパティを変更するために使用します。 メッセージに含まれているエンティティに変更を適用することは避けてください。変更を適用すると、新しい更新イベントがトリガーされるからです。 PostOperation ステージ内で、非同期実行モードを使用するためのステップを登録できます。 これらのステップは、非同期サービスを使用してデータベース トランザクションの外部で実行されます。 プラグインが更新操作を実行するように設計されており、ユーザー (SystemUser) エンティティの Create メッセージに登録されている場合は、プラグインを登録するときに非同期モードを使用する必要があります。 詳細については「非同期サービス」を参照してください。

どのステージを選択するべきかは、拡張の目的によって異なります。 すべてのビジネス ロジックを単一の手順に適用する必要はありません。 複数のステップを適用することで、事前検証ステージで操作を進めるかどうかのロジックを確認でき、PostOperation ステージでロジックをメッセージ プロパティに変更できるようにすることができます。

重要

データベース トランザクションの任意の同期ステージでコードによってスローされた例外により、トランザクション全体がロールバックされます。 考えられる例外がコードによって処理されるように注意する必要があります。 操作を取り消したい場合は、事前検証ステージでこれを検出し、操作がキャンセルされた理由を説明する適切なメッセージを含む InvalidPluginExecutionException をスローしてください。

同じメッセージとステージに対して複数の拡張機能を登録することができます。 ステップ登録の中で、実行順序値は、複数の拡張機能が所定のステージに対して処理されるべき順序を決定します。

登録されたステップに関する情報は、SdkMessageProcessingStep テーブル に格納されます。

非同期のプラグイン ステップ

PostOperation ステージに登録する場合、非同期実行モード で実行するステップを登録するためのオプションを使用できます。 これらのプラグインは記録操作が完了した後に実行されます。

多くの場合これが必要になるのは、現在のレコードに関連付けられているが、別のプロセスで作成されたレコードを操作する場合です。 たとえば、特定の SystemUser に関連する UserSettings は、SystemUser 行が作成されるまで作成されません。

詳細情報: 非同期サービス

イベント コンテキスト

拡張機能がプラグインである場合、IPluginExecutionContext インターフェイスを実装するパラメーターを受け取ります。 このクラスは、プラグインが登録されている Stage に関する情報と、現在の操作をトリガーさせた別のプラグイン内の操作に関する情報を提供する ParentContext に関する情報を提供します。

拡張機能が Azure Service Bus エンドポイント、Azure EventHub トピック、Web フックの場合、登録されたエンドポイントに投稿されるデータは、IPluginExecutionContext と IExecutionContext の両方を実装する RemoteExecutionContext の形式になります

実行コンテキストに関する詳細については、実行コンテキストを理解する を参照してください。

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。