ASP.NET Web API 2 中的跟踪

项目
06/16/2023

尝试调试基于 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 包。第二个命令将 WebApi.WebHost 包更新到最新版本。

注意

如果要以特定版本的 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。

显示修改后的 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 方法创建跟踪。调用方指定类别和跟踪级别。类别可以是任何用户定义的字符串。跟踪的实现应执行以下操作：

创建新的 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 设置不执行任何操作的“no-op”跟踪器。 (存在“no-op”跟踪器，因此跟踪代码不必在编写 trace 之前检查跟踪编写器是否为 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 中的所有跟踪代码。

通过