クイックスタート: Power Platform Tools を使用してプラグインを作成する
この記事には、Visual Studio 用 Power Platform Tools 拡張機能を使用して、プラグインを作成する方法に関する情報が含まれています。
前提条件
- Visual Studio 2019 または 2022
- Visual Studio 向け Power Platform Tools の拡張機能
- プラグインまたはカスタムワークフロー活動開発には .NET Framework 4.6.2 が必要です
- Power Apps サブスクリプションまたは試用環境
プラグイン ライブラリでソリューションを作成する
この手順に従って、プラグイン ライブラリでソリューションを作成し、Power Platform 環境に接続して、カスタム コードのアセンブリやステップなどを登録できます。
Visual Studio 用 Power Platform Tools の拡張機能を使用して、プラグイン ライブラリで新しいソリューションを作成します。 手順については、Power Platform 開発者ガイドの Power Platform Tools プロジェクトを作成するに移動してください。
すでに既存のソリューションが設定されている場合は、Power Platform の Power Platform ソリューションに新しいプロジェクトを追加する に記載されている手順に従い、Power Platform Tools テンプレートを使用してプラグイン ライブラリのプロジェクトをソリューションに追加します。
ツール メニューで、Dataverse に接続を選択します。
ダイアログで必要なオプションを選択し、ログイン を選択します。
既存のソリューション、または 既定の ソリューションを選択します。 ソリューションには、後で他の環境に配布できるように、登録済みのプラグインとワークフロー活動アセンブリが含まれます。
完了したら、完了 を選択します。
Power Platform エクスプローラー ビューが表示されるか、またはビュー メニューからそのビューを開くこともできます。 ノードを展開して、表示できる環境データの種類を確認します。 ノードを右クリックして、使用可能なオプションを確認します。
注意
Power Platform Tools の拡張機能の Power Platform エクスプローラー ビューでは、プラグインやワークフローのアクティビティ登録やその他の機能を搭載しています。 追加機能のドキュメントは、将来のドキュメント リリースで提供予定です。 それまでの間は、自由に探索してください。
Dataverse でプラグイン ステップを登録する
次の手順に従って、プラグインステップ (SDK メッセージ処理ステップとも呼ばれます) を登録します。 このステップでは、どのデータテーブルとイベントによってプラグインを実行するかを指定します。 詳細情報: イベント フレームワーク、プラグイン ステップの登録
ビュー > Power Platform エクスプローラーを選択し、環境ノードとテーブル サブノードを展開します。
ステップを登録するテーブルタイプ (例: 「アカウント」) を右クリックし、プラグインの作成を選択します。
注意
また、イベント カタログ を展開してビジネス イベントを右クリックし、プラグインを追加する を選択してもプラグインを作成できます。
新規ステップの登録ダイアログの情報を入力し、完了後は新規ステップの登録を選択します。
ステップ情報の入力時に指定したクラス名は、新しいプラグイン クラスの名前として使用されます。 このクラスは、ハンドラー アセンブリ ダイアログ フィールドで指定したプラグイン プロジェクト ライブラリに配置されます。 ソリューションにプラグイン ライブラリ プロジェクトが 1 つしかない場合、ハンドラー アセンブリ フィールドは非アクティブになります。
ソリューションに新たなステップ登録が加わりました。 ただし、プラグイン アセンブリや手順を指定した Dataverse 環境やソリューションに追加する前に、プラグイン ライブラリをビルドしてデプロイする必要があります。
別のプラグイン クラスをライブラリに追加する
上記の手順に従ってプラグイン プロジェクト ライブラリにプラグイン クラスを作成し、ステップを追加したと仮定します。 次に、別のプラグイン クラスを同じライブラリに追加します。 具体的なやり方 オプションが 2 つあり、どちらも Power Platform Tools 拡張機能のコンテキスト メニューを使用します。
最初の方法は上記と同じ操作であり、Power Platform エクスプローラー ビューで テーブル ノードを展開し、テーブル タイプを右クリックして プラグインを作成する を選択します。 ステップを登録する場合は、ハンドラー アセンブリ で同じプラグイン プロジェクト ライブラリと、クラス名 フォーム フィールドで新しいクラス名を指定します。
2 つ目の方法では、プラグイン ライブラリ アセンブリをすでにビルドして Dataverse 環境に展開したと仮定します。 この場合、エクスプローラー ビューを更新して プラグイン アセンブリ ノードを展開すると、展開したアセンブリと作成したステップが表示されます。 その時点で、対象のアセンブリ ノードをただ右クリックして プラグインを追加する を選択します。 この操作によってステップ登録フォームが表示され、新しいプラグイン クラスに入力できます。
その後、プラグイン ライブラリ プロジェクトをビルドして展開し、対象の環境とソリューションを更新します。
プラグイン ステップを追加する
所有する既存の登録済みプラグインのステップを追加できます。 その方法は、Power Platform エクスプローラー ビューで対象のプラグイン アセンブリ ノードを展開し、登録済みのプラグインを表示します。 そのプラグインのノードを右クリックして ステップを追加する を選択します。 新しいステップを登録する フォームに必要事項を記入します。
対象の環境とソリューションでステップ登録を使用できるようにするために、プラグイン プロジェクトのビルドと展開は必要はありません。
PluginBase の抽象クラス
PluginBase はプラグイン ライブラリのテンプレートから自動的に生成されます。 カスタム プラグイン クラスは、この基本クラスから派生する必要があります。 ベースクラスは、生産性の向上に役立つ一般的なプラグインコードを実装しています。 プラグインプロジェクトの PluginBase クラスのコードを確認し、機能をご確認ください。
生成されたプラグイン クラス コード
プラグイン ライブラリ テンプレートでは，抽象クラス PluginBase を提供しています。 Power Platform Tools の拡張機能とうまく連動させるには、プラグインが PluginBase から派生している必要があります。 以下は、Power Platform エクスプローラーからプラグインを作成した場合に生成される派生クラスです。 通常、TODO コメントがある場所にコードを追加します。 プラグイン コードでは、標準的なIPlugin インターフェースの Execute メソッドが ExecuteCdsPlugin に置き換えられていることに注意してください。
using System;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;
namespace PPTools_Sample_Solution.NotifyPlugin
{
public class NotifyAccountCreate: PluginBase
{
public NotifyAccountCreate(string unsecure, string secure)
: base(typeof(NotifyAccountCreate))
{
// TODO: Implement your custom configuration handling.
}
protected override void ExecuteCdsPlugin(LocalPluginContext localContext)
{
if (localContext == null)
{
throw new InvalidPluginExecutionException(nameof(localContext));
}
ITracingService tracingService = localContext.TracingService;
try
{
IPluginExecutionContext context = (IPluginExecutionContext)localContext.PluginExecutionContext;
IOrganizationService service = localContext.OrganizationService;
// TODO: Implement your custom Plug-in business logic.
}
catch (Exception ex)
{
tracingService?.Trace("An error occurred executing Plugin PPTools_Sample_Solution.NotifyPlugin.NotifyAccountCreate : {0}", ex.ToString());
throw new InvalidPluginExecutionException("An error occurred executing Plugin PPTools_Sample_Solution.NotifyPlugin.NotifyAccountCreate .", ex);
}
}
}
}
この時点で、TODO コードのコメントで示されている場所に、カスタム プラグイン コードを追加します。 詳細については、次の関連トピックを参照してください: 構成データをプラグインに渡す、実行コンテキストを理解する、とトレースとログ。
重要
Power Platform Tools のコンテキスト メニューを使用することを推奨します。 Power Platform エクスプローラーのコンテキスト メニューを使用してプラグインを追加する場合、提供された情報を使用してクラスが生成され、CrmPackage プロジェクトの RegisterFile.crmregister ファイルの展開エントリを維持します。 アセンブリ、プラグイン、ステップの展開には、この情報を使用します。
アセンブリにサインする
すべてのプラグインとカスタム ワークフローのアセンブリは、Dataverse サーバーにアップロードする前にデジタル署名されている必要があります。 アセンブリへの署名は、次の手順に従ってください。
ソリューション エクスプローラーでプラグインまたはワークフロー活動プロジェクトを選択します。
計画 > <project name>プロパティを選択してプロジェクトのプロパティを編集します。
署名タブで、アセンブリに署名するをチェックして、厳密な名前のキーファイルを指定します。
環境ソリューションにプラグインをデプロイする
コードの修正が終わり、プラグイン アセンブリとステップを環境にデプロイする準備ができたら、以下の手順に従ってください。
プラグイン ライブラリをビルドします。
ソリューション エクスプローラー でプラグインのライブラリ プロジェクトを右クリックします。
コンテキスト メニューで プロパティ を選択します。
ヒント
CrmPackage プロジェクトを右クリックしてデプロイを選択すると、Visual Studio ソリューションのすべてのプロジェクトをデプロイすることができます。
デプロイの完了後は、Power Platformエクスプローラーで更新アイコンを選択します。 環境ノードの プラグイン アセンブリ サブノードを展開すると、登録されたアセンブリが表示されます。 プラグイン アセンブリを右クリックして Power Platform エクスプローラー にステップ インし、サポートしている操作を確認します。 アセンブリを削除する を選択すると、アセンブリとそれに関連した手順の登録が解除されます。
エンティティ イメージの追加
エンティティ イメージとは、コア操作 (例: 作成、更新) の前または後で取得したエンティティ データのスナップショットです。 (オプション) Power Platform エクスプローラー ビューを使用してプラグイン ステップにエンティティ イメージを追加できます。 Power Platform エクスプローラー ビューのステップにイメージを追加する場合は、プラグイン アセンブリ ノード ツリーを展開して対象のプラグイン ステップを表示してから、ステップを右クリックして、コンテキスト メニューで イメージを追加する を選択します。
また、イベント プラグインのステップから イベント カタログ 配下の Power Platform エクスプローラー ビューに画像を追加できます。
.png)
コンテキスト メニューで イメージを追加する を選択してから、表示されるフォームに入力します。
このフォームの プレ イメージ/ポスト イメージ は、コア操作の前 (プレ) または後 (ポスト) に存在するエンティティ データを指定します。 名前 フィールドには、データを求める対象のエンティティが持つ論理名を定義します。 エンティティ エイリアス は、対象のエンティティ データを含む画像テーブルの行を識別するためにコードで使用する、名前付きインデックスです。 パラメーター は必要なエンティティ データ列のリストです。 指定する列が多いほどプラグインのパフォーマンスが低下するため、必要な列のみを指定します。
詳細情報: エンティティ イメージを定義する。
次の手順
プラグインの開発について解説します
ツールのフィードバックを提供する
ツールのフィードバックは、Power Platform エクスプローラー ビューのフィードバックアイコンを使ってマイクロソフトに送信できます。
.png)
関連情報
Visual Studio 向け Power Platform Tools
Power Platform Tools プロジェクトを作成する
チュートリアル: プラグインをデバッグする
イベント フレームワーク
ビジネス プロセスを拡張するためのプラグインの使用
注意
ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)
この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。