依存アセンブリ プラグイン (プレビュー)

  • [アーティクル]

[このトピックはプレリリース ドキュメントであり、変更されることがあります。]

プラグイン内に別のアセンブリまたはリソース ファイルを含めることは、多くの場合有益です。 たとえば、Newtonsoft.Json.dll や別のアセンブリを使用する場合があるでしょう。 ローカライズした文字列リストにアクセスすべき場合もあります。

依存アセンブリがない場合、すべてのプラグインを個別の .NET Framework アセンブリとして登録します。 別のアセンブリを含める唯一の方法は、ILMerge を使用して 1 つに統合することです。 ILMerge は多くの企業で機能しましたが、Dataverse 決してサポートされておらず、常に機能するとは限りません。 ILMerge のメンテナンスは終了しています。

依存アセンブリでは、個別の .NETアセンブリを登録するのではなく、プラグイン アセンブリと依存アセンブリを含む NuGet パッケージをアップロードします。 この NuGet パッケージ ファイルは PluginPackage という新しいテーブルに格納されます。 NuGet パッケージのコンテンツは、SQL ではなくファイル ストレージに格納されます。

重要

  • これはプレビュー機能です。
  • プレビュー機能は運用環境での使用を想定しておらず、機能が制限される可能性があります。 これらの機能を公式リリースの前に使用できるようにすることで、顧客が一足先にアクセスし、そこからフィードバックを得ることができます。

本書では、以前、アセンブリラン タイムで利用可能な追加ファイルをプラグイン パッケージに含めるプロセスについて説明しました。 この機能ではサポートされません。 ランタイムがこれらのファイルへのアクセスを許可することを保証するものではありません。

NuGet パッケージをアップロードすると、 IPlugin Interface を実装するクラスを含むアセンブリはすべて PluginAssembly テーブルでに登録され、PluginPackage に関連付けられています。 プロジェクトを開発および保守する際、 PluginPackage の更新を継続すると、関連するプラグイン アセンブリへの変更がサーバー上で管理されます。

実行時に Dataverse は NuGet パッケージのコンテンツを PluginPackage 行からコピーし、サンドボックス ランタイムに抽出します。 この方法により、プラグインに必要な依存アセンブリを使用できます。

プラグイン アセンブリを個別に登録することもできますが、PluginPackage の使用が推奨されるアプローチになります。 現在のプラグイン プロジェクトが依存アセンブリへのアクセスを必要としない場合でも、依存アセンブリをサポートするように構成されたプロジェクトから開始すると、必要に応じて後で依存アセンブリを追加できます。 PluginPackage を使用して、既存のプラグイン アセンブリ プロジェクトを変換して使用する作業は予定されていません。

フィードバックを送信する

この機能に関する質問や問題がある場合は、テクニカル サポートにお問い合わせください。 ご提案がある場合は、Power Apps アイデア フォーラム サイトに投稿してください。

制限

次の制限が依存アセンブリ プラグインに適用されます。

  • ワークフロー拡張機能、ワークフロー アセンブリ、 ワークフロー アクティビティ または カスタム ワークフロー アクティビティ とも呼ばれていますが、これはサポートされていません。
  • 仮想テーブル データ プロバイダーのプラグインはサポートされていません。 仮想エンティティに登録されているプラグイン (依存アセンブリを含む) がソリューションに含まれている場合、環境へのソリューションのインポートは失敗します。
  • オンプレミスの 環境はサポートされていません。
  • アンマネージド コードはサポートされていません。 アンマネージド リソースへの参照を含めることはできません。

署名アセンブリ

プラグイン パッケージで使用されるプラグイン アセンブリに署名する必要はありません。

依存アセンブリ機能を使用せずに個々のプラグイン アセンブリを登録する場合は、アセンブリに一意の名前が付けられるため、署名が必要です。 ただし、プラグイン パッケージ内のプラグイン アセンブリの場合、アセンブリは別のメカニズムを使用してサンドボックス サーバーに読み込まれるため、署名は必要ありません。

注意

アセンブリに署名する場合、署名されたアセンブリは、署名されていないアセンブリに含まれるリソースを使用できないことに注意してください。 プラグイン アセンブリまたは依存アセンブリに署名する場合は、それらのアセンブリが依存するすべてのアセンブリに署名する必要があります。 署名されたアセンブリが署名されていないアセンブリに依存している場合、次のようなエラーが発生します: Could not load file or assembly '<AssemblyName>, Version=<Version>, Culture=neutral, PublicKeyToken=null' or one of its dependencies. A strongly-named assembly is required.

Microsoft Power Platform CLI (pac cli) を使用すると、既定の設定で自動的にアセンブリに署名されます。 --skip-signing パラメーターを使用して署名をオプトアウトする必要があります。 詳細: Visual Studio プロジェクトの作成。

Power Platform Tools はプラグイン アセンブリに署名しません。

ツール オプション

この機能は 2 つのツール オプションで使用できます:

ツール 概要
PAC CLI とプラグイン登録ツール (PRT) Microsoft Power Platform CLI は、開発者と ISV が、Microsoft Power Platform で環境ライフサイクル、認証関連のさまざまな操作を実行して、Microsoft Dataverse 環境、ソリューション パッケージ、ポータル、コード コンポーネントなどと作業できる、シンプルなワンストップ開発者 CLI です。

PRT は Windows アプリケーションであり、プラグイン アセンブリの登録を管理してプラグイン ステップを登録する際に使用できます。

次の手順を参照してください: PAC CLI と PRT を使用する
Visual Studio で Power Platform Tools を使用する Visual Studio の Power Platform Tools は、プラグインの迅速な作成、デバッグ、展開をサポートします。また、その他の機能には、カスタム ワークフロー活動、Web リソース、Azure Service エンドポイントや Webhooks などの統合技術の開発などが含まれます。

次の手順を参照してください: Power Platform Tools for Visual Studio を使用する

PAC CLI と PRT を使用する

PAC CLI を使用して Visual Studio プロジェクトを作成し、PRT でパッケージを管理して手順を登録します。

前提条件

この機能を PAC CLI と PRT で使用する場合は、これらのツールとアプリケーションを必ず使用してください。

ツール/アプリ 方法
Microsoft Power Platform CLI バージョン 1.17 以降が必要です。
Visual Studio Code を使用したインストール方法を推奨します。 Power Platform Tools を参照してください。

また、こちらから Windows 版をダウンロードし、インストールできます。: https://aka.ms/PowerAppsCLI。
Windows バージョンを既にインストールしている場合は、必ず pac install latest を実行して最新バージョンを取得してください。

詳細情報: Microsoft Power Platform CLI とは
PRT 必ず 9.1.0.184 以降のバージョンを使用してください。

これらの手順に従って最新バージョンをインストールします: Dataverse 開発ツール。
Visual Studio Visual Studio 2019 以降であることが必須です。

Visual Studio プロジェクトを作成する

PAC CLI pac plugin init コマンドを使用して、依存アセンブリを使用して開発プロセスを合理化する Visual Studio プロジェクトを作成します。

  1. プラグイン プロジェクト用のフォルダーを作成します。 このフォルダーの名前によって、プラグインの Visual Studio .NET Framework クラス ライブラリ プロジェクトの名前が決まります。

  2. Visual Studio Code で PowerShell ターミナル ウィンドウを開き、フォルダーに移動して pac plugin init コマンドを実行します。 プラグイン パッケージの場合は、プラグイン アセンブリが署名されないように --skip-signing パラメーターを使用することをお勧めします。

    例:

    PS E:\projects\mypluginproject> pac plugin init --skip-signing

注意

現在では依存アセンブリを使用する際にアセンブリに署名する必要はありません。 アセンブリに署名した場合は、すべての依存アセンブリにも署名する必要があります。 詳細: 署名アセンブリ

pac plugin init コマンドには、いくつかのオプションのパラメーターがあります。 プラグイン アセンブリに署名したくない場合は、--skip-signing パラメーターを使用する必要があります。

これらのコマンドは、作成されたフォルダーの名前に基づいて、Visual Studio .NET Framework クラス ライブラリ プロジェクトを作成します。

Visual Studio ソリューション構成に応じて、Visual Studio で Visual Studio プロジェクトを開いてビルドすると、bin\Debug または bin\Release フォルダー内のプロジェクトに対して NuGet パッケージが生成されます。 プロジェクトをビルドするたびに、この NuGet パッケージが更新されます。 NuGet パッケージは、プラグイン登録ツールを使用してアップロードするファイルです。

NuGet を使用して依存アセンブリを追加する

通常どおり、NuGet パッケージを Visual Studio プロジェクトに追加できます。 プロジェクトをビルドすると、NuGet パッケージにアセンブリが生成されます。

NuGet パッケージ エクスプローラー を使用して NuGet パッケージを検証できます。

NuGet 使用せずに依存アセンブリを追加する

NuGet パッケージとして配布されていないアセンブリがある場合は、通常どおりプロジェクトに追加できます。 ソリューション エクスプローラーで Dependencies を右クリックし、アセンブリ参照の追加... を選択します。そして追加したいアセンブリを選択します。

プラグイン登録ツールを使用する

プラグイン登録ツール (PRT) を使用して、次のタスクを実行できます:

  1. 利用できるプラグイン パッケージのリストを表示します。
  2. NuGet パッケージをプラグイン パッケージとして登録します。
  3. プラグイン パッケージを更新します。
  4. プラグイン パッケージを削減します。

利用できるプラグイン パッケージのリストを表示する

PRT には新しい パッケージごとに表示する ビューがあり、以前にインポートしたプラグイン パッケージを一覧表示できます:

プラグイン登録ツールを使用して、プラグイン パッケージのリストを表示します。

NuGet パッケージをプラグイン パッケージとして登録する

PRT には新しいコマンドがあり、プラグイン パッケージとしてインポート/登録する NuGet パッケージを選択できます。

プラグイン登録ツールを使用してプラグイン パッケージを登録するコマンド。

このコマンドにより、プラグイン パッケージを選択するためのダイアログが開きます。

既存のソリューションを選択するか、新しいソリューションを作成できます。

新しいプラグイン パッケージをインポートするダイアログ。

パッケージごとに表示する ビューから、アセンブリと登録の手順を選択できます。

新しくアップロードしたプラグイン パッケージを [パッケージごとに表示する] ビューに表示します。

このアセンブリは パッケージごとに表示する ビューでも使用できます。

アセンブリごとに表示ビューでプラ​​グイン パッケージ アセンブリを表示します。

プラグイン パッケージを更新する

パッケージ別表示 ビューを使用してプラグイン パッケージのリストを表示しているときに、プラグイン パッケージを選択し、更新 コマンドを選択します。

プラグイン パッケージを選択した状態で更新コマンドを表示します。

このコマンドによりダイアログが開き、変更のある NuGet パッケージを選択できます。

プラグイン パッケージの更新ダイアログ。

重要

プラグイン アセンブリやプラグイン ステップの登録で使用するタイプを更新が削除する場合、その更新は拒否されます。 更新によって削除する、プラグイン アセンブリやプラグイン タイプを使用しているステップ登録を、手動ですべて削除する必要があります。

プラグイン パッケージやプラグイン アセンブリのバージョンは、アップグレード動作に影響しません。 こうした項目のバージョンは、必要に応じて更新できます。

プラグイン パッケージを削減する

パッケージ別表示 ビューを使用してプラグイン パッケージのリストを表示しているときに、プラグイン パッケージを選択し、登録解除 コマンドを選択します。

プラグイン パッケージを選択した状態で登録解除コマンドを表示します。

重要

パッケージが含む任意のプラグイン アセンブリに対して、プラグイン ステップ登録を持つパッケージの登録は解除できません。 パッケージを削除する前に、まずパッケージが含むアセンブリのステップ登録をすべて解除する必要があります。

Visual Studio で Power Platform Tools を使用する

Visual Studio 向け Power Platform Tools は、Visual Studio プロジェクトを作成してパッケージを管理し、手順を登録します。

前提条件

この機能を Visual Studio 向け Power Platform Tools で使用する際は、Visual Studio 2019 を用意し、さらに Visual Studio 向け Power Platform Tools をインストールする必要があります。

プラグインを操作するための Power Platform Tools for Visual Studio ツールのインストールと使用に関連する次の記事を参照してください。

通常は、Power Platform Tools for Visual Studio ツールを使用して同じプロセスでプラグインを作成および管理しますが、アセンブリへの署名は必要なくなりました。 詳細: 署名アセンブリ。

Power Platform Tools のプラグイン パッケージを有効化する

Visual Studio 向け Power Platform Tools は、Power Platform Tools オプション の説明に従って、いくつかの構成オプションを提供します。

  1. Visual Studio で ツール > オプション に移動し、Power Platform Tools を検索します。

  2. NuGet パッケージを使用してプラグインを Dataverse に展開する を選択します。

    Dataverse にプラグインをデプロイするために、NuGet パッケージを使用するを選択します。

注意

このオプションを選択すると、すべてのプラグイン プロジェクトをプラグイン パッケージと共に展開します。

Power Platform Tools とともに NuGet を使用して依存アセンブリを追加する

通常どおり、NuGet パッケージを Visual Studio プロジェクトに追加できます。 プロジェクトをビルドすると、NuGet パッケージにアセンブリが生成されます。 NuGet パッケージは bin\outputPackages フォルダにあります。

NuGet パッケージ エクスプローラー を使用して NuGet パッケージを検証できます。

Power Platform Tools で NuGet を使用せず依存アセンブリを追加する

NuGet パッケージとして配布されていないアセンブリがある場合は、通常どおりプロジェクトに追加できます。 ソリューション エクスプローラーで Dependencies を右クリックし、アセンブリ参照の追加... を選択します。そして追加したいアセンブリを選択します。

Power Platform Tools のプラグイン パッケージを展開する

プラグイン パッケージを展開する際は、ソリューション エクスプローラー でプラグイン プロジェクトを右クリックし、コンテキスト メニューから 展開 を選択します。

foo

初めて展開する際は、プラグイン パッケージの作成完了を通知するメッセージが出力ウィンドウに表示されます:

6/22/2022 3:03:17 PM : registration of Plugin Package sample_PowerPlatformVSSolution.ExamplePlugins, 
at E:\projects\PowerPlatformVSSolution\ExamplePlugins\bin\outputPackages\PowerPlatformVSSolution.ExamplePlugins.1.0.0.nupkg was successful. 
ID allotted was 06a20e15-77f2-ec11-bb3c-000d3a892245.

その後デプロイするたびに、プラグイン パッケージが更新されたことを通知するメッセージが出力ウィンドウに表示されます。

6/22/2022 3:20:14 PM : update of Plugin Package sample_PowerPlatformVSSolution.ExamplePlugins, at
E:\projects\PowerPlatformVSSolution\ExamplePlugins\bin\outputPackages\PowerPlatformVSSolution.ExamplePlugins.1.0.0.nupkg was successful.

重要

プラグイン アセンブリやプラグイン ステップの登録で使用するタイプを更新が削除する場合、その更新は拒否されます。 更新によって削除する、プラグイン アセンブリやプラグイン タイプを使用しているステップ登録を、手動ですべて削除する必要があります。

プラグイン パッケージやプラグイン アセンブリのバージョンは、アップグレード動作に影響しません。 こうした項目のバージョンは、必要に応じて更新できます。

Power Platform Tools でプラグイン パッケージを表示する

Power Platform エクスプローラーで、使用できるプラグイン パッケージを表示できます。

Power Platform エクスプローラーで、使用できるプラグイン パッケージを表示できます

Power Platform Tools でプラグイン パッケージを削除する

Power Platform エクスプローラーでプラグイン パッケージを選択し、コンテキスト メニューから 削除 を選択します。

プラグイン パッケージを選択し、コンテキスト メニューから [削除] を選択します

重要

パッケージの削除すると、パッケージ、パッケージが含むすべてのアセンブリ、アセンブリが含むすべてのプラグイン、プラグインのすべてのプラグイン ステップ登録が削除されます。

Power Platform Tools でプラグイン パッケージを作成する

注意

Power Platform Tools のプラグイン パッケージを展開する で述べた通り、プラグインを作成する通常のフローではプラグイン パッケージの作成は必要ありません。 Visual Studio で NuGet パッケージを使用してプラグインを Dataverse に展開する オプションを設定した状態でプラグインを初めて展開すると、自動的に作成されます。 ただし、次の手順を使用して、Nuget パッケージから新しいプラグイン パッケージを作成できます。

  1. Power Platform エクスプローラーで プラグイン パッケージ を選択し、コンテキスト メニューから 作成 を選択します。

    Power Platform エクスプローラーで プラグイン パッケージ を選択し、コンテキスト メニューから [作成] を選択します。

  2. このコマンドにより、新しいプラグイン パッケージのインポート ダイアログが開きます。

    新しいプラグイン パッケージを **インポートするダイアログ

    NuGet パッケージを選択して、追加するソリューションを選択するか、新しいソリューションを作成します。

Power Platform Tools でプラグイン パッケージを更新する

注意

Power Platform Tools のプラグイン パッケージを展開する で述べた通り、プラグインを作成する通常のフローではプラグイン パッケージの更新は必要ありません。 Visual Studio で NuGet パッケージを使用してプラグインを Dataverse に展開する オプションを設定した状態でプラグインを展開するたびに、自動的に更新されます。 なお、以下の手順で NuGet パッケージから新しいプラグイン パッケージを更新できます。

Power Platform エクスプローラー でプラグイン パッケージを選択し、コンテキスト メニューから 更新 を選択します。

プラグイン パッケージを選択し、コンテキスト メニューから [更新] を選択します

このコマンドによりダイアログが開き、NuGet パッケージを選択してプラグイン パッケージを更新できるようになります。

設計メモ

ここでは、プラグイン パッケージを作成する際に考慮すべき点をいくつか示します。

NuGet パッケージを生成する

Visual Studio pac plugin init を使用して作成された プロジェクトは、 NuGetパッケージの生成を可能にする Visual Studio 機能を使用します。 この方法では SDK スタイル プロジェクト形式を使用します。 Visual Studio 向け Power Platform Tools は 非 SDK スタイル プロジェクト形式を使用します。

プラグインで NuGet パッケージを生成するためにこれらのツールを使用する必要はありません。選択した機能を使用して、NuGet パッケージをアップロードできますが、パッケージを Dataverse にアップロードするために利用可能なツールを使用する必要があります。

詳細情報:

パッケージに含まれないもの

プラグイン パッケージを作成および登録するときに、標準 Dataverse アセンブリがパッケージに含まれていると、パッケージ登録時にエラーが発生するという問題が発生することがあります。

重要

以下の Dataverse アセンブリをパッケージに含めないでください。 これを行うと、パッケージの登録時にエラーが発生します。

Microsoft.Crm.Sdk.Proxy.dll
Microsoft.Xrm.Sdk.dll
Microsoft.Xrm.Sdk.Workflow.dll
Microsoft.Xrm.Sdk.Data.dll
Microsoft.Crm.Sdk.dll

これらのアセンブリのいずれかをプラグイン パッケージに含めると、プラグイン パッケージを Dataverse に登録するときに次のエラー メッセージが表示されます:

"PluginPackage には、Microsoft.CrmSdk.CoreAssemblies または Microsoft.CrmSdk.Workflow nuget パッケージに含まれるアセンブリを含めることはできません。"

この状況を修正するには、この 依存関係アセットの制御 記事の情報に従って、これらの依存関係アセットがパッケージに含まれないようにします。 プロジェクト構成ファイル (.csprog) で <PrivateAssets> タグを使用して、アセンブリ参照をマークする必要があります。

System.Text.Json の使用

System.Text.Json を使用する場合、System.Text.Json NuGet パッケージ への参照を明示的に追加することに特に注意してください。

依存アセンブリには、使用するすべての外部ライブラリの NuGet パッケージ依存関係を含める必要があります。 設計時にこれらの型を参照できるように、これらの依存関係を含める必要があります。 クラス ライブラリ プロジェクトには、Microsoft.CrmSdk.CoreAssemblies NuGet パッケージ への参照を含める必要があり、それにより、プラグインを作成するために重要なインターフェイスを参照できるようになります。

なぜなら Microsoft.CrmSdk.CoreAssemblies NuGet パッケージには System.Text.Json への依存関係があります、 明示的に System.Text.Json NuGet パッケージを追加せずに、設計時に System.Text.Json タイプを指定します。 しかし System.Text.Json NuGet パッケージは、この間接的な依存関係により、プラグイン パッケージには含まれません。 プラグイン パッケージの第 1 レベルの依存関係として明示的に追加する必要があります。

現在、System.Text.Json は Microsoft.CrmSdk.CoreAssemblies NuGet パッケージの唯一の依存関係です。 このガイダンスは、将来、他の新しい依存関係が追加された場合に当てはまります。

よくあるご質問

Q: 引き続き ILMerge を使用できますか?

A: ILMerge には一切対応していません。 この依存アセンブリ機能は、サポート対象のソリューションによって同じ機能やその他の機能を提供します。 なお、その他の変更はありません。 ILMerge が機能する場合は、引き続き使用できます。 このソリューションはサポート対象であるため、依存アセンブリの使用を推奨します。

既知の問題

以下は、プラグインの依存アセンブリが一般的に利用可能になる前に解決する必要がある既知の問題です。

カスタム API エクスポート キーの変更

プラグイン パッケージを使用するカスタム API を含むソリューションをインポートすると、次のエラーが発生する場合があります。

Lookup value <plugintypeexportkey>{guid value}</plugintypeexportkey> is not resolvable.

このエラーは、2023 年 5 月より前にエクスポート/生成されたソリューションでのみ発生します。 正確な日付は地域によって異なります。 この問題の修正は、2023 年 5 月 26 日に北米地域に展開されました。

この問題を解決するには、プラグイン パッケージを更新し、ソリューションをエクスポート/生成して、再インストールする必要があります。

詳細: プラグイン タイプとの関係を設定する (オプション)

プラグイン プロファイラー

プラグイン パッケージに含まれるプラグインをデバッグする際は、次の手順に従います。

  1. プラグイン登録ツール (PRT) の最新バージョンを使用します。 バージョン 9.1.0.184 以降。

    --update スイッチを持つ Pac CLI pac tool prt コマンドを使用して更新します。

  2. PRT を含むフォルダーで appsettings.json ファイルを編集します。 LegacyPluginProfiler を false に設定します。

    Pac CLI を使用してインストールした場合、フォルダーは次のようになります。

    C:\Users\<you>\AppData\Local\Microsoft\PowerPlatform\PRT\9.1.0.184\tools

詳細情報:

参照

プラグインを使用してビジネス プロセスを拡張する
PAC CLI pac プラグインの初期化

注意

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

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