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

[アーティクル]
07/07/2022

注意

エンティティとテーブルの違いがわかりませんか？ Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。

このチュートリアルは、プラグインの使用方法を説明するシリーズの最初のチュートリアルです。このチュートリアルは、以下のチュートリアルの前提条件です。

関連する概念と技術的詳細については、以下を参照してください。

目標

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

注意

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

前提条件

Microsoft Dataverse 環境への管理者レベルのアクセス
取引先企業およびタスクテーブルを含むモデル駆動型のアプリケーション。
- これらを含むモデル駆動型アプリケーションがない場合は、モデル駆動型アプリケーションを最初から作成するを参照して、わずか数分で作成する手順を参照してください。
Visual Studio 2017 (またはそれ以降のバージョン)
Visual C# プログラミング言語の知識
プラグイン登録ツールをダウンロードします。
- プラグイン登録ツールのダウンロードについての詳細については、NuGet からツールをダウンロードを参照してください。そのトピックには、PowerShell スクリプト使用の手引きが含まれており、NuGet から最新ツールをダウンロードできます。

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

プラグインを書き込むには Visual Studio を使用する必要があります。基本的なプラグインを作成する手順に従います。または、Power Platform CLI を使用して、pac plugin init コマンドを使用する新しいプロジェクトを作成できます。

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

プラグイン用の 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 organization service reference 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);

コードについて

このコードは、タスクを作成し、作成された取引先企業に関連付けるために、遅延バインドのフォームを使用します。詳細: 組織サービスを使用したテーブルの作成
事前バインドクラスを使用できますが、テーブルのクラスを生成し、アセンブリプロジェクトと共にそれらのクラスを定義するファイルが含まれている必要があります。これは、大部分は個人用設定であるので、簡略化するため、これらの手順はこのチュートリアルでは除外されています。詳細: 組織サービスを使用した遅延バインドと事前バインドプログラミングのクラス
作成される取引先企業の 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 を右クリックし、新しいステップの登録 を選択します。
新しい手順の登録 ダイアログで、以下のフィールドを設定します。

設定 Value

メッセージ作成

主エンティティ取引先企業

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

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

設定	Value
メッセージ	作成
主エンティティ	取引先企業
実行のイベントパイプラインステージ	PostOperation
実行モード	非同期

注意

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

プラグインのテスト

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

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

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

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

システムジョブの表示

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

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

システムジョブの照会

非同期プラグインに対して失敗したシステムジョブを返すには、以下の 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>

詳細: FetchXML と FetchExpression の使用

トレースログの表示

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

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

ヒント

コードでこの設定を変更する場合: この設定は、組織テーブルの 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 クエリで返される以下の内容が表示されることを期待できます。

{
    "@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 プロジェクトを作成する

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

コードについて

ビジネス ロジックの追加

コードについて

プラグインの作成

プラグインにサインする

プラグインの登録

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

アセンブリの登録

新しい手順の登録

プラグインのテスト

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

システム ジョブの表示

システム ジョブの照会

トレース ログの表示

次のステップ

フィードバック

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

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

ビジネスロジックの追加

システムジョブの表示

システムジョブの照会

トレースログの表示