プラグインのコードのビルドとパッケージ化

  • [アーティクル]

この記事では、Microsoft Dataverse プラグイン用のアセンブリを構成および構築する際に知っておく必要がある制約と制限について説明します。

プラグイン アセンブリの制約

プラグイン プロジェクトをビルドする際は、次の出力アセンブリ制約に留意してください。

.NET Framework 4.6.2 の使用

プラグインおよびカスタム ワークフロー活動アセンブリ プロジェクトは、.NET Framework 4.6.2 をターゲットにする必要があります。 .NET Framework の新しいバージョンを使用して構築されたアセンブリは、通常は動作するはずです。 しかし、プラグインコードが 4.6.2 以降に導入された機能を使用している場合、ランタイムエラーが発生します。

アセンブリを 16 MB に制限する

アセンブリには複数のプラグイン クラスやタイプ、カスタム ワークフロー アクティビティを含めることができますが、16MB を超えることはできません。 ベスト プラクティスとして、サイズが 16 MB 未満である限り、プラグインとワークフロー アセンブリをひとつのアセンブリに統合することをお勧めします。

登録する前にアセンブリに署名する

依存アセンブリ機能を使用していない場合、アセンブリは Dataverse に登録する前に署名する必要があります。 アセンブリに署名するには、プロジェクトのプロパティにある Visual Studio Signing タブ、または Sn.exe (厳密な名前ツール) コマンドを使用します

NuGet CoreAssemblies はサンドボックス内にあります

Microsoft.CrmSdk.CoreAssemblies NuGet パッケージをプロジェクトに追加すると、必要な Dataverse アセンブリ参照も追加されますが、アセンブリ自体はプラグイン アセンブリと一緒にアップロードされません。 これらは、コードが実行されるサーバーのサンドボックス ランタイムに既に存在します

依存アセンブリ

重要

依存アセンブリ機能は、プラグイン開発にとって非常に重要であるため、すぐに必要でなくても、最初から使用を検討する必要があります。 開発サイクルの後半では、プラグイン プロジェクトに依存アセンブリのサポートを追加することがはるかに困難になります。

ILMerge はサポートされていません。 依存アセンブリ機能は、ILMerge と同等の機能とそれ以上の機能を提供します。

依存アセンブリ機能を使用すると、登録時にDataverse サーバーにアップロードされる単一の NuGet パッケージに、ローカライズされた文字列などの他の必要な .NET アセンブリやリソースをプラグインアセンブリに含めることができます。

NuGet パッケージ ファイルは PluginPackage テーブルに格納されています。 パッケージの内容は、SQL データベースではなくファイル ストレージに保存されます。

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

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

重要

プラグイン パッケージの名前とバージョンは、作成後に変更することはできません。 API 呼び出しを使用して実行しようとすると、エラーが発生します。

署名付きアセンブリの必要はない

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

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

重要

アセンブリに署名する場合、署名されたアセンブリは署名されていないアセンブリに含まれるリソースを使用できないことに注意してください。 プラグイン アセンブリまたは依存アセンブリに署名する場合は、それらのアセンブリが依存するすべてのアセンブリに署名する必要があります。

署名付きアセンブリが署名なしアセンブリに依存している場合、次のようなエラーが発生します: 「ファイルまたはアセンブリ AssemblyName, Version=Version, Culture=neutral, PublicKeyToken=null、またはその依存関係の 1 つをロードできませんでした。 厳密な名前のアセンブリが必要です。」

依存アセンブリの制限事項

プラグイン依存アセンブリを使用する場合、次の制限が適用されます:

  • ワークフロー拡張機能 (カスタム ワークフロー アクティビティ とも呼ばれます) はサポートされていません。
  • オンプレミスの 環境はサポートされていません。
  • アンマネージド コードはサポートされていません。 アンマネージド リソースへの参照を含めることはできません。

プラグイン パッケージをインポートまたは登録する際のパフォーマンスに関する考慮事項

IPlugin を実装する多数 (数百から数千) のクラスを持つアセンブリを含むプラグイン パッケージは、Dataverse へのインポートに比較的長い時間がかかります。

1,000 種類のプラグインのインポートに 15 分かかることが確認されています。 この期間は、API 呼び出しまたは Web UI を使用してソリューションをインポートする場合、またはプラグイン登録ツールを使用してパッケージを登録する場合に関係なく適用されます。

プラグイン パッケージの作成

プラグイン アセンブリと依存するアセンブリを NuGet パッケージにまとめて配置し、Dataverse サーバーにパッケージを登録してアップロードします。 プラグイン プロジェクトが Microsoft.CrmSdk.CoreAssemblies NuGet パッケージに同梱されているもの以外に実行時に依存するアセンブリを必要としない場合は、パッケージを作成する必要はありません。

PAC CLI を使用してプラグイン パッケージを作成、登録する方法と、Visual Studio を使用してプラグイン パッケージを作成・登録する方法をご紹介します。

すべてのプロジェクトは SDK スタイルである必要があります

プラグイン パッケージには、SDKスタイル と呼ばれる特定の形式のプロジェクト ファイルからビルドされたカスタム アセンブリのみを含める必要があります。 このルールに従わない場合、プラグイン登録ツールを使用してパッケージを登録しようとすると、エラー (「ファイルが見つかりません」) が発生します。

重要

結果としてコンパイルされたアセンブリがプラグイン パッケージに追加されるすべての MSBuild プロジェクトは、「SDK スタイル」形式である必要があります。

SDKスタイルのプロジェクトとは、プロジェクトの .csproj ファイルの内容が次のコード行を含むものです: <Project Sdk="Microsoft.NET.Sdk">。

当社のツールのいずれかを使用してプラグイン プロジェクトを作成する場合、たとえば Power Platform CLI pac plugin init コマンドを実行すると、プラグイン プロジェクト ファイルは正しい形式になります。 このようなプロジェクトファイルの例を示します。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net462</TargetFramework>
    <PowerAppsTargetsPath>$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\PowerApps</PowerAppsTargetsPath>
    <AssemblyVersion>1.0.0.0</AssemblyVersion>
    <FileVersion>1.0.0.0</FileVersion>
    <ProjectTypeGuids>{4C25E9B5-9FA6-436c-8E19-B395D2A65FAF};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>
  </PropertyGroup>
  ...
</Project>

別のプロジェクトを Visual Studio ソリューション、たとえばクラス ライブラリ プロジェクトの場合は、次の手順に従って SDK スタイルのプロジェクトを作成できます。

  1. Visual Studio で 、.NET または .NET Standard テンプレートを使用して、新しいプロジェクトをソリューションに追加します。 .NET Framework をターゲットにしないでください。
  2. ソリューション エクスプローラーでプロジェクト名を右クリックし、プロジェクト ファイルの編集 を選択するか、別のエディターでプロジェクトの .csproj ファイルを開いてプロジェクトファイルを編集します。
  3. プロジェクト ファイルに <Project Sdk="Microsoft.NET.Sdk"> という行があるはずです。 TargetFramework プロパティを <TargetFramework>net462</TargetFramework> に変更し、ファイルを保存します。
  4. ソリューションのビルドを確認したら完了です。

詳細情報: .NET プロジェクト SDK

System.Text.Json に依存しない

Microsoft.CrmSdk.CoreAssemblies NuGet パッケージには 依存関係 があるため System.Text.Json、設計時に System.Text.Json 型を参照できます。 しかし、サンドボックスのランタイムにある System.Text.Json.dll ファイルは、プロジェクトで参照しているバージョンと同じではない可能性があります。 System.Text.Json を使用する必要がある場合は、依存アセンブリ機能を使用し、NuGet パッケージに明示的に含める必要があります。

次のステップ

参照

注意

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

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