チュートリアル: プラグインを書き込み登録する

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

このチュートリアルでは、プラグインを作成し、Microsoft Dataverse に登録する方法を説明します。まずプラグインを作成するの記事を読んで、プラグインの作成に慣れてください。

また、このチュートリアルの完全なプラグインソリューションファイルをサンプル: 基本プラグインの作成で見つけることもできます。

ゴール

取引先企業テーブルの "作成" メッセージで登録された非同期プラグインを作成します。プラグインは、取引先企業の作成者に 1 週間後のフォローアップを通知するタスク活動を作成します。

注意

この目標は、コードを記述せずにワークフローを使用して簡単に達成できます。プラグインの作成および展開に集中できるように、この単純な例を使用します。

前提条件

ターゲット Microsoft Dataverse 環境内のシステム管理者またはシステムカスタマイザーの役割を持つシステムユーザーアカウント。
取引先企業およびタスクテーブルを含むモデル駆動型のアプリケーション。
- これらのテーブルを含むモデル駆動型アプリケーションがない場合は、モデル駆動型アプリケーションを最初から作成するを参照して、わずか数分で作成する手順を参照してください。
Visual Studio 2019 (またはそれ以降のバージョン)。
Visual C# プログラミング言語の知識。
開発用コンピューターにインストールされたプラグイン登録ツール。 Dataverse 展開ツールを参照してください。

プラグインプロジェクトの作成

この記事では、Visual Studio を使用してプラグインを作成し、アセンブリを構築する方法を示します。ただし、お気に入りのエディターをコーディングに使用し、MSBuild を使用してアセンブリをビルドすることもできます。いずれの場合も、プラグイン登録ツールを使用してプラグインを Dataverseに登録する必要があります。

または、Power Platform CLI を使って、コマンド pac plugin initを使用して、ボイラープレートプラグインコードを含む新しいプロジェクトをすばやく作成することもできます。プラグイン登録ツールをまだ使用してプラグインを Dataverseに登録する必要があります。

もう 1 つの方法は、ここ Visual Studio を使用してプラグインパッケージを作成および登録するに記載されている Power Platform Tools 拡張機能を使用します。この場合、拡張機能によってプラグインを作成して登録できるため、プラグイン登録ツールは必要ありません。

プラグイン用の Visual Studio プロジェクトを作成する

Visual Studio を開き、.NET Framework 4.6.2を使用する新しいClass Library (.NET Framework 4.6.2) プロジェクトを開いてください

プロジェクトで使用した名前は、アセンブリの名前にもなります。このチュートリアルでは BasicPlugin という名前を使用します。
ソリューションエクスプローラーで、プロジェクトを右クリックしてNuGet パッケージの管理... を選択してくださいを選択します。
参照を選択して、Microsoft.CrmSdk.CoreAssemblies を検索し、最新バージョンをインストールします。
ライセンスの承認 ダイアログで 同意する を選択する必要があります。

注意

Microsoft.CrmSdk.CoreAssemblies NuGet パッケージを追加すると、これらのアセンブリがアセンブリのビルドフォルダーに含まれますが、ロジックを含むアセンブリとともにこれらのアセンブリをアップロードすることはありません。これらのアセンブリは、サンドボックスランタイムにすでに存在します。

プロジェクトのビルドフォルダーに他の NuGet パッケージまたはアセンブリを含めないでください。アセンブリをロジックに登録するときに、これらのアセンブリを含めることはできません。 Microsoft.CrmSdk.CoreAssemblies NuGet パッケージに含まれているもの以外のアセンブリがサーバー上に存在し、コードと互換性があると想定することはできません。
ソリューションエクスプローラーで、Class1.cs ファイルを右クリックし、コンテキストメニューで 名前の変更 を選択します。
Class1.cs ファイルの名前を FollowupPlugin.cs に変更します。
メッセージが表示されたら、Visual Studio はクラスの名前をファイル名と合うように変更することが許可されます。

プラグインを定義するためにクラスファイルを編集する

以下の using ステートメントを FollowupPlugin.cs ファイルの上部に追加します。
```
using System.ServiceModel;  
using Microsoft.Xrm.Sdk;
```
クラスを編集することで、IPlugin インターフェイスを実装します。

注意

クラス名の後 : IPlugin と入力するだけの場合、Visual Studio により実行メソッドのスタブの実装が自動推奨されます。
```
public class FollowupPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        throw new NotImplementedException();
    }
}
```
Execute メソッドの内容を次のコードに置き換えます。

// Obtain the tracing service
ITracingService tracingService =
(ITracingService)serviceProvider.GetService(typeof(ITracingService));

// Obtain the execution context from the service provider.  
IPluginExecutionContext context = (IPluginExecutionContext)
    serviceProvider.GetService(typeof(IPluginExecutionContext));

// The InputParameters collection contains all the data passed in the message request.  
if (context.InputParameters.Contains("Target") &&
    context.InputParameters["Target"] is Entity)
{
    // Obtain the target entity from the input parameters.  
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the IOrganizationService instance which you will need for  
    // web service calls.  
    IOrganizationServiceFactory serviceFactory =
        (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
    IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

    try
    {
        // Plug-in business logic goes here.  
    }

    catch (FaultException<OrganizationServiceFault> ex)
    {
        throw new InvalidPluginExecutionException("An error occurred in FollowUpPlugin.", ex);
    }

    catch (Exception ex)
    {
        tracingService.Trace("FollowUpPlugin: {0}", ex.ToString());
        throw;
    }
}

コードについて

ITracingService により、トレースログへの書き込みが可能になります。最終キャッチブロックで例を確認できます。詳細: トレースの使用
IPluginExecutionContext は、プラグインを実行したイベントのコンテキストへのアクセスを提供します。詳細については、実行コンテキストを理解するを参照してください。
このコードは、コンテキスト InputParameters に、このプラグインが登録される CreateRequest の必要なパラメーターが含まれていることを確認します。 Target プロパティが存在する場合、要求に渡された Entity が使用可能になります。
IOrganizationServiceFactory インターフェイスは、サービスを操作してタスクを作成するために使用するメソッドを提供する IOrganizationService インターフェイスを実装するサービス変数へのアクセスを提供します。

ビジネスロジックの追加

プラグインは、取引先企業の作成者に 1 週間後のフォローアップを通知するタスク活動を作成します。

try ブロックに次のコードを追加します。コメント // Plug-in business logic goes here を次のコードに置き換えます。

// Create a task activity to follow up with the account customer in 7 days. 
Entity followup = new Entity("task");

followup["subject"] = "Send e-mail to the new customer.";
followup["description"] =
    "Follow up with the customer. Check if there are any new issues that need resolution.";
followup["scheduledstart"] = DateTime.Now.AddDays(7);
followup["scheduledend"] = DateTime.Now.AddDays(7);
followup["category"] = context.PrimaryEntityName;

// Refer to the account in the task activity.
if (context.OutputParameters.Contains("id"))
{
    Guid regardingobjectid = new Guid(context.OutputParameters["id"].ToString());
    string regardingobjectidType = "account";

    followup["regardingobjectid"] =
    new EntityReference(regardingobjectidType, regardingobjectid);
}

// Create the task in Microsoft Dynamics CRM.
tracingService.Trace("FollowupPlugin: Creating the task activity.");
service.Create(followup);

コードについて

このコードは、タスクを作成し、作成された取引先企業に関連付けるために、遅延バインドのフォームを使用します。詳細: .NTE 用 SDK を使用したテーブルの作成
事前バインドクラスを使用できますが、その使用にはテーブルのクラスを生成し、アセンブリプロジェクトと共にそれらのクラスを定義するファイルが含まれている必要があります。早期バインドクラスの使用は、大部分は個人用設定であるので、簡略化するため、これらの手順はこのチュートリアルでは除外されています。詳細: .NET 用 SDK を使用した遅延バインドと事前バインドプログラミングのクラス
作成される取引先企業の Id は、コンテキスト OutputParameters にあり、タスクの regardingobjectid 検索列として設定されます。

プラグインの作成

Visual Studio では、アセンブリを構築するために F6 キーを押します。エラーなしでコンパイルされることを確認します。

プラグインにサインする

ソリューションエクスプローラーで、BasicPlugin プロジェクトを右クリックし、コンテキストメニューで プロパティ を選択します。
プロジェクトプロパティで、署名タブを選択し、アセンブリに署名する チェックボックスを選択します。
厳密な名前のキーファイルを選択 ドロップダウンで、<新規…> を選択します。
厳密な名前キーを作成 ダイアログで、キーファイル名を入力し、パスワードでキーファイルを保護する チェックボックスを選択解除します。
OK を選択して 厳密な名前キーの作成 ダイアログを閉じます。
プロジェクトのプロパティの ビルド タブで、構成が デバッグ に設定されていることを確認します。
プラグインを再構築するために F6 を押します。
エクスプローラーを使用して、作成されたプラグインを \bin\Debug\BasicPlugin.dll で検索します。

注意

以降のチュートリアルではプラグインプロファイラーを使用してデバッグするため、デバッグ構成を使用してアセンブリをビルドします。ソリューションと共にプラグインを含めるには、リリース構成を使用してクエリを構築する必要があります。

プラグインの登録

プラグインを登録するには、プラグイン登録ツールが必要です。

プラグイン登録ツールを使用して接続する

プラグイン登録ツールをダウンロードした後、PluginRegistration.exe をクリックして開きます。
新しい接続の作成をクリックして、使用するインスタンスに接続します。
Office 365 が選択されていることを確認します。
現在使用しているアカウント以外の Microsoft アカウントを使用して接続している場合は、詳細の表示をクリックし、クレデンシャルを入力します。それ以外の場合は、現在のユーザーとしてサインインを選択したままにしておきます。
Microsoft アカウントが複数の環境へのアクセスを提供する場合は、利用可能な組織の一覧を表示するを選択します。
ログインをクリックします。
使用可能な組織の一覧を表示するを選択した場合、接続する組織を選択し、ログインをクリックします。
接続すると、既存の登録済みプラグイン、カスタムワークフロー活動、およびデータプロバイダーが表示されます。

アセンブリの登録

登録ドロップダウンリストで 新しいアセンブリ を選択します。
新しいアセンブリの登録 ダイアログで、省略記号 (…) ボタンを選択し、前の手順で作成したアセンブリを参照します。
Microsoft 365 ユーザーの場合、分離モード が サンドボックス に設定され、アセンブリを格納するための場所が データベース であることを確認します。

注意

分離モード および場所のそのほかのオプションは、設置型 Dynamics 365 展開に適用されます。その場所には、D365 サーバーのデータベース、サーバーのローカルストレージ (ディスク)、またはサーバーのグローバルアセンブリキャッシュを指定できます。詳細については、プラグインストレージを参照してください。
選択したプラグインの登録 をクリックします。
登録プラグイン 確認ダイアログが表示されます。
OK を選択してダイアログを閉じ、新しいアセンブリの登録 ダイアログを閉じます。
(アセンブリ) BasicPlugin アセンブリが表示されるようになりました。展開すると、(プラグイン) BasicPlugin.FollowUpPlugin プラグインが表示されます。

新しい手順の登録

(プラグイン) BasicPlugin.FollowUpPlugin を右クリックし、新しいステップの登録 を選択します。
新しい手順の登録 ダイアログで、以下のフィールドを設定します。

設定価値

Message Create

主エンティティアカウント

実行のイベントパイプラインステージ PostOperation

実行モード非同期
新しいステップの登録 を選択して登録を完了し、新しいステップの登録 ダイアログを閉じます。
登録されている手順を表示できます。

設定	価値
Message	Create
主エンティティ	アカウント
実行のイベントパイプラインステージ	PostOperation
実行モード	非同期

注意

この時点で、アセンブリや手順はシステムの既定のソリューションの一部です。運用プラグインを作成するときは、配布するアンマネージドソリューションにプラグインを追加します。これらのステップは、このチュートリアルには含まれていません。詳細については、「アセンブリをソリューションに追加する」および「手順をソリューションに追加する」を参照してください。

プラグインのテスト

モデル駆動型アプリケーションを開き、アカウントテーブルを作成します。
すぐに、取引先企業を開き、タスクの作成を確認します。

タスクが作成されなかった場合はどうなりますか

非同期プラグインを使うため、タスクを作成する操作は、取引先企業が作成された後に行われます。通常、このタスク生成はすぐに行われますが、行われない場合でも、適用されるのを待っているキューでシステムジョブを表示できます。このステップ登録では、ベストプラクティスの Delete AsyncOperation if StatusCode = Successful オプションを使用しました。これは、システムジョブが正常に完了するとすぐに、Delete AsyncOperation if StatusCode = Successful オプションを選択解除してプラグインを再登録しない限り、システムジョブデータを表示できなくなることを意味します。

ただし、エラーが発生した場合、エラーメッセージを表示するためにシステムジョブを表示できます。

システムジョブの表示

Dynamics 365 --カスタム アプリを使用してシステムジョブを表示できます。

モデル駆動型のアプリで、アプリに移動します。
Dynamics 365 --カスタム アプリで、設定 > システム > システムジョブ に移動します。
システムジョブを表示すると、テーブル (エンティティ) でフィルター処理できます。 取引先企業 を選択します。
ジョブが失敗した場合、BasicPlugin.FollowupPlugin: Create of account という名前のレコードが表示されます。
システムジョブを開いた場合、トレースに書き込まれた情報とエラーについての詳細を表示するために詳細セクションを展開できます。

システムジョブの照会

非同期プラグインに対して失敗したシステムジョブを返すには、以下の Web API クエリを使用できます。

GET <your org uri>/api/data/v9.0/asyncoperations?$filter=operationtype eq 1 and statuscode eq 31&$select=name,message

詳細情報: Web APIを使用してデータをクエリする

または、次の FetchXml を使用します。

<fetch top='50' >
  <entity name='asyncoperation' >
    <attribute name='message' />
    <attribute name='name' />
    <filter type='and' >
      <condition attribute='operationtype' operator='eq' value='1' />
      <condition attribute='statuscode' operator='eq' value='31' />
    </filter>
  </entity>
</fetch>

詳細情報: FetchExpressionの使用 FetchXML

トレースログの表示

サンプルコードは、トレースログにメッセージを書きました。これらの次のステップは、ログを表示する方法について説明します。

既定では、プラグイントレースログは無効です。

ヒント

コードでこの設定を変更する場合: この設定は、組織テーブルの PluginTraceLogSetting 列にあります。

有効な値:

値	Label
0	オフに切り替え
1	例外
2	すべて

モデル駆動型アプリケーションで有効にするには、次の手順を実行します。

Dynamics 365 - カスタムアプリを開きます。
設定 > システム > 管理の順に移動します。
管理で システム設定 を選択します。
システム設定 ダイアログの [カスタマイズ] タブで、プラグイントレースログへのログ記録を有効にする を すべて に設定します。

注意

プラグインのテストを終了したらログ記録を無効にする必要があります。または、少なくとも すべて ではなく例外に設定します。
OK を選択して システムの設定 ダイアログを閉じます。
新しい取引先企業を作成することで、プラグインをテストするための手順を繰り返します。
Dynamics 365 -- カスタムアプリケーション で、設定 > カスタマイズ > プラグイントレースログ の順に移動します。
新しいプラグイントレースログレコードが作成されたことがわかります。
レコードを開いた場合、トレースで設定した情報が含まれていることが期待されるかもしれませんが、含まれていません。トレースが発生されたことのみ確認されます。
詳細を表示するには、plugintracelog EntityType と共に以下のクエリを使用し、typename プロパティを使用してプラグインクラスの名前に基づいて messageblock プロパティで結果をフィルター処理し、ブラウザーで Web API を使用してこのデータを照会した方が簡単です。

GET <your org uri>/api/data/v9.0/plugintracelogs?$select=messageblock&$filter=typename eq 'BasicPlugin.FollowUpPlugin'

Web API クエリで返されるこの JSON 形式の情報が表示されることを期待できます。

{
    "@odata.context": "<your org uri>/api/data/v9.0/$metadata#plugintracelogs(messageblock)",
    "value": [{
        "messageblock": "FollowupPlugin: Creating the task activity.",
        "plugintracelogid": "f0c221d1-7f84-4f89-acdb-bbf8f7ce9f6c"
    }]
}

次の手順

このチュートリアルでは、単純なプラグインを作成して登録しました。このプラグインをデバッグする手順について知るには、チュートリアル: プラグインのデバッグを実行します。

参照

チュートリアル: プラグインを更新する
 プラグインを記述する
 プラグインの登録
 プラグインのデバッグ。

注意

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

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

次の方法で共有

チュートリアル: プラグインを書き込み登録する

ゴール

前提条件

プラグインプロジェクトの作成

プラグイン用の Visual Studio プロジェクトを作成する

プラグインを定義するためにクラスファイルを編集する

コードについて

ビジネスロジックの追加

コードについて

プラグインの作成

プラグインにサインする

プラグインの登録

プラグイン登録ツールを使用して接続する

アセンブリの登録

新しい手順の登録

プラグインのテスト

タスクが作成されなかった場合はどうなりますか

システムジョブの表示

システムジョブの照会

トレースログの表示

次の手順

参照

その他のリソース

次の方法で共有

チュートリアル: プラグインを書き込み登録する

ゴール

前提条件

プラグイン プロジェクトの作成

プラグイン用の Visual Studio プロジェクトを作成する

プラグインを定義するためにクラス ファイルを編集する

コードについて

ビジネス ロジックの追加

コードについて

プラグインの作成

プラグインにサインする

プラグインの登録

プラグイン登録ツールを使用して接続する

アセンブリの登録

新しい手順の登録

プラグインのテスト

タスクが作成されなかった場合はどうなりますか

システム ジョブの表示

システム ジョブの照会

トレース ログの表示

次の手順

参照

その他のリソース

プラグインプロジェクトの作成

プラグインを定義するためにクラスファイルを編集する

ビジネスロジックの追加

システムジョブの表示

システムジョブの照会

トレースログの表示