プラグインの登録
注意
エンティティとテーブルの違いがわかりませんか？ Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。
Visual Studio 用 Power Platform Tools を使用すると、プラグインをすばやく作成してデプロイ (登録) することができます。その方法を紹介したクイックスタート記事を用意しています。
プラグインの書き込み、登録、デバッグするプロセスは次のとおりです:
- Visual Studio に .NET Framework クラス ライブラリ プロジェクトを作成する
Microsoft.CrmSdk.CoreAssembliesNuGet パッケージをプロジェクトに追加する- ステップとして登録されるクラスの IPlugin インターフェイスを実装します。
- インターフェイスに必要な Execute メソッドにコードを追加する
- 必要なサービスへの参照を取得する
- 自分のカスタム ビジネス ロジックを追加する
- アセンブリにサインし、ビルドする
- アセンブリをテストする
- テスト環境でアセンブリを登録する
- アンマネージド ソリューションに、登録されたアセンブリとステップを追加する
- アセンブリの動作をテストする
- 想定されたトレース ログが書き込まれたことを確認する
- 必要に応じてアセンブリをデバッグする
このトピックは、プラグイン アセンブリとステップを登録し、それらをソリューションに追加する方法について説明しています。 追加情報は、これらのチュートリアルにあります。
Plug-in Registration tool (PRT)
プラグイン アセンブリとステップを登録するには、Plug-in Registration tool (PRT) を使用します。
PRT は、NuGet からダウンロード可能なツールの 1 つです。 NuGet からのツールをダウンロード の手順に従います。 そのトピックには、PowerShell スクリプト使用の手引きが含まれており、NuGet から最新ツールをダウンロードできます。
PRT をダウンロードしたら、チュートリアル: プラグインの書き込みと登録 にある プラグイン登録ツールを使用して接続するの手順を使用して、Microsoft Dataverse 環境に接続します。
アセンブリの登録
アセンブリの登録は、Dataverse データベースにアセンブリをアップロードするプロセスです。 チュートリアル: プラグインの作成と登録のアセンブリの登録にある説明を参照してください。
注意
アセンブリの 分離モード と 場所 に関連するオプションがあります。 これらは、設置型展開に適用されるオプションを示します。 Dataverse は、設置型展開では使用できませんので、これらのオプションの既定のオプション サンドボックス および データベース を常に使用できます。
アセンブリがアップロードされると、PluginAssembly テーブルに格納されます。 ほとんどのプロパティは、インポートされたテーブルの反映を使用して設定されます。 アセンブリの base64 でエンコードされたバイトは、Content 列に格納されます。 PRT のアセンブリの プロパティ を表示している間、編集できるのは 説明 値のみです。
登録されたアセンブリの表示
PRT を使用しないでアプリケーション ソリューション エクスプローラーで登録されているアセンブリに関する情報を表示できます。
アンマネージド ソリューションに移動する
Power Apps ポータルから ソリューション を選択し、ツール バーの クラシックに切り替え を選択します。
すべてのソリューション リストから、必要な [アンマネージド ソリューション] を選択します。
注意
PRT を使用して追加する各アセンブリは、システム 既定のソリューション、(Common Data Services規定のソリューション と混同しないようにするために) に追加されます。 既定のソリューション を表示するには、ソリューション にある すべてのソリューション を選択し、ビューを すべてのソリューション - 内部 に変更します。
ソリューションに関する情報の詳細については、ソリューションの概要を参照してください。
内部ソリューション リストで規定のソリューションの名前を選択した後、この環境に登録されているすべてのアセンブリを見つけることができます。
コードを使用した登録されているアセンブリの照会
PRT またはアプリケーションを使用しないで登録されているアセンブリに関する情報を表示するには、ブラウザーで次の Web API クエリを使用します。
[org uri]]/api/data/v9.0/pluginassemblies
?$filter=ishidden/Value eq false
&$select=
createdon,
culture,
customizationlevel,
description,
isolationmode,
major,
minor,
modifiedon,
name,
pluginassemblyid,
publickeytoken,
version
または、以下の FetchXml を使用して記述したプログラムで取得します。
<fetch>
<entity name='pluginassembly' >
<attribute name='createdon' />
<attribute name='culture' />
<attribute name='customizationlevel' />
<attribute name='description' />
<attribute name='isolationmode' />
<attribute name='major' />
<attribute name='minor' />
<attribute name='modifiedon' />
<attribute name='name' />
<attribute name='pluginassemblyid' />
<attribute name='publickeytoken' />
<attribute name='version' />
<filter type='and' >
<filter>
<condition attribute='ishidden' operator='eq' value='false' />
</filter>
</filter>
</entity>
</fetch>
詳細: FetchXML と FetchExpression の使用
ソリューションへのアセンブリの追加
登録済みアセンブリの表示で説明されているように、作成したアセンブリ登録はシステムの 既定のソリューション に追加されています。 アンマネージド ソリューションにアセンブリを追加する必要があるため、他の組織に配布できます。
使用しているアンマネージド ソリューション内で、ソリューション エクスプローラーを使用して プラグインアセンブリ に移動します。 リスト メニューで、既存を追加 を選択します。 次の図では、Common Data Service 既定のソリューションという名前のカスタムソリューションが使用されています。
次に、ソリューションにコンポーネントとしてアセンブリを追加します。
追加したプラグイン アセンブリを選択すると、含まれるプラグイン クラスを参照できます。
注意
既存またはそれ以降のステップ登録は、プラグイン アセンブリを含むアンマネージド ソリューションに追加されません。 ソリューションに、各登録手順を個別に追加する必要があります。 詳細情報: ソリューションへのステップの追加
プラグイン ステップの登録
アセンブリが読み込まれるかアップロードされたら、IPlugin を実装するクラスが PRT で使用可能になります。 チュートリアル: プラグインの作成と登録にある新しいステップの登録の手順を使用して、新しいステップ登録を作成します。
ステップを登録する際、イベント パイプラインのステージと、応答するコードを登録する操作の性質に応じて、数多くのオプションを利用できます。
一般的な構成情報フィールド
| フィールド | 説明 |
|---|---|
| メッセージ | PRT は、システムの使用可能なメッセージ名をオートコンプリートします。 詳細: メッセージを組織サービスと共に使用する |
| 主エンティティ | PRT は、選択したメッセージに適用される有効なテーブルをオート コンプリートします。 これらのメッセージには、Entity または EntityReference 型を受け入れる Target パラメーターがあります。 有効なテーブルが適用される場合、プラグインが呼び出される回数を制限するときにこれを設定する必要があります。 Update、Delete、Retrieve、RetrieveMultiple のようなコア テーブルメッセージまたは、メッセージとともに適用できるメッセージを空白のままにしている場合は、このメッセージをサポートするすべてのテーブルに対してプラグインが呼び出されます。 |
| 副エンティティ | このフィールドは、Target パラメーターとしての EntityReference の配列を受け入れた廃止されたメッセージの下位互換性を保つために残されています。 このフィールドは、通常は使用されなくなりました。 |
| フィルタリング属性 | Update または OnExternalUpdated メッセージでは、プライマリ エンティティ を設定する際、列をフィルタリングすると、選択した列が更新に含まれる場合にプラグインの実行が制限されます。 これはパフォーマンスのベスト プラクティスです。 |
| イベント ハンドラー | この値は、アセンブリの名前とプラグイン クラスに基づいて設定されます。 |
| ステップ名 | ステップの名前。 値は、ステップの構成に基づいて事前設定されますが、この値は変更できます。 |
| ユーザーのコンテキストで実行 | ステップの偽装を適用するためのオプションを提供します。 既定の値は 呼び出し元ユーザー です。 呼び出し元ユーザーに、ステップで操作を実行する特権がない場合、これらの特権を持つユーザーにこれを設定する必要があります。 詳細情報: ユーザーを偽装する |
| 実行順序 | 同じメッセージの同じステージに対して複数のステップを登録することができます。 このフィールドの番号で、低いものから順に適用するように指定します。 注: ステージでプラグインが適用される順序を制御するには、このオプションを設定します。 既定値をそのまま受け入れることは推奨されません。 (同じステージ、テーブル、およびメッセージの) 実行順序値が同じプラグインの実際の実行順序は保証されておらず、ランダムである可能性があります。 |
| 説明 | ステップの説明です。 この値は、事前設定されますが、上書きできます。 |
実行のイベント パイプライン ステージ
プラグインの目的に最適なイベント パイプラインのステージを選択します。
| オプション | 説明 |
|---|---|
| 事前検証 | 初期操作の場合、このステージはメイン システム操作の前に発生します。 これにより、データベース トランザクションの前に操作をキャンセルするためのロジックを組み込む機会が提供されます。 他のステージに登録された拡張機能によってトリガーされる後続の操作も、このステージを通過しますが、呼び出し元拡張機能のトランザクション内に組み込まれます。 このステージはセキュリティ チェックが実行される前に発生し、呼び出し元ユーザーまたはログオンしたユーザーが目的の操作を実行するための適切なアクセス許可を持っていることを確認します。 |
| 事前操作 | メイン システム操作の前に、データベース トランザクション内で発生します。 メッセージに含まれているエンティティの値を変更する必要がある場合は、ここで変更する必要があります。 ここではアクションをキャンセルしないでください。 キャンセルするとトランザクションのロールバックがトリガーされ、パフォーマンスに大きな影響があります。 |
| PostOperation | メイン システム操作の後、データベース トランザクション内で発生します。 このステージは、呼び出し元にメッセージを戻す前に、メッセージのプロパティを変更するために使用します。 メッセージに含まれているエンティティに変更を適用することは避けてください。変更を適用すると、新しい更新イベントがトリガーされるからです。 PostOperation ステージ内で、非同期実行モードを使用するためのステップを登録できます。 これらのステップは、非同期サービスを使用してデータベース トランザクションの外部で実行されます。 詳細については「非同期サービス」を参照してください。 |
詳細: イベント実行パイプライン
実行モード
非同期実行と同期実行の 2 つのモードがあります。
| オプション | 説明 |
|---|---|
| 非同期 | 操作の完了後に実行するシステム ジョブに、適用するビジネス ロジックの実行コンテキストと定義が移動されます。 |
| 同期 | プラグインは、実行の段階および実行順序に応じてすぐに実行されます。 すべての操作全体が、これらが完了するまで待機します。 |
非同期プラグインは PostOperation ステージでのみ登録することができます。 システム ジョブのしくみの詳細については、非同期サービスを参照してください。
特別なステップの登録シナリオ
ステップの登録とテーブルの組み合わせが明確でない特定のシナリオがあります。 これは、テーブルまたは操作の間に特別な関係があるシステムが内部でどのように設計されているかによります。 以下の情報は、これらのケースを識別し、ステップの登録ガイダンスを提供します。
- 更新 イベントに登録されたプラグインは 2 回呼び出される場合があります。 詳細: 特化された更新操作の動作
- データを customeraddress、leadaddress、publisheraddress、または competitoraddress のテーブル インスタンスに変更する場合、取引先企業 や 取引先担当者 のプラグインステップを登録します。
展開
| 回答内容 | 内容 |
|---|---|
| サーバー | プラグインは、Dataverse サーバーで実行されます。 |
| オフライン | プラグインは、ユーザーがオフライン モードになると Dynamics 365 for Outlook クライアント内で実行されます。 |
構成データの設定
PRT の 安全でない構成 フィールドや 安全な構成 フィールドを使用すると、特定のステップでプラグインに渡す構成データを指定できます。
注意
ソリューションをエクスポートする場合、セキュリティで保護された構成データはステップ登録に含まれません。
このデータを使用してプラグインがステップでどのように機能するかを制御するために、コンストラクターの文字列値を受け入れるようにプラグインを作成できます。 詳細: プラグインへの構成データの引き渡し
エンティティ イメージの定義
プラグイン内で、操作に含まれていなかったプライマリ テーブルのプロパティ値を参照する必要がある場合があります。 たとえば、Update 操作では、変更前の値を知ることができますが、実行コンテキストはこの情報を提供しておらず、変更された値のみが含まれます。
プラグイン ステップが実行パイプラインの PreValidation または PreOperation ステージに登録されている場合、組織サービスを使用してプロパティの現在の値を取得できますが、これはパフォーマンス上お勧めしません。 より優れたプラクティスは、プラグイン ステップ登録を使用してプレエンティティ イメージを定義する方法です。 これにより、変更された値と比較するために使用できる操作の前に存在していた、関心のあるフィールドを含むテーブルの「スナップショット」がキャプチャされます。
エンティティ イメージをサポートするメッセージ
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 の拡張機能を使用して、プラグイン ステップに エンティティ画像を追加します。
または、セクション画像を追加する 配下の チュートリアル: プラグインを更新する の指示に従い、プラグイン登録ツールを使用してステップにエンティティ画像を追加できます。
ソリューションへのステップの追加
ソリューションへのアセンブリの追加で説明されているように、プラグイン アセンブリ は、アンマネージド ソリューションに追加できるソリューション コンポーネントです。 SDK メッセージ処理手順 は、ソリューション コンポーネントでもあり、配布する順序でアンマネージド ソリューションに追加する必要もあります。
ソリューションにステップを追加する手順は、アセンブリの追加に似ています。 既存の追加 コマンドを使用して、それを目的のアンマネージド ソリューションに移動します。 唯一の違いは、ステップを追加しようとしましたが、そのステップで使用されたクラスを含むアセンブリをまだ追加していない場合に、不足している必須ココンポーネントを追加するように求められることです。
これが発生した場合は、通常、OK を選択し、アンマネージド ソリューションと共にアセンブリを持ち込む必要があります。 これを選択しないのは、アセンブリを含む別のソリューションがすでにインストールされている環境にソリューションがインストールされるように設計されている場合のみです。
同様に、ソリューションからアセンブリを削除しても、それに依存するステップは削除されないことに注意してください。
アセンブリの更新
以前登録したアセンブリを変更して再構築する場合は、それを更新する必要があります。 ステップについては、チュートリアル: プラグインの更新にあるプラグイン アセンブリ登録の更新ステップを参照してください。
アセンブリ バージョン管理
デプロイされた管理ソリューションの一部であるプラグイン アセンブリに変更を加える場合は、その管理ソリューションを更新するときに変更が与える可能性のある影響を考慮する必要があります。 アセンブリのバージョンによって動作が制御されます。
プラグイン アセンブリは、Microsoft Visual Studio プロジェクトの Assembly.info ファイルで定義されている major.minor.build.revision のセマンティック バージョン形式を使用してバージョンを管理できます。 新しいソリューションでアセンブリ バージョン番号のどの部分が変更されるかにより、インポートによって既存のソリューションが更新されるときに、次の動作が適用されます。
ビルドまたはリビジョンのアセンブリ バージョン番号が変更されます
これは一括アップグレードと見なされます。 更新されたアセンブリを含むソリューションがインポートされると、アセンブリの古いバージョンは削除されます。 古いソリューションの既存の手順は、新しいバージョンのアセンブリを参照するように自動的に変更されます。
メジャーまたはマイナー アセンブリ バージョン番号が変更されます
改訂されたアセンブリを含む更新されたソリューションをインポートした場合、アセンブリは、既存のソリューションのそのアセンブリの以前のバージョンとは異なるアセンブリと見なされます。 既存ソリューション内のプラグイン登録手順では、引き続き古いバージョンのアセンブリが参照されます。 以前のアセンブリの既存のプラグイン登録ステップが改訂されたアセンブリを指すようにする場合は、Plugin Registration Tool を使用して、改訂されたアセンブリタイプを参照するようにステップ構成を手動で変更する必要があります。 この作業は、後でインポートするために更新後のアセンブリをソリューションにエクスポートする前に行う必要があります。
プラグイン コンポーネントの登録解除または無効化
プラグイン コンポーネントを登録解除または無効化できます。
コンポーネントの登録解除
PRT は、アセンブリ、種類、ステップ、イメージの登録を解除するコマンドを提供します。 手順については、チュートリアル: プラグインの更新のアセンブリ、プラグイン、ステップの登録解除の手順を参照してください。
これらは、PluginAssembly、PluginType、SdkMessageProcessingStep、SdkMessageProcessingStepImage のテーブル上での削除操作です。
ソリューション エクスプローラーで プラグイン アセンブリ と Sdk メッセージ処理ステップ を削除して、同じ結果を生み出すこともできます。 次の図では、Common Data Service規定のソリューションという名前のカスタムソリューションが表示されます。
注意
プラグイン アセンブリ を削除することはできませんが、既存の Sdk メッセージ処理ステップ はそれに依存しています。 エンティティ イメージは別々に削除できませんが、それらを使用するステップが削除されると削除されます。
ステップの無効化
PRT にはステップを無効化および有効化するコマンドがあります。
アクティブ化 と 非アクティブ化 コマンドを使用して、ソリューション エクスプローラーでステップを無効にすることもできます。
次の手順
関連項目
ビジネス プロセスを拡張するためのプラグインの作成
プラグインを記述する
チュートリアル: プラグインを書き込み登録する
チュートリアル: プラグインをデバッグする
チュートリアル: プラグインを更新する
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。
フィードバック
フィードバックの送信と表示