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 包。 第二个命令将 WebApi.WebHost 包更新为最新版本。

打开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;

有两种设置可以控制：

• 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 方法创建跟踪。 调用方指定类别和跟踪级别。 类别可以是任何用户定义的字符串。 您对跟踪的实现需要执行以下操作：

1. 创建新的 TraceRecord。 使用请求、类别和跟踪级别初始化它，如下所示。 这些值由调用方提供。
2. 调用 traceAction 委托。 在此委托中，调用方应填写 TraceRecord 的其余部分。
3. 使用喜欢的任何日志记录技术编写 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”跟踪器，以便跟踪代码不必在编写跟踪之前检查跟踪编写器是否 为 null 。

Web API 跟踪的工作原理

Web API 中的跟踪使用 外观 模式：启用跟踪后，Web API 使用执行跟踪调用的类包装请求管道的各个部分。

例如，选择控制器时，管道使用 IHttpControllerSelector 接口。 启用跟踪后，管道将插入实现 IHttpControllerSelector 的类，但会调用实际实现：

此设计的优点包括：

• 如果未添加跟踪编写器，则不会实例化跟踪组件，并且不会影响性能。
• 如果将 IHttpControllerSelector 等默认服务替换为自己的自定义实现，则跟踪不会受到影响，因为跟踪是由包装器对象完成的。

还可以通过替换默认 ITraceManager 服务，将整个 Web API 跟踪框架替换为自己的自定义框架：

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

实现 ITraceManager.Initialize 以初始化跟踪系统。 请注意，这将替换 整个 跟踪框架，包括内置于 Web API 中的所有跟踪代码。