次の方法で共有


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

このチュートリアルでは、プラグインを作成し、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 プロジェクトを作成する

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

    .NET Framework 4.6.2 を使用して新しいクラス ライブラリ (.NET Framework) を開く。

    プロジェクトで使用した名前は、アセンブリの名前にもなります。 このチュートリアルでは BasicPlugin という名前を使用します。

  2. ソリューション エクスプローラーで、プロジェクトを右クリックしてNuGet パッケージの管理... を選択してください を選択します。

    NuGet パッケージの管理。

  3. 参照 を選択して、Microsoft.CrmSdk.CoreAssemblies を検索し、最新バージョンをインストールします。

    Microsoft.CrmSdk.CoreAssemblies NuGet パッケージのインストール。

  4. ライセンスの承認 ダイアログで 同意する を選択する必要があります。

    注意

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

    プロジェクトのビルド フォルダーに他の NuGet パッケージまたはアセンブリを含めないでください。 アセンブリをロジックに登録するときに、これらのアセンブリを含めることはできません。 Microsoft.CrmSdk.CoreAssemblies NuGet パッケージに含まれているもの以外のアセンブリがサーバー上に存在し、コードと互換性があると想定することはできません。

  5. ソリューション エクスプローラーで、Class1.cs ファイルを右クリックし、コンテキスト メニューで 名前の変更 を選択します。

    クラスの名前変更。

  6. Class1.cs ファイルの名前を FollowupPlugin.cs に変更します。

  7. メッセージが表示されたら、Visual Studio はクラスの名前をファイル名と合うように変更することが許可されます。

    名前の変更の確認ダイアログ。

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

  1. 以下の using ステートメントを FollowupPlugin.cs ファイルの上部に追加します。

    using System.ServiceModel;  
    using Microsoft.Xrm.Sdk;
    
  2. クラスを編集することで、IPlugin インターフェイスを実装します。

    注意

    クラス名の後 : IPlugin と入力するだけの場合、Visual Studio により 実行メソッドのスタブの実装が自動推奨されます。

    public class FollowupPlugin : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            throw new NotImplementedException();
        }
    }
    
  3. 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 キーを押します。 エラーなしでコンパイルされることを確認します。

プラグインにサインする

  1. ソリューション エクスプローラーで、BasicPlugin プロジェクトを右クリックし、コンテキスト メニューで プロパティ を選択します。

    プロジェクト プロパティを開く。

  2. プロジェクト プロパティで、署名 タブを選択し、アセンブリに署名する チェック ボックスを選択します。

    アセンブリにサインします。

  3. 厳密な名前のキーファイルを選択 ドロップダウンで、<新規…> を選択します。

  4. 厳密な名前キーを作成 ダイアログで、キー ファイル名を入力し、パスワードでキー ファイルを保護する チェック ボックスを選択解除します。

  5. OK を選択して 厳密な名前キーの作成 ダイアログを閉じます。

  6. プロジェクトのプロパティの ビルド タブで、構成デバッグ に設定されていることを確認します。

  7. プラグインを再構築するために F6 を押します。

  8. エクスプローラーを使用して、作成されたプラグインを \bin\Debug\BasicPlugin.dll で検索します。

注意

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

プラグインの登録

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

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

  1. プラグイン登録ツールをダウンロードした後、PluginRegistration.exe をクリックして開きます。

  2. 新しい接続の作成をクリックして、使用するインスタンスに接続します。

  3. Office 365 が選択されていることを確認します。

  4. 現在使用しているアカウント以外の Microsoft アカウントを使用して接続している場合は、詳細の表示をクリックし、クレデンシャルを入力します。 それ以外の場合は、現在のユーザーとしてサインインを選択したままにしておきます。

  5. Microsoft アカウントが複数の環境へのアクセスを提供する場合は、利用可能な組織の一覧を表示するを選択します。

    プラグイン登録ツールを使用してログインします。

  6. ログインをクリックします。

  7. 使用可能な組織の一覧を表示するを選択した場合、接続する組織を選択し、ログインをクリックします。

  8. 接続すると、既存の登録済みプラグイン、カスタム ワークフロー活動、およびデータ プロバイダーが表示されます。

    既存のプラグインとカスタム ワークフロー活動を表示します。

アセンブリの登録

  1. 登録 ドロップダウン リストで 新しいアセンブリ を選択します。

    新しいアセンブリの登録。

  2. 新しいアセンブリの登録 ダイアログで、省略記号 () ボタンを選択し、前の手順で作成したアセンブリを参照します。

    [新しいアセンブリの登録] ダイアログ。

  3. Microsoft 365 ユーザーの場合、分離モードサンドボックス に設定され、アセンブリを格納するための 場所データベース であることを確認します。

    注意

    分離モード および 場所 のそのほかのオプションは、設置型 Dynamics 365 展開に適用されます。 その場所には、D365 サーバーのデータベース、サーバーのローカル ストレージ (ディスク)、またはサーバーのグローバル アセンブリ キャッシュを指定できます。 詳細については、プラグイン ストレージ を参照してください。

  4. 選択したプラグインの登録 をクリックします。

  5. 登録プラグイン 確認ダイアログが表示されます。

    登録済みプラグインの確認ダイアログ。

  6. OK を選択してダイアログを閉じ、新しいアセンブリの登録 ダイアログを閉じます。

  7. (アセンブリ) BasicPlugin アセンブリが表示されるようになりました。展開すると、(プラグイン) BasicPlugin.FollowUpPlugin プラグインが表示されます。

    (プラグん) BasicPlugin.FollowUpPlugin プラグイン。

新しい手順の登録

  1. (プラグイン) BasicPlugin.FollowUpPlugin を右クリックし、新しいステップの登録 を選択します。

    新しい手順の登録。

  2. 新しい手順の登録 ダイアログで、以下のフィールドを設定します。

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

    関連するステップ データの入力。

  3. 新しいステップの登録 を選択して登録を完了し、新しいステップの登録 ダイアログを閉じます。

  4. 登録されている手順を表示できます。

    登録された手順の表示。

注意

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

プラグインのテスト

  1. モデル駆動型アプリケーションを開き、アカウント テーブルを作成します。

  2. すぐに、取引先企業を開き、タスクの作成を確認します。

    プラグインによる関連タスク活動を持つ取引先企業テーブル レコードの作成。

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

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

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

システム ジョブの表示

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

  1. モデル駆動型のアプリで、アプリに移動します。

    dynamics 365 カスタム アプリの表示。

  2. Dynamics 365 --カスタム アプリで、設定 > システム > システム ジョブ に移動します。

    システム ジョブに移動。

  3. システム ジョブを表示すると、テーブル (エンティティ) でフィルター処理できます。 取引先企業 を選択します。

    取引先企業のフィルター。

  4. ジョブが失敗した場合、BasicPlugin.FollowupPlugin: Create of account という名前のレコードが表示されます。

    失敗したシステム ジョブ。

  5. システム ジョブを開いた場合、トレースに書き込まれた情報とエラーについての詳細を表示するために 詳細 セクションを展開できます。

    システム ジョブの詳細。

システム ジョブの照会

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

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

  1. Dynamics 365 - カスタム アプリを開きます。

    Dynamics 365 - カスタム アプリを開きます。

  2. 設定 > システム > 管理 の順に移動します。

    管理に移動。

  3. 管理システム設定 を選択します。

  4. システム設定 ダイアログの [カスタマイズ] タブで、プラグイン トレース ログへのログ記録を有効にするすべて に設定します。

    [システム設定] の [カスタマイズ] タブ。

    注意

    プラグインのテストを終了したらログ記録を無効にする必要があります。または、少なくとも すべて ではなく 例外 に設定します。

  5. OK を選択して システムの設定 ダイアログを閉じます。

  6. 新しい取引先企業を作成することで、プラグインをテストするための手順を繰り返します。

  7. Dynamics 365 -- カスタム アプリケーション で、設定 > カスタマイズ > プラグイン トレース ログ の順に移動します。

  8. 新しいプラグイン トレース ログ レコードが作成されたことがわかります。

    プラグイン トレース ログ レコード。

  9. レコードを開いた場合、トレースで設定した情報が含まれていることが期待されるかもしれませんが、含まれていません。 トレースが発生されたことのみ確認されます。

  10. 詳細を表示するには、plugintracelog EntityType と共に以下のクエリを使用し、typename プロパティを使用してプラグイン クラスの名前に基づいて messageblock プロパティで結果をフィルター処理し、ブラウザーで Web API を使用してこのデータを照会した方が簡単です。

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

  11. 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 分かかります。 個人データは収集されません (プライバシー ステートメント)。