Seguimiento en ASP.NET Web API 2

Cuando intenta depurar una aplicación basada en la web, no hay ningún sustituto para un buen conjunto de registros de seguimiento. En este tutorial se muestra cómo habilitar el seguimiento en ASP.NET API web. Puede usar esta funcionalidad para realizar un seguimiento de lo que hace el marco de trabajo de Web API antes y después de invocar su controlador. También puede usarlo para realizar un seguimiento de su propio código.

Versiones de software usadas en el tutorial

• Visual Studio 2017 (también funciona con Visual Studio 2015)
• Web API 2
• Microsoft.AspNet.WebApi.Tracing

Habilitación del seguimiento de System.Diagnostics en la API web

En primer lugar, crearemos un nuevo proyecto de aplicación web ASP.NET. En Visual Studio, en el menú Archivo , seleccione Nuevo>proyecto. En Plantillas, Web, seleccione Aplicación web ASP.NET.

Elija la plantilla de proyecto de API web.

En el menú Herramientas , seleccione Administrador de paquetes NuGet y, después, Consola de administración de paquetes.

En la ventana Consola del Administrador de paquetes, escriba los siguientes comandos.

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

El primer comando instala el paquete de seguimiento de API web más reciente. También actualiza los paquetes principales de la API web. El segundo comando actualiza el paquete WebApi.WebHost a la versión más reciente.

Abra el archivo WebApiConfig.cs en la carpeta App_Start. Agregue el código siguiente al método Register .

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

        // Other configuration code not shown.
    }
}

Este código agrega la clase SystemDiagnosticsTraceWriter a la canalización de la API web. La clase SystemDiagnosticsTraceWriter escribe seguimientos en System.Diagnostics.Trace.

Para ver las trazas, ejecute la aplicación desde el depurador. En el explorador, vaya a /api/values.

Las instrucciones de seguimiento se escriben en la ventana de salida de Visual Studio. (En el menú Ver , seleccione Salida).

Dado que SystemDiagnosticsTraceWriter escribe seguimientos en System.Diagnostics.Trace, puede registrar agentes de escucha de seguimiento adicionales; por ejemplo, para escribir seguimientos en un archivo de registro. Para obtener más información sobre los emisores de seguimiento, consulte el tema Escuchadores de trazas en MSDN.

Configuración de SystemDiagnosticsTraceWriter

En el código siguiente se muestra cómo configurar el escritor de trazas.

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

Hay dos configuraciones que puede controlar:

• IsVerbose: Si es falso, cada traza contiene información mínima. Si es verdadero, las trazas incluyen más información.
• MinimumLevel: establece el nivel de seguimiento mínimo. Los niveles de seguimiento, en orden, son Debug, Info, Warn, Error y Fatal.

Añadiendo rastros a su aplicación de API web

Agregar un registrador de trazas proporciona acceso inmediato a las trazas creadas por la tubería de la API web. También puede usar el escritor de seguimiento para realizar un seguimiento de su propio código:

using System.Web.Http.Tracing;

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

        // ...
    }
}

Para obtener el escritor de seguimiento, llame a HttpConfiguration.Services.GetTraceWriter. Desde un controlador, este método es accesible a través de la propiedad ApiController.Configuration .

Para escribir una traza, puede llamar directamente al método ITraceWriter.Trace, pero la clase ITraceWriterExtensions define algunos métodos de extensión que son más accesibles. Por ejemplo, el método Info mostrado anteriormente crea un seguimiento con nivel de traza Info.

Infraestructura de seguimiento de API web

En esta sección se describe cómo escribir un escritor de seguimiento personalizado para la API web.

El paquete Microsoft.AspNet.WebApi.Tracing se basa en una infraestructura de seguimiento más general en la API web. En lugar de usar Microsoft.AspNet.WebApi.Tracing, también puede conectar otras bibliotecas de seguimiento o registro, como NLog o log4net.

Para recopilar seguimientos, implemente la interfaz ITraceWriter . Este es un ejemplo sencillo:

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);
    }
}

El método ITraceWriter.Trace crea un seguimiento. El autor de la llamada especifica una categoría y un nivel de seguimiento. La categoría puede ser cualquier cadena definida por el usuario. La implementación de Trace debe hacer lo siguiente:

1. Cree un nuevo objeto TraceRecord. Inicialícelo con la solicitud, categoría y nivel de traza, como se muestra. El autor de la llamada proporciona estos valores.
2. Invoque el delegado traceAction . Dentro de este delegado, se espera que el autor de la llamada rellene el resto de TraceRecord.
3. Escriba TraceRecord, con cualquier técnica de registro que desee. El ejemplo que se muestra aquí simplemente llama a System.Diagnostics.Trace.

Configurar el escritor de trazas

Para habilitar el seguimiento, debe configurar la API web para que use la implementación de ITraceWriter . Esto se hace a través del objeto HttpConfiguration , como se muestra en el código siguiente:

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

Solo un escritor de seguimiento puede estar activo. De forma predeterminada, la API web establece un trazador "no-op" que no realiza ninguna acción. (El tracer "no-op" existe para que el código de registro no tenga que comprobar si el escritor del registro es nulo antes de escribir un registro).

Cómo funciona el seguimiento de API web

El seguimiento en Web API usa un patrón de fachada: cuando se habilita el seguimiento, Web API envuelve varias partes de la canalización de solicitudes con clases que realizan llamadas de seguimiento.

Por ejemplo, al seleccionar un controlador, la canalización usa la interfaz IHttpControllerSelector . Con el seguimiento habilitado, la canalización inserta una clase que implementa IHttpControllerSelector, pero redirige la llamada a la implementación real.

Entre las ventajas de este diseño se incluyen:

• Si no agrega un escritor de trazas, los componentes de seguimiento no se instancian y no tienen ningún impacto en el rendimiento.
• Si reemplaza servicios predeterminados como IHttpControllerSelector por su propia implementación personalizada, el seguimiento no se ve afectado, ya que el objeto contenedor realiza el seguimiento.

También puede reemplazar todo el marco de seguimiento de la API web por su propio marco personalizado reemplazando el servicio ITraceManager predeterminado:

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

Implemente ITraceManager.Initialize para inicializar el sistema de seguimiento. Tenga en cuenta que esto reemplaza todo el marco de seguimiento, incluido todo el código de seguimiento integrado en la API web.