プラグインの登録
プラグインを作成してコンパイルした後、特定のエンティティ (テーブル行) とメッセージ (操作) が処理されるときに実行されるように、 イベント フレームワーク に登録する必要があります Microsoft Dataverse。 プラグインを登録するには、 Dataverse プラグイン登録ツール (PRT) または Power Platform ツール拡張機能のいずれかのツールを使用する必要があります Visual Studio。
PRT は Dataverse オブジェクト登録を作成し、それらの登録の編集をサポートします。 この記事では、プラグイン アセンブリとメッセージ処理 手順 を登録する方法、ソリューションにアセンブリを追加する方法、およびプラグイン登録ツールを使用してその他の一般的なプラグイン関連の操作を実行する方法について説明します。
Visual Studio 拡張機能は、より機能豊富な開発環境を提供し、コーディング、展開、デバッグ/プロファイリングの開発プロセス全体をカバーします。 Visual Studio 用の Power Platform Tools 拡張機能の使用については、クイックスタートを参照してください。
プラグイン登録ツールについて
プラグイン登録ツール (PRT) は、Dataverse によるプラグイン アセンブリ、メッセージ処理ステップ、およびその他の種類のオブジェクトの登録をサポートします。 PRT は、NuGet.org からダウンロードできるいくつかの Dataverse ツールのうちの 1 つです。Dataverse 開発ツール の指示に従って、PRT と必要に応じて他の開発ツールをダウンロードします。
PRT をダウンロードしたら、プラグイン登録ツールを使用して接続するの指示に従って、ツールをターゲット Dataverse 環境 (プラグインを登録する場所) に接続します。
アセンブリ登録
アセンブリの登録は、ツールによって処理された Dataverse データベースにアセンブリをアップロードすることが含まれます。 チュートリアル: プラグインの作成と登録のアセンブリの登録にある説明を参照してください。
注意
アセンブリの 分離モード と 場所 に関連するオプションがあります。 これらは、設置型展開に適用されるオプションを示します。 Dataverse は、設置型展開では使用できませんので、これらのオプションの既定のオプションサンドボックスおよびデータベースを常に使用できます。
アセンブリがアップロードされると、PluginAssembly テーブルに格納されます。 プロパティの大半は、インポートされたアセンブリのリフレクションを使用して設定されます。 アセンブリの base64 でエンコードされたバイトは、Content 列に格納されます。 PRT のアセンブリの プロパティ を表示している間、編集できるのは 説明 値のみです。 IPlugin インターフェイスを実装するか、CodeActivity から派生するアセンブリ内のコンパイル済みクラスはすべて、自動的に登録されます。
登録されたアセンブリの表示
登録されたプラグイン アセンブリとステップに関する情報には、 Power Apps およびPRTアセンブリ ビューでアクセスできます。 Power Apps のプラグイン情報にアクセスするには、左側のナビゲーション ペインで [ソリューション] を選択し、リストから利用可能なソリューションを選択します。 次に、左側の オブジェクト ペイン内で プラグイン アセンブリ または プラグイン ステップ を選択します。
注意
登録する各アセンブリは、Common Data Services の既定のソリューションと混同しないようにするために既定のソリューションに追加されます。 ソリューションに関する情報の詳細については、ソリューションの概要を参照してください。
ソリューションへのアセンブリの追加
登録済みアセンブリの表示で説明されているように、作成したアセンブリ登録はシステムの 既定のソリューション に追加されています。 アンマネージド ソリューションにアセンブリを追加する必要があるため、他の組織に配布できます。 PRT では、アセンブリまたはステップを登録するときにソリューションを指定できません。
ソリューションとその作成方法の詳細については、ソリューションの概要およびソリューションを作成するを参照してください。 ソリューションを作成したら、最初にソリューション リストでソリューションを選択し、次に既存の追加 > その他 > 開発者 > プラグイン アセンブリを選択して、Power Apps のプラグイン アセンブリをそのソリューションに追加できます。
注意
既存またはそれ以降のステップ登録 (次のセクションを参照) は、プラグイン アセンブリを含むアンマネージド ソリューションに追加されません。 ソリューションに、各登録手順を個別に追加する必要があります。 詳細情報: ソリューションに 手順 を追加
ステップ登録
メッセージ処理 手順 を登録すると、 Dataverse プラグインを実行する条件と実行方法が通知されます。 条件とは、 Dataverse によって処理されるテーブルとメッセージ操作を指します。 同期実行または非同期実行、コア操作の前または後など、その他の構成オプションは、手順 登録時に指定できます。 これらのランタイム構成オプションについては、次のセクションで詳しく説明します。
アセンブリが読み込まれるかアップロードされた後は、IPlugin を実装するクラスが PRT で使用可能になります。 チュートリアル: プラグインの作成と登録にある新しいステップの登録の手順を使用して、新しいステップ登録を作成します。
一般的な構成情報フィールド
| Field | プロパティ |
|---|---|
| Message | Dataverse によって処理されるとプラグインが実行されるメッセージ。 |
| 主エンティティ | 処理されるとプラグインが実行されるエンティティ (テーブル)。 Dataverse メッセージには、 |
| 副エンティティ | このフィールドは、Target パラメーターとしての EntityReference の配列を受け入れた廃止されたメッセージの下位互換性を保つために残されています。 このフィールドは、通常は使用されなくなりました。 |
| フィルタリング属性 | Update、 OnExternalUpdated、またはその他のメッセージの場合、プライマリ エンティティを設定すると、フィルター属性 (列) によって、指定した列が更新に含まれる場合にのみプラグインの実行が制限されます。このフィールドを設定することは、パフォーマンス向上のベストプラクティスです。 フィルター属性にはエンティティの主キーを含めないでください。 主キーは常に更新操作に含まれるため、これを実行すると、フィルターされた他のすべての属性が無効になります。 |
| イベント ハンドラー | このフィールド値は、アセンブリの名前とプラグイン クラスに基づいてPRTに入力されます。 |
| ステップ名 | メッセージ処理の名前は 手順 です。 値は、ステップの構成に基づいて事前設定されますが、この値は変更できます。 |
| ユーザーのコンテキストで実行 | ステップの偽装を適用するためのオプションを提供します。 既定の値は 呼び出し元ユーザー です。 呼び出し側のユーザーがステップの操作を実行する権限を持っていない場合、このフィールド値をこれらの権限を持つユーザーに設定する必要がある場合があります。 詳細: ステップのユーザー偽装を設定する |
| 実行順序 | 同じステージとメッセージに対して複数のステップを登録できます。 このフィールドの数字によって、ステージ内でステップが適用される最も低い序列から最も高い序列までが決定されます。 同じステージでプラグインが実行される順序を制御するには、これを設定する必要があります。 既定値をそのまま受け入れることは推奨しません。 同じ実行順序値 (同じステージ、テーブル、メッセージ) を持つプラグインの実際の実行順序は保証されず、ランダムになる場合があります。 |
| プロパティ | 手順 の説明。 この値は、事前設定されますが、上書きできます。 |
実行のイベント パイプライン ステージ
プラグインの目的に最適なイベント パイプラインのステージを選択します。 プレフィックス「Pre」および「Post」は、 Dataverse メイン（コア）操作の前または後を指します。 メイン操作は、メッセージとエンティティの組み合わせが処理される段階です。
| 回答内容 | プロパティ |
|---|---|
| 事前検証 | 初期操作の場合、このステージはメイン システム操作の前に発生します。 これにより、データベース トランザクションの前に操作をキャンセルするためのロジックを組み込む機会が提供されます。 他のステージに登録された拡張機能によってトリガーされる後続の操作も、このステージを通過しますが、呼び出し元拡張機能のトランザクション内に組み込まれます。 このステージはセキュリティ チェックが実行される前に発生し、呼び出し元ユーザーまたはログオンしたユーザーが目的の操作を実行するための適切なアクセス許可を持っていることを確認します。 |
| 事前操作 | メイン システム操作の前に、データベース トランザクション内で発生します。 メッセージに含まれているエンティティの値を変更する必要がある場合は、ここで変更する必要があります。 ここではアクションをキャンセルしないでください。 キャンセルするとトランザクションのロールバックがトリガーされ、パフォーマンスに大きな影響があります。 |
| PostOperation | メイン システム操作の後、データベース トランザクション内で発生します。 このステージは、呼び出し元にメッセージを戻す前に、メッセージのプロパティを変更するために使用します。 メッセージに含まれているエンティティに変更を適用することは避けてください。変更を適用すると、新しい更新イベントがトリガーされるからです。 PostOperation ステージ内で、非同期実行モードを使用するためのステップを登録できます。 これらのステップは、非同期サービスを使用してデータベース トランザクションの外部で実行されます。 プラグインが更新操作を実行するように設計されており、ユーザー (SystemUser) エンティティの Create メッセージに登録されている場合は、プラグインを登録するときに非同期モードを使用する必要があります。 詳細については「非同期サービス」を参照してください。 |
詳細: イベント実行パイプライン
実行モード
実行モードには、非同期と同期の2つがあります。
| 回答内容 | プロパティ |
|---|---|
| 非同期 | 実行コンテキストと適用するビジネス ロジックの定義はシステム ジョブ キューに移動され、メイン操作が完了した後に実行されます。 |
| 同期 | プラグインは、実行の段階および実行順序に応じてすぐに実行されます。 すべての操作全体が、これらが完了するまで待機します。 |
非同期プラグインは PostOperation ステージでのみ登録することができます。 システム ジョブのしくみの詳細については、非同期サービスを参照してください。
特別なステップの登録シナリオ
ステップの登録とテーブルの組み合わせが明確でない特定のシナリオがあります。 これは、テーブルまたは操作の間に特別な関係があるシステムが内部でどのように設計されているかによります。 以下の情報は、これらのケースを識別し、ステップの登録ガイダンスを提供します。
- Update イベントに登録されたプラグインが2回呼び出される場合があります。 詳細: 特化された更新操作の動作
- データを customeraddress、leadaddress、publisheraddress、または competitoraddress レコードに変更する場合、取引先企業や取引先担当者のプラグイン ステップを登録します。
展開
| 回答内容 | 説明設定 |
|---|---|
| サーバー | プラグインは、Dataverse サーバーで実行されます。 |
| オフライン | プラグインは、ユーザーがオフライン モードになると Dynamics 365 for Outlook クライアント内で実行されます。 |
構成データの設定
PRT の 安全でない構成 フィールドや 安全な構成 フィールドを使用すると、特定のステップでプラグインに渡す構成データを指定できます。
注意
ソリューションをエクスポートする場合、セキュリティで保護された構成データはステップ登録に含まれません。
このデータを使用してプラグインがステップでどのように機能するかを制御するために、コンストラクターの文字列値を受け入れるようにプラグインを作成できます。 詳細: プラグインへの構成データの引き渡し
エンティティ イメージの定義
プラグイン内で、操作に含まれていなかったプライマリ テーブルのプロパティ値を参照する必要がある場合があります。 たとえば、Update 操作では、変更前の値を知ることができますが、実行コンテキストはこの情報を提供しておらず、変更された値のみが含まれます。
プラグイン ステップが実行パイプラインの PreValidation または PreOperation ステージに登録されている場合、IOrganizationService インスタンスを使用してプロパティの現在の値を取得できますが、これはパフォーマンス上お勧めしません。 より優れたプラクティスは、プラグイン ステップ登録を使用してプレエンティティ イメージを定義する方法です。 これにより、変更された値と比較するために使用できる操作の前に存在していた、関心のあるフィールドを含むテーブルの「スナップショット」がキャプチャされます。
重要
エンティティ イメージを作成する際の既定動作では、すべての列を選択します。 この既定の動作は使用しないでください。 これは、パフォーマンスに悪影響を与える可能性があります。 プラグインのロジックに必要な列のみを含めてください。
エンティティ イメージをサポートするメッセージ
Dataverse では、以下のメッセージだけがエンティティ イメージをサポートしています。
| メッセージ | 要求クラス プロパティ | 内容 |
|---|---|---|
Assign |
Target |
割り当てられたテーブル。 |
Create |
Target |
作成されたテーブル。 |
Delete |
Target |
削除されたテーブル。 |
DeliverIncoming |
EmailId |
配布された電子メール ID。 |
DeliverPromote |
EmailId |
配布された電子メール ID。 |
Merge |
Target または SubordinateId |
子テーブルのデータがマージされる親テーブル、または親テーブルにマージされる子テーブル。 |
Route |
Target |
転送されるアイテム。 |
Send |
FaxId、EmailId、または TemplateId |
送信されるアイテム。 |
SetState |
EntityMoniker |
状態が設定されているテーブル。 |
Update |
Target |
更新されたテーブル。 |
エンティティ イメージの種類
2 種類のエンティティ イメージがあります: プレ イメージ および ポスト イメージ。 構成すると、これらのイメージがそれぞれ PreEntityImages および PostEntityImages プロパティとして実行コンテキスト内で使用可能になります。 名前が示すように、これらのスナップショットは、メイン操作の前とメイン操作後のテーブルの様子を表します。 エンティティ イメージを構成する場合、テーブル エイリアス* 値を定義します。これは、PreEntityImages または PostEntityImages プロパティから特定のエンティティ イメージにアクセスするために使用するキー値になります。
イメージの可用性
エンティティ イメージを構成する場合、使用可能なエンティティ イメージのタイプが、登録されたステップのステージと操作のタイプに依存することを認識することが重要です。 例:
- テーブルがまだ存在しないため、
Createメッセージのプレ イメージを保持することはできません。 - テーブルが存在しなくなったため、
Deleteメッセージのポスト イメージを保持することはできません。 - トランザクションが完了するまでテーブルのプロパティの状態を知る方法がないため、実行パイプラインの PostOperation ステージに登録されたステップの ポスト イメージのみ保持することができます。
- PostOperation ステージで登録した
Update操作については、プリ イメージとポスト イメージの両方が存在することができます。
エンティティ イメージの追加
Visual Studio 向け Power Platform Tools の拡張機能を使用して、プラグイン ステップに エンティティ画像を追加します。
または、1画像を追加するセクションのチュートリアル: プラグインを更新するの指示に従い、プラグイン登録ツールを使用してステップにエンティティ画像を追加できます。
ステップをソリューションに追加する
ソリューションへのアセンブリの追加で説明されているように、プラグイン アセンブリは、アンマネージド ソリューションに追加できるソリューション コンポーネントです。 SDK メッセージ処理手順は、ソリューション コンポーネントでもあり、配布する順序でアンマネージド ソリューションに追加する必要もあります。
ソリューションにステップを追加する手順は、アセンブリの追加に似ています。 既存の追加 コマンドを使用して、それを目的のアンマネージド ソリューションに移動します。 唯一の違いは、ステップを追加しようとしましたが、そのステップで使用されたクラスを含むアセンブリをまだ追加していない場合に、不足している必須ココンポーネントを追加するように求められることです。
これが発生した場合は、通常、OK を選択し、アンマネージド ソリューションと共にアセンブリを持ち込む必要があります。 これを選択しないのは、アセンブリを含む別のソリューションがすでにインストールされている環境にソリューションがインストールされるように設計されている場合のみです。
同様に、ソリューションからアセンブリを削除しても、それに依存するステップは削除されないことに注意してください。
ステップにユーザーの偽装を設定する
プラグイン登録ツールが実行され、ターゲットの Dataverse 環境にログインすると、プラグイン ステップ登録の設定または変更に進むことができます。 このセクションでは、プラグインが操作を実行するユーザーの変更について説明します。 つまり、プラグインによって開始されたデータ操作を実行している実効ユーザーです。 デフォルトでは、呼び出し元のユーザー (Dataverse で操作を呼び出したユーザー) がその操作の所有者です。 ただし、ステップ登録では別のユーザーを指定することもできます。 この操作を実行するためには、システム管理者またはシステム カスタマイザーのセキュリティ ロールが必要になります。
プラグイン ステップのユーザー コンテキストを設定するには:
- 目的の (ステップ) 登録ノードが表示されるまで、アセンブリ ビューでターゲット プラグイン アセンブリ ノードを展開します。
- ステップ ノードを選択し、コンテキスト メニューまたはツールバーで 更新 を選択します。
- ユーザーのコンテキストで実行ラベルの横にある使用可能なユーザーのドロップダウン リストからユーザーを選択します。
- 更新ステップ を選択します。
詳細情報: ユーザーを偽装する
アセンブリの更新
以前登録したアセンブリを変更して再構築する場合は、それを更新する必要があります。 ステップについては、チュートリアル: プラグインの更新 にある プラグイン アセンブリ登録の更新 ステップを参照してください。
アセンブリ バージョン管理
デプロイされた管理ソリューションの一部であるプラグイン アセンブリに変更を加える場合は、その管理ソリューションを更新するときに変更が与える可能性のある影響を考慮する必要があります。 アセンブリのバージョンによって動作が制御されます。
プラグイン アセンブリは、Microsoft Visual Studio プロジェクトの Assembly.info ファイルで定義されている major.minor.build.revision のセマンティック バージョン形式を使用してバージョンを管理できます。 新しいソリューションでアセンブリ バージョン番号のどの部分が変更されるかにより、インポートによって既存のソリューションが更新されるときに、次の動作が適用されます。
ビルドまたはリビジョンのアセンブリ バージョン番号が変更されます
これは一括アップグレードと見なされます。 更新されたアセンブリを含むソリューションがインポートされると、アセンブリの古いバージョンは削除されます。 古いソリューションの既存の手順は、新しいバージョンのアセンブリを参照するように自動的に変更されます。
メジャーまたはマイナー アセンブリ バージョン番号が変更されます
改訂されたアセンブリを含む更新されたソリューションをインポートした場合、アセンブリは、既存のソリューションのそのアセンブリの以前のバージョンとは異なるアセンブリと見なされます。 既存ソリューション内のプラグイン登録手順では、引き続き古いバージョンのアセンブリが参照されます。 以前のアセンブリの既存のプラグイン登録ステップが改訂されたアセンブリを指すようにする場合は、Plugin Registration Tool を使用して、改訂されたアセンブリタイプを参照するようにステップ構成を手動で変更する必要があります。 この作業は、後でインポートするために更新後のアセンブリをソリューションにエクスポートする前に行う必要があります。
プラグインとコンポーネントの登録解除または無効化
プラグイン登録ツール (PRT) を使用して、プラグインとそのコンポーネントを登録解除または無効にすることができます。
重要
Microsoft または標準のシステム プラグインとステップを登録解除したり、無効にしたりすることはできなくなりました。 以前は、Microsoft.* およびその他のすぐに使用できるシステム プラグインの一部を登録解除または無効にすることができました。これを許可しないようにこの動作を変更しました。 これらのプラグインまたはステップを登録解除または無効にすると、製品機能が期待どおりに動作しなくなる可能性があるため、機能が変更されました。 このようなプラグインまたはステップを登録解除または無効にする必要がある場合は、Microsoft サポート リクエストを提出してください。
プラグイン ステップを無効または有効にする
プラグイン登録ツールが実行され、ターゲットの Dataverse 環境にログインすると、プラグイン ステップの無効化または有効化に進むことができます。 ステップを無効にすると、ステップ登録で指定されたエンティティとメッセージの組み合わせを Dataverse が処理するときにプラグインの実行が事実上オフになります。
重要
プラグインを無効にすると、アプリ、ソリューション、または Dataverse システムの機能に悪影響を及ぼす可能性があります。 続行する前に、影響を理解しておいてください。
登録済みのプラグイン ステップを無効または有効にするには:
- 目的のステップ登録ノードが表示されるまで、アセンブリ ビューでターゲット プラグイン アセンブリ ノードを展開します。
- ステップを選択し、コンテキスト メニューまたはツールバーで 有効にする または 無効にする を選択します。
アクティブ化 と 非アクティブ化 コマンド オプションを使用して、レガシーの Dataverse ソリューション エクスプローラー ユーザー インターフェイスでステップを有効または無効にすることもできます。
Power Apps で、選択した 手順 の「オフにする」および「オンにする」オプションを使用して、プラグイン ステップを無効または有効にします。 手順 オプションにアクセスするには、まず [ソリューション] に移動してソリューションを選択し、次に左側の [オブジェクト] ペインで [プラグイン ステップ] を選択します。
コンポーネントの登録解除
PRT は、アセンブリ、種類、ステップ、イメージの登録を解除するコマンドを提供します。 手順については、チュートリアル: プラグインの更新のアセンブリ、プラグイン、ステップの登録解除の手順を参照してください。
これらは、PluginAssembly、PluginType、SdkMessageProcessingStep、SdkMessageProcessingStepImage のテーブル上での削除操作です。
ソリューション エクスプローラーでプラグイン アセンブリと Sdk メッセージ処理ステップを削除して、同じ結果を生み出すこともできます。 次の図では、Common Data Service規定のソリューションという名前のカスタムソリューションが表示されます。
注意
プラグイン アセンブリを削除 (登録解除) することはできませんが、既存の Sdk メッセージ処理ステップはそれに依存しています。 エンティティ イメージは別々に削除できませんが、それらを使用するステップが削除されると削除されます。
次の手順
参照
ビジネス プロセスを拡張するためのプラグインの作成
プラグインを記述する
チュートリアル: プラグインを書き込み登録する
チュートリアル: プラグインをデバッグする
チュートリアル: プラグインを更新する
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。