ASP.NET Web API 2 中的跟踪

作者: Mike Wasson

尝试调试基于 web 的应用程序时,不能替代一组良好的跟踪日志。 本教程演示如何在 ASP.NET Web API 中启用跟踪。 您可以使用此功能跟踪 Web API 框架在调用控制器之前和之后执行的操作。 你还可以使用它来跟踪你自己的代码。

本教程中使用的软件版本

在 Web API 中启用诊断跟踪

首先,我们将创建一个新的 ASP.NET Web 应用程序项目。 在 Visual Studio 的 "文件" 菜单中,选择 "新建" > 项目"。 在"模板 " 下,选择 " ASP.NET Web 应用程序"。

选择 "Web API 项目" 模板。

从 "工具" 菜单中,依次选择 " NuGet 包管理器"、"包管理控制台"。

在 "包管理器控制台" 窗口中,键入以下命令。

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

第一个命令安装最新的 Web API 跟踪包。 它还会更新核心 Web API 包。 第二个命令将 WebApi 包更新到最新版本。

Note

如果要面向特定版本的 Web API,请在安装跟踪包时使用-Version 标志。

在应用_启动文件夹中打开文件 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 类将跟踪写入到

若要查看跟踪,请在调试器中运行应用程序。 在浏览器中,导航到 /api/values

跟踪语句将写入 Visual Studio 中的 "输出" 窗口。 (从 "视图" 菜单中选择 "输出")。

由于SystemDiagnosticsTraceWriter 将跟踪写入到 system.exception,因此你可以注册其他跟踪侦听器;例如,将跟踪写入日志文件。 有关跟踪编写器的详细信息,请参阅 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. GetTraceWriter。 通过控制器,可以通过ApiController属性访问此方法。

若要编写跟踪,可以直接调用ITraceWriter方法,但ITraceWriterExtensions类定义一些更友好的扩展方法。 例如,上面所示的Info方法会创建包含跟踪级别信息的跟踪。

Web API 跟踪基础结构

本部分介绍如何为 Web API 编写自定义跟踪编写器。

WebApi 包构建在 Web API 中更通用的跟踪基础结构之上。 你还可以不使用 WebApi,而是插入一些其他跟踪/日志记录库,例如NLoglog4net

若要收集跟踪,请实现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方法创建跟踪。 调用方指定类别和跟踪级别。 类别可以是任何用户定义的字符串。 跟踪的实现应执行以下操作:

  1. 创建新的TraceRecord。 用请求、类别和跟踪级别对其进行初始化,如下所示。 这些值由调用方提供。
  2. 调用traceAction委托。 在此委托内部,调用方应填写TraceRecord的其余部分。
  3. 使用你喜欢的任何日志记录技术编写TraceRecord。 此处所示的示例只调用了

设置跟踪编写器

若要启用跟踪,必须将 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以初始化跟踪系统。 请注意,这会替换整个跟踪框架,包括 Web API 中内置的所有跟踪代码。