プラグインのデバッグ

  • [アーティクル]

 

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

Microsoft Dynamics 365 (設置型) で実行するプラグインをデバッグする手順を以下に示します。Microsoft Dynamics 365 (オンライン) のサンドボックスで実行するプラグインをデバッグするには、このトピックで後述するトレースを使用する必要があります。

このトピックの内容

Debug a plug-in

隔離されたプラグインのデバッグ

ログおよびトレース

プラグインのデバッグ

  1. プラグイン アセンブリを登録して展開します。

    同じ場所にアセンブリの別のコピーがあり、そのコピーが Microsoft Dynamics 365 によってロックされているため上書きできない場合は、プラグインを実行していたサービス プロセスを再開する必要があります。 適切なサービス プロセスについては、以下の表を参照してください。詳細: プラグインの登録および展開

  2. デバッガーを構成します。

    プラグインを実行する Microsoft Dynamics 365 サーバー上のプロセスにデバッガーを追加します。 プロセスを識別するには、次の表を参照してください。

    プラグイン登録構成

    サービス プロセス

    オンライン

    w3wp.exe

    オフライン

    Microsoft.Crm.Application.Hoster.exe

    非同期の登録プラグイン (またはユーザー定義のワークフロー アセンブリ)

    CrmAsyncService.exe

    サンドボックス (分離モード)

    Microsoft.Crm.Sandbox.WorkerProcess.exe

    同じ実行可能ファイルを実行している複数のプロセス (たとえば、複数の w3wp.exe プロセス) がある場合は、実行中の実行可能プロセスのすべてのインスタンスにデバッガーを追加します。 次に、プラグイン コードに 1 つ以上のブレークポイントを設定します。

  3. プラグインをテストします。

    Microsoft Dynamics 365 アプリケーションまたは SDK を使用する他のカスタム アプリケーションを実行して、プラグインの起動に必要なアクションを実行します。 たとえば、プラグインが取引先企業の作成イベントに登録されている場合は、新しい取引先企業を作成します。

  4. プラグイン コードをデバッグします。

    コードが意図したとおりに実行されるように、必要な変更を加えます。 コードを変更した場合は、そのコードをアセンブリにコンパイルし、必要に応じてこの手順の 1 ～ 4 を繰り返します。 ただし、プラグイン アセンブリのメジャーまたはマイナーのバージョン番号を変更する場合は、アセンブリの以前のバージョンの登録を解除して、新しいバージョンを登録する必要があります。詳細: プラグインの登録および展開

  5. データベースにプラグインを登録します。

    プラグインの編集、コンパイル、展開、テスト、デバッグがひと通り完了したら、ディスク上のプラグイン アセンブリの登録を解除し、次に、Microsoft Dynamics 365 データベースにプラグインを再登録します。詳細: プラグインの登録および展開

ヒント

データベースで展開されたプラグインをデバッグできます。 コンパイル済みのプラグイン アセンブリのシンボル ファイル (.pdb) を、サーバーの <crm-root>\Server\bin\assembly フォルダーにコピーしてから、インターネット インフォメーション サービス (IIS) を再起動する必要があります。 プラグインを実行していたプロセスが余分なメモリを消費してしまうことのないように、デバッグが完了したら、シンボル ファイルを削除し、IIS をリセットしてください。

プラグイン プロファイラー ツールを使用したプラグインのデバッグの詳細については、「プラグインのパフォーマンスを解析する」を参照してください。

隔離されたプラグインのデバッグ

ここで説明する手順は、隔離されたプラグインを最初に実行する前に行うことが重要です。 プラグインが既に実行されている場合は、アセンブリのコードを変更してアセンブリのハッシュがサーバーで変更されるようにするか、サンドボックス サーバーで Microsoft Dynamics 365 サンドボックス処理サービスを再開します。

サーバーの構成

サンドボックス ホスト プロセスでは、プラグインを実行しているサンドボックス ワーカー プロセスを監視します。 また、このプロセスでは、メモリのしきい値を超えた場合などに、プラグインが応答を停止するかどうかを確認します。 30 秒以上応答のないワーカー プロセスはシャットダウンされます。 サンドボックス プラグインをデバッグするには、このシャットダウン機能を無効にする必要があります。 シャットダウン機能を無効にするには、次のレジストリ キーを 1 (DWORD) に設定します。

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSCRM\SandboxDebugPlugins

プラグインのデバッグ

隔離されたプラグインをデバッグするには、次の手順に従います。

  1. サンドボックス (分離モード) でプラグインを登録し、Microsoft Dynamics 365 Server データベースにそのプラグインを展開します。

  2. コンパイル済みのプラグイン アセンブリのシンボル ファイル (.pdb) を、Microsoft.Crm.Sandbox.WorkerProcess.exe というサンドボックス ワーカー プロセスを実行しているサーバーの server\bin\assembly フォルダーにコピーします。 これは、サンドボックス処理サービス ロールをホストしているサーバーです。

  3. このトピックの最初に示した手順 2 ～ 4 の指示に従います。

プラグイン プロファイラー ツールを使用したプラグインのデバッグの詳細については、「プラグインのパフォーマンスを解析する」を参照してください。

ログおよびトレース

プラグインまたはユーザー定義のワークフロー活動 (カスタム コード) をトラブルシューティングする代替の方法は、Microsoft Visual Studio のデバッグと比べると、トレースの使用です。 トレースは、コードの失敗の原因を診断する補助として、実行時のユーザー定義の情報を記録することによって、開発者を支援します。 トレースは、Microsoft Dynamics 365 (オンライン) に登録されているユーザー定義のコードをトラブルシューティングする場合に特に有効であり、このシナリオでサポートされている唯一のトラブルシューティングの方法です。 トレースは、サンドボックスで保護された (部分信頼)、また完全信頼で登録されたユーザー定義コードに対して、同期または非同期の実行時にサポートされます。 トレースは、Outlook 用 Microsoft Dynamics 365 または他のモバイル クライアントで実行されるユーザー定義コードに対してはサポートされません。

Microsoft Dynamics 365 の実行時のトレース情報の記録は、ITracingService という名前のサービスによって提供されます。 ユーザー定義コードによってこのサービスに提供された情報は、次に示す 3 つの異なる場所に記録できます。

  • トレース ログ

    PluginTraceLog の種類のトレース ログ レコードは、[設定] に移動して [プラグイン トレース ログ] タイルを選択することによって、Web アプリケーション内に見つけることができます。 このタイルは、割り当てられたセキュリティ ロールでトレース ログのエンティティ レコードにアクセスできる場合にのみ表示されます。 これらのレコードの作成は、次のセクションで説明されるトレースの設定によって制御されます。PluginTraceLog エンティティに必要な特権の詳細については、エンティティ別の特権を参照してください。

    注意

    トレース ログは、特に多数のトレースと例外が生成されたときは、組織の保存領域を占有します。 トレースログは、デバッグとトラブルシューティングの場合にのみオンにして、調査の完了後はオフにする必要があります。

  • エラー ダイアログ

    例外をプラットフォームに返す、非同期の登録済みのプラグインまたはユーザー定義のワークフロー活動の結果、ログオンしているユーザーに表示される Web アプリケーションに、エラー ダイアログ ボックスが表示されます。 ユーザーは、ダイアログにある [ログ ファイルのダウンロード] ボタンを選択して、例外とトレース出力を格納しているログを表示することができます。

  • システム ジョブ

    例外を返す、非同期の登録済みのプラグインまたはユーザー定義の活動の場合、トレース情報は、Web アプリケーションの**[システム ジョブ]** フォームの [詳細] 領域に表示されます。

トレース ログの有効化

この機能をサポートする組織のトレース ログを有効にするには、Web アプリケーションで、[設定] > [管理] > [システムの設定] に移動します。[カスタマイズ] タブで、[プラグイン トレース ログへのログ記録を有効化] という名前のドロップダウン メニューを見つけて、使用可能なオプションから 1 つを選択します。

オプション

内容

オフ​​

トレース ログへの書き込みは無効です。PluginTraceLog レコードが作成されません。 ただし、ログが書き込まれていない場合でも、ユーザー定義コードはそれでも Trace メソッドを呼び出すことができます。

例外

ユーザー定義コードから例外がプラットフォームに渡されると、トレース情報がログに書き込まれます。

すべて

コードの完了時に、またはユーザー定義コードから例外がプラットフォームに渡されたときに、トレース情報がログに書き込まれます。

トレース ログの設定が [例外] に設定されている場合、ユーザー定義コードが例外をプラットフォームに返したとき、トレース ログのレコードが作成され、トレース情報はもう一つの場所にも書き込まれます。 同期して実行されるユーザー定義コードの場合は、情報はエラー ダイアログ ボックスでユーザーに表示されます。それ以外の、非同期のコードの場合は、情報は関連するシステム ジョブに書き込まれます。

既定では、システム管理者およびシステム カスタマイザのロールには、トレース ログの設定を変更するために必要な特権が備わっています。トレース ログの設定は TraceSettings エンティティ レコードに格納されています。 トレース設定には組織のスコープがあります。

トレース サービスへの書き込み

トレース サービスに書き込む前に、最初に、渡された実行コンテキストからトレース サービス オブジェクトを取得する必要があります。 その後、ユーザー定義コードに、Trace 呼び出しを追加するだけす。このメソッドの呼び出しで関連する診断情報が渡されます。


//Extract the tracing service for use in debugging sandboxed plug-ins.
ITracingService tracingService =
    (ITracingService)serviceProvider.GetService(typeof(ITracingService));

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

// For this sample, execute the plug-in code only while the client is online. 
tracingService.Trace("AdvancedPlugin: Verifying the client is not offline.");
if (context.IsExecutingOffline || context.IsOfflinePlayback)
    return;

// The InputParameters collection contains all the data passed 
// in the message request.
if (context.InputParameters.Contains("Target") &amp;&amp;
    context.InputParameters["Target"] is Entity)
{
    // Obtain the target entity from the Input Parameters.
    tracingService.Trace
        ("AdvancedPlugin: Getting the target entity from Input Parameters.");
    Entity entity = (Entity)context.InputParameters["Target"];

    // Obtain the image entity from the Pre Entity Images.
    tracingService.Trace
        ("AdvancedPlugin: Getting image entity from PreEntityImages.");
    Entity image = (Entity)context.PreEntityImages["Target"];

次に、プラグインまたはユーザー定義ワークフロー活動を作成して展開します。 組織によってサポートされ、有効になっていて、前のセクションで説明したとおりに、Web ダイアログまたはシステム ジョブでユーザーにも利用できるようになっている場合、ユーザー定義コードの実行中に、Trace メソッド呼び出しで提供された情報は、ITracingService によってトレース ログのエンティティ レコードに書き込まれます。 トレース ログに書き込まれるトレース情報は、トレース設定で構成されます。 詳細については、「トレース ログの有効化」を参照してください。

注意

ユーザー定義コードがデータベース トランザクション内で実行され、トランザクションのロールバックを引き起こす例外が発生した場合、コードによるすべてのエンティティ データの変更は取り消されます。 ただし、PluginTraceLog レコードは、ロールバックが完了しても残ります。

トレース サービスについて

ITracingService は提供された情報を Trace メソッドを使用して 1 つにまとめます。 ユーザー定義コードの実行が正常に完了した後、または例外がスローされた後、情報は新しい PluginTraceLog レコードに書き込まれます。

PluginTraceLog レコードには有効期限があります。 一括削除ジョブがバックグラウンドで 1 日に 1 回実行されて、作成から 24 時間経過したレコードを削除します。 このジョブは必要に応じて無効にすることができます。

関連項目

プラグインの開発
プラグインのパフォーマンスを解析する
プラグインの登録および展開
イベント実行パイプライン
プラグインを記述する
プラグイン分離、信頼、および統計
PluginTraceLog エンティティのメッセージとメソッド

Microsoft Dynamics 365

© 2017 Microsoft. All rights reserved. 著作権