0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@shingargle

Dataverse プラグイン開発環境の構築メモ（Visual Studio 2022／.NET 4.6.2 固定／2025年版）

0
Posted at

はじめに

Power Apps / Dataverse でビジネスロジックをサーバーサイドで実装したい場合、C# で書く プラグイン（Plugin） が定番です。
本記事では、次の 2 点にしぼって手順をまとめます。

  • Windows での プラグイン開発環境の構築方法
  • 構築した環境で サンプル プラグインを作って動作確認する方法

✅ 重要な前提：プラグインは .NET Framework 4.6.2 ターゲット必須
現行の公式ドキュメントでは「プラグインは .NET Framework 4.6.2 をターゲットにする」と明記されています。
本記事も ターゲット フレームワークは 4.6.2 で固定 して進めます（4.8 等は将来の対応予定という位置づけ）。

「とりあえず DLL をビルドして、Dataverse 環境に 1 本プラグインを登録できるようになる」ことをゴールにしています。

前提

  • OS: Windows 10 / 11（64bit）
  • 役割: Dataverse / Dynamics 365 Online のカスタマイズを行う開発者
  • Dataverse 環境（サンドボックス環境推奨）を 1 つ以上保有
  • C# / .NET Framework の基本構文をなんとなく読める
  • 管理者権限でソフトウェアをインストールできる
  • ターゲット フレームワークは .NET Framework 4.6.2 を使用する前提

※ ここでは、オンライン Dataverse 向けの 従来型 .NET Framework プラグイン（4.6.2） を想定しています。
.NET 6 以降の Isolated プラグインなどは一旦スコープ外です。

1. 必要なツール一式

プラグイン開発に最低限必要なのは、次の 3 つです。

  1. Visual Studio 2022（Community 版で OK）
  2. .NET Framework 4.6.2 Developer Pack（必須）
  3. Plugin Registration Tool（プラグイン登録ツール）

1-1. Visual Studio 2022 のインストール

  1. 「Visual Studio Community 2022」で検索し、公式サイトからインストーラをダウンロード
  2. インストーラ起動後、ワークロード選択画面で 「.NET デスクトップ開発」 にチェック
  3. そのままインストールを完了

インストール完了後、Visual Studio を起動しておきます。

1-2. .NET Framework 4.6.2 Developer Pack の導入確認（必須）

プラグインのターゲット フレームワークとして、4.6.2 が必須 です。

  1. Visual Studio で適当な C# プロジェクトを作成
  2. プロジェクトを右クリック → 「プロパティ」 → 「アプリケーション」タブの ターゲット フレームワーク を確認
  3. プルダウンに 「.NET Framework 4.6.2」 が存在し、選択できることを確認

もし 4.6.2 が選択肢にない場合は：

  1. 「.NET Framework 4.6.2 Developer Pack」で検索し、Microsoft 公式サイトからダウンロード
  2. インストール後、Visual Studio を再起動
  3. 再度プロジェクトの ターゲット フレームワーク を開き、4.6.2 を選べることを確認

⚠️ 誤登録を防ぐためのポイント

  • ターゲット 4.8 のままプラグインを作ってしまう ケースが非常に多いです。
  • チーム運用時は「プラグイン プロジェクトは 4.6.2 以外は禁止」とルール化しておくと安全です。

1-3. Plugin Registration Tool の入手

Dataverse にプラグイン DLL を登録するために Plugin Registration Tool（PRT） を使用します。入手方法はいくつかありますが、ここでは 2 パターンを紹介します。

パターン A: Power Platform Tools（Visual Studio 拡張・推奨）

Visual Studio 用の拡張機能 Power Platform Tools をインストールする方法です。

  1. Visual Studio のメニューから
    [拡張機能] → [拡張機能の管理] を開く
  2. 「オンライン」タブで Power Platform Tools を検索
  3. 見つかったらインストールし、Visual Studio を再起動

再起動後：

  • [表示] → [その他のウィンドウ] → [Power Platform Explorer] から Dataverse に接続
  • プラグイン プロジェクトを右クリックして 「パッケージ デプロイ（Deploy）」 まで完結させることが可能です（いわゆる プラグイン パッケージ／依存アセンブリ方式）。

チーム標準化を狙うなら、

  • Visual Studio + Power Platform Tools
  • NuGet で依存アセンブリを管理し、ソリューションから右クリック Deploy
    というパターンを推奨します。

パターン B: 単体ツールとして利用（従来の PRT）

昔ながらの Plugin Registration Tool（exe）を使う場合は、

  • Microsoft.CrmSdk.XrmTooling.PluginRegistrationTool NuGet パッケージをダウンロードして展開
  • もしくは、XrmToolBox のプラグインとしてインストール

などの方法があります。
この記事の「動作確認」の章では、わかりやすさ重視で従来の PRT 画面を前提に書いています。

2. SDK アセンブリを NuGet で参照に追加

C# プラグインでは IPlugin インターフェイスなどを使うため、Dataverse SDK のアセンブリを参照する必要があります。
最も簡単なのは NuGet を使う方法です。

  1. Visual Studio でプラグイン用ソリューションを開く
  2. プロジェクトを右クリック → 「NuGet パッケージの管理」
  3. 「参照」タブで Microsoft.CrmSdk.CoreAssemblies を検索
  4. 最新の安定版をインストール

これで Microsoft.Xrm.Sdk.dll などが参照に追加されます。

3. サンプル プラグイン プロジェクトの作成（環境確認用）

ここから、環境確認を兼ねて 最小限のプラグインを 1 本作ってみる 手順です。

3-1. Class Library プロジェクトの作成（4.6.2 固定）

  1. Visual Studio を起動
  2. [新しいプロジェクトの作成] を選択
  3. プロジェクト テンプレートから 「クラス ライブラリ (.NET Framework)」 を選択
  4. プロジェクト名: SampleDataversePlugin など
  5. ターゲット フレームワーク: .NET Framework 4.6.2 を選択（必須）

ここで誤って 4.8 などを選ぶと、あとでターゲット変更し忘れたまま DLL をデプロイしてしまう事故が起きがちです。
新規プロジェクトの作成時に 必ず 4.6.2 を選び直す のを習慣化すると安全です。

3-2. SDK 参照の追加

先ほどの手順（2章）と同様に、このプロジェクトに

  • Microsoft.CrmSdk.CoreAssemblies

の NuGet パッケージをインストールします。

3-3. サンプル プラグイン クラスを実装

Class1.cs を削除し、代わりに SamplePlugin.cs というクラスを追加して、以下のようなコードを書きます。

using System;
using Microsoft.Xrm.Sdk;

namespace SampleDataversePlugin
{
    public class SamplePlugin : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            // トレース出力用サービス
            var tracingService =
                (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            // 実行コンテキスト
            var context =
                (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

            tracingService.Trace("SamplePlugin Execute start.");

            // 例: 取引先企業（account）の作成時だけ何かする
            if (context.PrimaryEntityName != "account" || context.MessageName != "Create")
            {
                tracingService.Trace("Not account Create. Exit.");
                return;
            }

            var factory =
                (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
            var service = factory.CreateOrganizationService(context.UserId);

            // Target エンティティ取得
            if (!(context.InputParameters["Target"] is Entity entity))
            {
                tracingService.Trace("Target is not Entity. Exit.");
                return;
            }

            // メモ欄 (description) に「プラグイン実行済み」と追記
            var desc = entity.GetAttributeValue<string>("description") ?? string.Empty;
            entity["description"] = desc + "（SamplePlugin で更新）";

            tracingService.Trace("SamplePlugin Execute end.");
        }
    }
}

ポイント:

  • IPlugin インターフェイスを実装する
  • PrimaryEntityName と MessageName で、対象エンティティとメッセージを絞る
  • ITracingService.Trace() を使って、トレースログにメッセージを書いておくと、後述の プラグイン トレースログ から原因調査がしやすくなります
  • サンプルなので、account 作成時に description フィールドを書き換えるだけ の簡単な処理にしています

3-4. ビルドして DLL を作る

Visual Studio で

  • メニュー [ビルド] → [ソリューションのビルド]

を実行し、ビルドが成功することを確認します。
成功すると、bin\Debug または bin\Release フォルダに SampleDataversePlugin.dll が生成されます。

ここまで通れば、開発環境としてはほぼ完成 です。

4. Dataverse に登録して動作確認する

次に、先ほどビルドした DLL を Dataverse 環境に登録し、実際に動くかどうかを見てみます。
ここでは Plugin Registration Tool を使う手順の一例を示します。

4-1. Plugin Registration Tool で環境に接続

  1. Plugin Registration Tool（PRT）を起動
  2. 「Create new Connection」から、組織の URL（例: https://orgxxxxx.crm7.dynamics.com）を入力
  3. 「OAuth」または「Interactive」など、環境に応じた認証方法を選択
  4. サインインして組織に接続

接続に成功すると、既存のアセンブリ／プラグイン／ステップの一覧が表示されます。

4-2. アセンブリを登録

  1. 画面上部の 「Register」 → 「Register New Assembly」 を選択
  2. 先ほどビルドした SampleDataversePlugin.dll を指定
  3. 「Isolation Mode」は Sandbox、Location は Database を選択
  4. 「Register Selected Plugins」にチェックを入れ、登録を完了

これで、アセンブリと SamplePlugin クラスが Dataverse 上に登録されます。

4-3. ステップの登録

  1. 登録した SampleDataversePlugin アセンブリを展開し、SamplePlugin を右クリック

  2. 「Register New Step」 を選択

  3. 以下のように設定

    • Message: Create
    • Primary Entity: account
    • Stage: Pre-Operation
    • Execution Mode: Synchronous

  4. 「Register New Step」で完了

これで、「取引先企業（account）のレコードが作成されるタイミング」で SamplePlugin が実行されるようになります。

4-4. 実際にレコードを作成して動作確認

  1. Power Apps ポータル（make.powerapps.com）から対象のモデル駆動型アプリを開く
  2. account テーブル（取引先企業）の新規レコードを作成
  3. 任意の名前・情報を入力し保存
  4. 保存後、そのレコードの メモ欄（description） を確認

description に （SamplePlugin で更新） という文字列が追加されていれば、プラグインが正しく動いていることが確認できます。

補足: 場合によってはフォームのカスタマイズ状況により description フィールドが表示されていないことがあります。
その場合はフォームに追加するか、別のフィールドを更新するサンプルに変更してください。

5. よくあるハマりポイント

5-1. ビルドは通るが登録時にエラーになる

  • ターゲット フレームワークが 4.6.2 以外 になっていないか確認
  • プロジェクトの「プラットフォーム ターゲット」が Any CPU になっているか確認
  • 参照している Microsoft.Xrm.Sdk のバージョンが古すぎないか／新しすぎないか確認

5-2. プラグインが実行されない

  • Plugin Registration Tool で、正しいメッセージ／エンティティ／ステージ にステップが登録されているか確認
  • 同じアセンブリを複数バージョン登録している場合、どのアセンブリに紐づいているステップかを確認
  • 必要に応じて、Dataverse 側で「プラグイン トレース ログ」のレベルを Exception または All にして原因を調査

5-3. コードの変更が反映されない

  • DLL を修正後、必ずビルドし直してから「Update Assembly」 を行う
  • 別フォルダに出力した DLL を古いまま参照していないか確認

6. トレースログを使ったデバッグ（Plugin Trace Log）

プラグインのデバッグで最も頼りになるのが プラグイン トレースログ です。
本記事のサンプルでも tracingService.Trace(...) を埋め込んでいます。

6-1. トレースログの有効化

有効化の方法は大きく 2 通りあります。

  1. 環境設定から有効化

    • Power Platform 管理センターや「設定」から、プラグイン トレース ログ レベルを Exception または All に設定

  2. Plugin Registration Tool（PRT）から有効化

    • PRT のメニュー [Settings] で「Log to Plug-in Trace Log」系の設定を有効にする

どちらの方法でも、ITracingService.Trace() による出力が PluginTraceLog テーブル に残るようになります。

6-2. ログの確認方法

  1. make.powerapps.com で Dataverse テーブルの一覧から Plugin Trace Logs（または類似名称）を開く
  2. 直近でエラーになったプラグイン実行のレコードを開く
  3. メッセージ欄に SamplePlugin Execute start. / end. などのトレースメッセージや例外の詳細が出力されます

「プラグインが動いているか分からない」「どこで落ちているか不明」というときは、

  • コードに tracingService.Trace("ここまでは通っている") を細かく入れる
  • Plugin Trace Log で確認する

というのが一番確実でおすすめです。

7. Sandbox 実行の制約と設計のヒント

オンライン Dataverse のプラグインは Sandbox で実行されます。Sandbox にはいくつか制約があるため、あまり重い処理や外部アクセスをさせない設計が重要です。

代表的なポイント：

  • ローカル ファイル システムやレジストリなどにはアクセスできない
  • 実行時間に制限がある（長時間処理はタイムアウトする）
  • 外部 HTTP 呼び出しも、タイムアウトやネットワーク制約の影響を受けやすい

そのため、次のような設計パターンをおすすめします。

  • プラグインでは「トリガー」と最小限の検証・更新のみにとどめる
  • 重い処理や外部システム連携は
    • Azure Functions
    • Azure Web Apps / Web API
    • Power Automate など
      に委譲する（キューやテーブルのフラグをトリガーにする）

「何でもプラグインでやる」のではなく、Sandbox 前提の軽量ロジック にとどめるのが、クラウド時代のベストプラクティスです。

8. おわりに（CLI 派への一言も）

本記事では、

  • Visual Studio 2022 と .NET Framework 4.6.2 固定 のプラグイン開発環境の構築
  • NuGet による Dataverse SDK アセンブリ参照の追加
  • 最小限の C# プラグインの実装
  • Plugin Registration Tool を使った登録と動作確認
  • トレースログと Sandbox 制約に関する注意点

までを、一気に駆け足でまとめました。

チーム内で「プラグインを触れる人」を増やすときは、この記事をたたき台にして、

  • 組織ごとの推奨 .NET バージョン（本記事では 4.6.2 固定）
  • 使用する Dataverse 環境名
  • Plugin Registration Tool の入手方法（Visual Studio の Power Platform Tools を標準にするか、従来の PRT を使うか）

などを追記してもらうと、スムーズに環境をそろえられると思います。

おまけ：CLI 派／VS Code 派の方へ

Visual Studio を使わず、VS Code + Power Platform CLI で進めたい方は、

  • pac plugin init でプラグイン プロジェクトを作成
  • pac tool prt で Plugin Registration Tool を起動

といった形で、ほぼ同等のことができます。
「編集は VS Code、ビルドと登録は CLI + PRT」で統一したいチームでも、基本的な考え方は本記事と変わりません。

「とりあえず 4.6.2 でビルドできて、Plugin Trace Log が読めれば一人前」ぐらいの気持ちで、まずは 1 本目のプラグインを動かしてみてください。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?