Visual Studio を使用してプラグインを作成する

[アーティクル]
03/26/2024

この記事には、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 Tools プロジェクトを作成するに移動してください。

すでに既存のソリューションが設定されている場合は、新規プロジェクトを 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 サーバーにアップロードする前にデジタル署名されている必要があります。アセンブリへの署名は、次の手順に従ってください。

ソリューションエクスプローラーでプラグインまたはワークフロー活動プロジェクトを選択します。
プロジェクト><プロジェクト名>プロパティ を選択して、プロジェクトのプロパティを編集します。
署名タブで、アセンブリに署名するをチェックして、厳密な名前のキーファイルを指定します。

環境ソリューションにプラグインをデプロイする

コードの修正が終わり、プラグインアセンブリとステップを環境にデプロイする準備ができたら、以下の手順に従ってください。

プラグインライブラリをビルドします。
ソリューションエクスプローラー でプラグインのライブラリプロジェクトを右クリックします。
コンテキストメニューで プロパティ を選択します。

チップ

CrmPackage プロジェクトを右クリックしてデプロイを選択すると、Visual Studio ソリューションのすべてのプロジェクトをデプロイすることができます。

デプロイの完了後は、Power Platformエクスプローラーで更新アイコンを選択します。環境ノードの プラグインアセンブリ サブノードを展開すると、登録されたアセンブリが表示されます。プラグインアセンブリを右クリックして Power Platform エクスプローラー にステップインし、サポートしている操作を確認します。 アセンブリを削除する を選択すると、アセンブリとそれに関連した手順の登録が解除されます。

エンティティイメージの追加

エンティティイメージとは、コア操作 (例: 作成、更新) の前または後で取得したエンティティデータのスナップショットです。 (オプション) Power Platform エクスプローラー ビューを使用してプラグインステップにエンティティイメージを追加できます。 Power Platform エクスプローラー ビューのステップにイメージを追加する場合は、プラグインアセンブリ ノードツリーを展開して対象のプラグインステップを表示してから、ステップを右クリックして、コンテキストメニューで イメージを追加する を選択します。

ステップにイメージを追加します。

また、イベントプラグインのステップから イベントカタログ 配下の Power Platform エクスプローラー ビューに画像を追加できます。

イベントステップにイメージを追加します。

コンテキストメニューで イメージを追加する を選択してから、表示されるフォームに入力します。

エンティティイメージを定義する。

このフォームの プレイメージ/ポストイメージ は、コア操作の前 (プレ) または後 (ポスト) に存在するエンティティデータを指定します。名前フィールドには、データを求める対象のエンティティが持つ論理名を定義します。 エンティティエイリアス は、対象のエンティティデータを含む画像テーブルの行を識別するためにコードで使用する、名前付きインデックスです。 パラメーター は必要なエンティティデータ列のリストです。指定する列が多いほどプラグインのパフォーマンスが低下するため、必要な列のみを指定します。

詳細情報: エンティティイメージを定義する。

ツールのフィードバックを提供する

ツールのフィードバックは、Power Platform エクスプローラービューのフィードバックアイコンを使ってマイクロソフトに送信できます。

フィードバックを提供します。

次の方法で共有

Visual Studio を使用してプラグインを作成する

前提条件

プラグインライブラリでソリューションを作成する

Dataverse でプラグインステップを登録する

別のプラグインクラスをライブラリに追加する

プラグインステップを追加する

PluginBase の抽象クラス

生成されたプラグインクラスコード

アセンブリにサインする

環境ソリューションにプラグインをデプロイする

エンティティイメージの追加

ツールのフィードバックを提供する

関連情報

その他のリソース

次の方法で共有

Visual Studio を使用してプラグインを作成する

前提条件

プラグイン ライブラリでソリューションを作成する

Dataverse でプラグイン ステップを登録する

別のプラグイン クラスをライブラリに追加する

プラグイン ステップを追加する

PluginBase の抽象クラス

生成されたプラグイン クラス コード

アセンブリにサインする

環境ソリューションにプラグインをデプロイする

エンティティ イメージの追加

ツールのフィードバックを提供する

関連情報

その他のリソース

プラグインライブラリでソリューションを作成する

Dataverse でプラグインステップを登録する

別のプラグインクラスをライブラリに追加する

プラグインステップを追加する

生成されたプラグインクラスコード

エンティティイメージの追加