ASP.NET Web API 2 中的追蹤

發行項
10/01/2024

當您嘗試偵錯 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 Package Manager]，然後選取 [套件管理主控台]。

在「套件管理員主控台」視窗中，鍵入以下命令。

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

第一個命令會安裝最新的 Web API 追蹤套件。它也會更新核心 Web API 套件。第二個命令會將 WebApi.WebHost 套件更新為最新版本。

注意

如果您想要以特定版本的 Web API 為目標，請在安裝追蹤套件時使用 -Version 旗標。

在 [App_Start] 資料夾中開啟 WebApiConfig.cs 檔案。將下列程式碼新增至 [註冊] 方法。

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。

顯示已修改 URL 的影像

追蹤陳述式會寫入 Visual Studio 中的 [輸出] 視窗。 (請從 [檢視] 功能表選取 [輸出]。)

因為 SystemDiagnosticsTraceWriter 會將追蹤寫入 System.Diagnostics.Trace，因此您可以註冊其他追蹤接聽程式；例如，將追蹤寫入記錄檔。如需追蹤寫入器的詳細資訊，請參閱 MSDN 上的追蹤接聽程式主題。

設定 SystemDiagnosticsTraceWriter

下列程式碼會示範如何設定追蹤寫入器。

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

您有兩個可以控制的設定：

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 中較一般的追蹤基礎結構之上。您也可以插入一些其他追蹤/記錄程式庫，例如 NLog 或 log4net，而不是使用 Microsoft.AspNet.WebApi.Tracing。

若要收集追蹤，請實作 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 的實作應該執行下列動作：

建立新的 TraceRecord。使用要求、類別和追蹤層級進行初始化，如下所示。呼叫端會提供這些值。
叫用 traceAction 委派。在此委派內，呼叫端應該會填入 TraceRecord 的其餘部分。
使用您喜歡的任何記錄技術來撰寫 TraceRecord。此處顯示的範例會直接呼叫 System.Diagnostics.Trace。

設定追蹤寫入器

若要啟用追蹤，您必須設定 Web API 以使用 ITraceWriter 實作。您可以透過 HttpConfiguration 物件執行此動作，如下列程式碼所示：

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

只有一個追蹤寫入器可以使用。根據預設，Web API 會設定「無作業」追蹤程式，但不會執行任何動作。 (「無作業」追蹤程式存在，因此追蹤程式碼不需要在寫入追蹤之前檢查追蹤寫入器是否為 Null。)

Web API 追蹤的運作方式

Web API 中的追蹤會使用外觀模式：啟用追蹤時，Web API 會包裝要求管線的各個部分，其中包含執行追蹤呼叫的類別。

例如，選取控制器時，管線會使用 IHttpControllerSelector 介面。啟用追蹤之後，管線會插入實作 IHttpControllerSelector 但透過實際實作呼叫的類別：

Web API 追蹤會使用外觀模式。

此設計的優點包括：

如果您未新增追蹤寫入器，追蹤元件就不會具現化，而且不會影響效能。
如果您將 IHttpControllerSelector 等預設服務換成您自己的自訂實作，則追蹤不會受到影響，因為追蹤是由包裝函式物件完成。

您也可以藉由取代預設 ITraceManager 服務，將整個 Web API 追蹤架構換成您自己的自訂架構：

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

實作 ITraceManager.Initialize 來初始化追蹤系統。請注意，這會取代整個追蹤架構，包括 Web API 內建的所有追蹤程式碼。

共用方式為