ASP.NET Web API 2 でのトレース

Web ベースのアプリケーションをデバッグしようとするなら、適切なトレース ログのセットに代わるものはありません。 このチュートリアルでは、ASP.NET Web API でトレースを有効にする方法を示します。 この機能を使用して、Web API フレームワークがコントローラーを呼び出す前後に実行している内容をトレースできます。 これを使用して、独自のコードをトレースすることもできます。

チュートリアルで使用するソフトウェアのバージョン

• Visual Studio 2017 (Visual Studio 2015 でも可)
• Web API 2
• Microsoft.AspNet.WebApi.Tracing

Web API で System.Diagnostics トレースを有効にする

まず、新しい ASP.NET Web アプリケーション プロジェクトを作成します。 Visual Studio の [ファイル] メニューから､[新規]>[プロジェクト] を選択します。 [テンプレート] の [Web] で、[ASP.NET Web アプリケーション] を選択します。

Web API プロジェクト テンプレートを選択します。

[ツール] メニューで、[NuGet パッケージ マネージャー]、[パッケージ マネージャー コンソール] の順に選択します。

[パッケージ マネージャー コンソール] ウィンドウで、次のコマンドを入力します。

Install-Package Microsoft.AspNet.WebApi.Tracing
Update-Package Microsoft.AspNet.WebApi.WebHost

最初のコマンドは、最新の Web API トレース パッケージをインストールします。 また、コア Web API パッケージも更新します。 2 番目のコマンドは、WebApi.WebHost パッケージを最新バージョンに更新します。

Note

特定のバージョンの Web API を対象にする場合は、トレース パッケージをインストールするときに -Version フラグを使用します。

App_Start フォルダー内のファイル WebApiConfig.cs を開きます。 Register メソッドに次のコードを追加します。

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // New code
        config.EnableSystemDiagnosticsTracing();

        // Other configuration code not shown.
    }
}

このコードは、SystemDiagnosticsTraceWriter クラスを Web API パイプラインに追加します。 SystemDiagnosticsTraceWriter クラスは、トレースを System.Diagnostics.Trace に書き込みます。

トレースを表示するには、デバッガーでアプリケーションを実行します。 ブラウザーで /api/values にアクセスします。

トレース ステートメントは、Visual Studio の [出力] ウィンドウに書き込まれます。 ([表示] メニューから [出力] を選択します)。

SystemDiagnosticsTraceWriter はトレースを System.Diagnostics.Trace に書き込むため、追加のトレース リスナーを登録して、たとえば、ログ ファイルにトレースを書き込んだりすることができます。 トレース ライターの詳細については、MSDN の「トレース リスナー」を参照してください。

SystemDiagnosticsTraceWriter の構成

次のコードはトレース ライターを構成する方法を示しています。

SystemDiagnosticsTraceWriter traceWriter = config.EnableSystemDiagnosticsTracing();
traceWriter.IsVerbose = true;
traceWriter.MinimumLevel = TraceLevel.Debug;

制御できる設定は 2 つあります。

• IsVerbose: false の場合、各トレースには最小限の情報が含まれます。 true の場合、トレースには詳細情報が含まれます。
• MinimumLevel: 最小トレース レベルを設定します。 トレース レベルは、デバッグ、情報、警告、エラー、致命的の順です。

Web API アプリケーションへのトレースの追加

トレース ライターを追加すると、Web API パイプラインによって作成されたトレースにすぐにアクセスできます。 トレース ライターを使用して、独自のコードをトレースすることもできます。

using System.Web.Http.Tracing;

public class ProductsController : ApiController
{
    public HttpResponseMessage GetAllProducts()
    {
        Configuration.Services.GetTraceWriter().Info(
            Request, "ProductsController", "Get the list of products.");

        // ...
    }
}

トレース ライターを取得するには、HttpConfiguration.Services.GetTraceWriter を呼び出します。 このメソッドには、コントローラーから ApiController.Configuration プロパティ経由でアクセスできます。

トレースを書き込むには、ITraceWriter.Trace メソッドを直接呼び出すこともできますが、ITraceWriterExtensions クラスは、よりわかりやすい拡張メソッドをいくつか定義します。 たとえば、上記の Info メソッドは、トレース レベル [Info] のトレースを作成します。

Web API トレース インフラストラクチャ

このセクションでは、Web API 用のカスタム トレース ライターを書き込む方法について説明します。

Microsoft.AspNet.WebApi.Tracing パッケージは、Web API のより一般的なトレース インフラストラクチャの上に構築されています。 Microsoft.AspNet.WebApi.Tracing を使用する代わりに、NLog や log4net などの他のトレース/ログ ライブラリをプラグインすることもできます。

トレースを収集するには、ITraceWriter インターフェイスを実装します。 次に、簡単な例を示します。

public class SimpleTracer : ITraceWriter
{
    public void Trace(HttpRequestMessage request, string category, TraceLevel level, 
        Action<TraceRecord> traceAction)
    {
        TraceRecord rec = new TraceRecord(request, category, level);
        traceAction(rec);
        WriteTrace(rec);
    }

    protected void WriteTrace(TraceRecord rec)
    {
        var message = string.Format("{0};{1};{2}", 
            rec.Operator, rec.Operation, rec.Message);
        System.Diagnostics.Trace.WriteLine(message, rec.Category);
    }
}

ITraceWriter.Trace メソッドはトレースを作成します。 呼び出し元は、カテゴリとトレース レベルを指定します。 カテゴリは、任意のユーザー定義文字列にすることができます。 Trace の実装では、次の操作を行う必要があります。

1. 新規 TraceRecord を作成します。 次に示すように、それを、要求、カテゴリ、トレース レベルで初期化します。 これらの値は、呼び出し元によって指定されます。
2. traceAction デリゲートを呼び出します。 このデリゲート内では、呼び出し元は TraceRecord の残りの部分を埋める必要があります。
3. 任意のログ記録手法を使用して、TraceRecord を書き込みます。 ここで示す例では、ただ System.Diagnostics.Trace を呼び出しています。

トレース ライターの設定

トレースを有効にするには、ITraceWriter 実装を使用するように Web API を構成する必要があります。 これを行うには、次のコードに示すように HttpConfiguration オブジェクトを使用します。

public static void Register(HttpConfiguration config)
{
    config.Services.Replace(typeof(ITraceWriter), new SimpleTracer());
}

アクティブにできるトレース ライターは 1 つだけです。 既定では、Web API は何も行わない "no-op" トレーサーを設定します。 ("no-op" トレーサーが存在するのは、トレースを書き込む前にトレース ライターが null であるかどうかをトレース コードがチェックする必要がないようにするためです。)

Web API トレースのしくみ

Web API でのトレースでは "ファサード" パターンが使用されます: トレースが有効になっている場合、Web API は要求パイプラインのさまざまな部分を、トレース呼び出しを実行するクラスでラップします。

たとえば、コントローラーを選択すると、パイプラインは IHttpControllerSelector インターフェイスを使用します。 トレースが有効な場合、パイプラインは IHttpControllerSelector を実装するクラスを挿入しますが、実際の実装を呼び出します。

この設計の利点は次のとおりです。

• トレース ライターを追加しない場合、トレース コンポーネントはインスタンス化されず、パフォーマンスに影響しません。
• IHttpControllerSelector などの既定のサービスを独自のカスタム実装に置き換えた場合、トレースは影響を受けません。トレースはラッパー オブジェクトによって実行されるためです。

既定の ITraceManager サービスを置き換えることで、Web API トレース フレームワーク全体を独自のカスタム フレームワークに置き換えることもできます。

config.Services.Replace(typeof(ITraceManager), new MyTraceManager());

トレース システムを初期化するには、ITraceManager.Initialize を実装します。 これは、Web API に組み込まれているすべてのトレース コードを含め、トレース フレームワーク "全体" を置き換える点に注意してください。