プラグインの登録

プラグインを作成してコンパイルした後、特定のエンティティ (テーブル行) とメッセージ (操作) が Dataverse によって処理されるときに実行できるように、プラグインをイベント フレームワークに登録する必要があります。 Dataverse イベント フレームワークでプラグインを登録するには、プラグイン登録 (PRT) または Visual Studio 用の Power Platform Tools 拡張機能を使用する必要があります。

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 のソリューションの下の、Power Apps クラシック ソリューション エクスプローラーと PRT アセンブリ ビューで、登録されたプラグイン アセンブリに関する情報を表示することができます。 Power Apps のソリューション エクスプローラーにアクセスするために、ソリューション、ツールバーのクラシックに切り替えるの順に選択します。 Power Apps から既定のソリューションにアクセスするには、ソリューション、リストから「既定のソリューション」の順に選択し、次にオブジェクト ウィンドウ内のプラグイン アセンブリを選択します。

注意

登録する各アセンブリは、Common Data Services の既定のソリューションと混同しないようにするために既定のソリューションに追加されます。 ソリューションに関する情報の詳細については、ソリューションの概要を参照してください。

ソリューションへのアセンブリの追加

登録済みアセンブリの表示で説明されているように、作成したアセンブリ登録はシステムの 既定のソリューション に追加されています。 アンマネージド ソリューションにアセンブリを追加する必要があるため、他の組織に配布できます。 PRT では、アセンブリまたはステップを登録するときにソリューションを指定できません。

ソリューションとその作成方法の詳細については、ソリューションの概要およびソリューションを作成するを参照してください。 ソリューションを作成したら、最初にソリューション リストでソリューションを選択し、次に既存の追加 > その他 > 開発者 > プラグイン アセンブリを選択して、Power Apps のプラグイン アセンブリをそのソリューションに追加できます。

注意

既存またはそれ以降のステップ登録 (次のセクションを参照) は、プラグイン アセンブリを含むアンマネージド ソリューションに追加されません。 ソリューションに、各登録手順を個別に追加する必要があります。 詳細情報: ソリューションへのステップの追加

ステップ登録

アセンブリが読み込まれるかアップロードされた後は、IPlugin を実装するクラスが PRT で使用可能になります。 チュートリアル: プラグインの作成と登録にある新しいステップの登録の手順を使用して、新しいステップ登録を作成します。

ステップを登録する際、イベント パイプラインのステージや、コードを登録しようとする操作の種類によって、いくつかの登録オプションが用意されています。

一般的な構成情報フィールド

Field	Description
Message	PRT は、システムの使用可能なメッセージ名をオート コンプリートします。 詳細: メッセージを .NET 用 SDK と共に使用する
主エンティティ	PRT は、選択したメッセージに適用される有効なテーブルをオート コンプリートします。 これらのメッセージには、Entity または EntityReference 型を受け入れる Target パラメーターがあります。 有効なテーブルが適用される場合、プラグインの呼び出し回数を制限したい場合に、このフィールド値を設定する必要があります。 Update、Delete、Retrieve、RetrieveMultiple のようなコア テーブルメッセージまたは、メッセージとともに適用できるメッセージを空白のままにしている場合は、このメッセージをサポートするすべてのテーブルに対してプラグインが呼び出されます。
副エンティティ	このフィールドは、Target パラメーターとしての EntityReference の配列を受け入れた廃止されたメッセージの下位互換性を保つために残されています。 このフィールドは、通常は使用されなくなりました。
フィルタリング属性	Update または OnExternalUpdated メッセージでは、プライマリ エンティティを設定する際、列をフィルタリングすると、選択した列が更新に含まれる場合にプラグインの実行が制限されます。 このフィールドを設定することは、パフォーマンス向上のベストプラクティスです。 フィルター属性にはエンティティの主キーを含めないでください。 主キーは常に更新操作に含まれるため、これを実行すると、フィルターされた他のすべての属性が無効になります。
イベント ハンドラー	このフィールドは、アセンブリの名前とプラグイン クラスに基づいて設定されます。
ステップ名	ステップの名前。 値は、ステップの構成に基づいて事前設定されますが、この値は変更できます。
ユーザーのコンテキストで実行	ステップの偽装を適用するためのオプションを提供します。 既定の値は 呼び出し元ユーザー です。 呼び出し側のユーザーがステップの操作を実行する権限を持っていない場合、このフィールド値をこれらの権限を持つユーザーに設定する必要がある場合があります。 詳細: ステップのユーザー偽装を設定する
実行順序	同じメッセージの同じステージに対して複数のステップを登録することができます。 このフィールドの番号で、低いものから順に適用するように指定します。 注: ステージでプラグインが適用される順序を制御するには、このオプションを設定します。 既定値をそのまま受け入れることは推奨しません。 (同じステージ、テーブル、およびメッセージの) 実行順序値が同じプラグインの実際の実行順序は保証されておらず、ランダムである可能性があります。
説明	ステップの説明です。 この値は、事前設定されますが、上書きできます。

実行のイベント パイプライン ステージ

プラグインの目的に最適なイベント パイプラインのステージを選択します。

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

詳細: イベント実行パイプライン

実行モード

非同期実行と同期実行の 2 つのモードがあります。

オプション	説明
非同期	操作の完了後に実行するシステム ジョブに、適用するビジネス ロジックの実行コンテキストと定義が移動されます。
同期	プラグインは、実行の段階および実行順序に応じてすぐに実行されます。 すべての操作全体が、これらが完了するまで待機します。

非同期プラグインは PostOperation ステージでのみ登録することができます。 システム ジョブのしくみの詳細については、非同期サービスを参照してください。

特別なステップの登録シナリオ

ステップの登録とテーブルの組み合わせが明確でない特定のシナリオがあります。 これは、テーブルまたは操作の間に特別な関係があるシステムが内部でどのように設計されているかによります。 以下の情報は、これらのケースを識別し、ステップの登録ガイダンスを提供します。

• 更新 イベントに登録されたプラグインは 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 で操作を呼び出したユーザー) がその操作の所有者です。 ただし、ステップ登録では別のユーザーを指定することもできます。 この操作を実行するためには、システム管理者またはシステム カスタマイザーのセキュリティ ロールが必要になります。

プラグイン ステップのユーザー コンテキストを設定するには:

1. 目的の (ステップ) 登録ノードが表示されるまで、アセンブリ ビューでターゲット プラグイン アセンブリ ノードを展開します。
2. ステップ ノードを選択し、コンテキスト メニューまたはツールバーで 更新 を選択します。
3. ユーザーのコンテキストで実行ラベルの横にある使用可能なユーザーのドロップダウン リストからユーザーを選択します。
4. 更新ステップ を選択します。

詳細情報: ユーザーを偽装する

アセンブリの更新

以前登録したアセンブリを変更して再構築する場合は、それを更新する必要があります。 ステップについては、チュートリアル: プラグインの更新 にある プラグイン アセンブリ登録の更新 ステップを参照してください。

アセンブリ バージョン管理

デプロイされた管理ソリューションの一部であるプラグイン アセンブリに変更を加える場合は、その管理ソリューションを更新するときに変更が与える可能性のある影響を考慮する必要があります。 アセンブリのバージョンによって動作が制御されます。

プラグイン アセンブリは、Microsoft Visual Studio プロジェクトの Assembly.info ファイルで定義されている major.minor.build.revision のセマンティック バージョン形式を使用してバージョンを管理できます。 新しいソリューションでアセンブリ バージョン番号のどの部分が変更されるかにより、インポートによって既存のソリューションが更新されるときに、次の動作が適用されます。

• ビルドまたはリビジョンのアセンブリ バージョン番号が変更されます

  これは一括アップグレードと見なされます。 更新されたアセンブリを含むソリューションがインポートされると、アセンブリの古いバージョンは削除されます。 古いソリューションの既存の手順は、新しいバージョンのアセンブリを参照するように自動的に変更されます。

• メジャーまたはマイナー アセンブリ バージョン番号が変更されます

  改訂されたアセンブリを含む更新されたソリューションをインポートした場合、アセンブリは、既存のソリューションのそのアセンブリの以前のバージョンとは異なるアセンブリと見なされます。 既存ソリューション内のプラグイン登録手順では、引き続き古いバージョンのアセンブリが参照されます。 以前のアセンブリの既存のプラグイン登録ステップが改訂されたアセンブリを指すようにする場合は、Plugin Registration Tool を使用して、改訂されたアセンブリタイプを参照するようにステップ構成を手動で変更する必要があります。 この作業は、後でインポートするために更新後のアセンブリをソリューションにエクスポートする前に行う必要があります。

プラグインとコンポーネントの登録解除または無効化

プラグイン登録ツール (PRT) を使用して、プラグインとそのコンポーネントを登録解除または無効にすることができます。

重要

Microsoft または標準のシステム プラグインとステップを登録解除したり、無効にしたりすることはできなくなりました。 以前は、Microsoft.* およびその他のすぐに使用できるシステム プラグインの一部を登録解除または無効にすることができました。これを許可しないようにこの動作を変更しました。 これらのプラグインまたはステップを登録解除または無効にすると、製品機能が期待どおりに動作しなくなる可能性があるため、機能が変更されました。 このようなプラグインまたはステップを登録解除または無効にする必要がある場合は、Microsoft サポート リクエストを提出してください。

プラグイン ステップを無効または有効にする

プラグイン登録ツールが実行され、ターゲットの Dataverse 環境にログインすると、プラグイン ステップの無効化または有効化に進むことができます。 ステップを無効にすると、ステップ登録で指定されたエンティティとメッセージの組み合わせを Dataverse が処理するときにプラグインの実行が事実上オフになります。

重要

プラグインを無効にすると、アプリ、ソリューション、または Dataverse システムの機能に悪影響を及ぼす可能性があります。 続行する前に、影響を理解しておいてください。

登録済みのプラグイン ステップを無効または有効にするには:

1. 目的のステップ登録ノードが表示されるまで、アセンブリ ビューでターゲット プラグイン アセンブリ ノードを展開します。
2. ステップを選択し、コンテキスト メニューまたはツールバーで 有効にする または 無効にする を選択します。

アクティブ化 と 非アクティブ化 コマンド オプションを使用して、レガシーの Dataverse ソリューション エクスプローラー ユーザー インターフェイスでステップを有効または無効にすることもできます。

コンポーネントの登録解除

PRT は、アセンブリ、種類、ステップ、イメージの登録を解除するコマンドを提供します。 手順については、チュートリアル: プラグインの更新のアセンブリ、プラグイン、ステップの登録解除の手順を参照してください。

これらは、PluginAssembly、PluginType、SdkMessageProcessingStep、SdkMessageProcessingStepImage のテーブル上での削除操作です。

ソリューション エクスプローラーでプラグイン アセンブリと Sdk メッセージ処理ステップを削除して、同じ結果を生み出すこともできます。 次の図では、Common Data Service規定のソリューションという名前のカスタムソリューションが表示されます。

注意

プラグイン アセンブリを削除 (登録解除) することはできませんが、既存の Sdk メッセージ処理ステップはそれに依存しています。 エンティティ イメージは別々に削除できませんが、それらを使用するステップが削除されると削除されます。

次の手順

プラグインのデバッグ

参照

ビジネス プロセスを拡張するためのプラグインの作成
プラグインを記述する
チュートリアル: プラグインを書き込み登録する
チュートリアル: プラグインをデバッグする
チュートリアル: プラグインを更新する

注意

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

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