Seguimiento en ASP.NET Web API 2

Cuando intenta depurar una aplicación basada en 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 estas características para rastros de lo que hace el marco de la API web antes y después de invocar a 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 ASP.NET Aplicación web.

Elija la plantilla de proyecto de API web.

En el menú Herramientas, seleccione administrador de paquetes NuGety, a continuación, consola de administración de paquetes.

En la ventana de la consola del administrador de paquetes, escriba los comandos siguientes.

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.

Nota:

Si desea tener como destino una versión específica de la API web, use la marca -Version al instalar el paquete de seguimiento.

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 API web. La clase SystemDiagnosticsTraceWriter escribe seguimientos en System.Diagnostics.Trace.

Para ver los seguimientos, ejecute la aplicación en el depurador. En el explorador, vaya a /api/values.

Las instrucciones de seguimiento se escriben en la ventana 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 escritores de seguimiento, consulte el tema agentes de escucha de seguimiento en MSDN.

Configuración de SystemDiagnosticsTraceWriter

En el código siguiente se muestra cómo configurar el sistema de escritura de seguimiento.

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

Hay dos configuraciones que puede controlar:

• IsVerbose: si es false, cada seguimiento contiene información mínima. Si es true, los seguimientos 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.

Adición de seguimientos a la aplicación de API web

Agregar un escritor de seguimiento proporciona acceso inmediato a los seguimientos creados por la canalización de 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, se puede acceder a este método a través de la propiedad ApiController.Configuration.

Para escribir un seguimiento, puede llamar directamente al método ITraceWriter.Trace, pero la claseITraceWriterExtensions define algunos métodos de extensión que son más descriptivos. Por ejemplo, el método Info mostrado anteriormente crea un seguimiento con el nivel de seguimiento 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 interfazITraceWriter. A continuación se incluye 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 TraceRecord. Inicialícelo con el nivel de solicitud, categoría y seguimiento, como se muestra. El autor de la llamada proporciona estos valores.
2. Invoque el delegado de traceAction. Dentro de este delegado, se espera que el autor de la llamada rellene el resto de TraceRecord.
3. Escriba el TraceRecord con cualquier técnica de registro que desee. El ejemplo que se muestra aquí simplemente llama a System.Diagnostics.Trace.

Establecimiento del sistema de escritura de seguimiento

Para habilitar el seguimiento, debe configurar la API web para que use la implementación de ITraceWriter. Esto se hace a través del objetoHttpConfiguration, 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 seguimiento "sin operación" que no hace nada. (El seguimiento "no-op" existe para que el código de seguimiento no tenga que comprobar si el escritor de seguimiento es null antes de escribir un seguimiento).

Cómo funciona el seguimiento de API web

El seguimiento en la API web usa un patrón de fachada: cuando se habilita el seguimiento, la API web encapsula 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 llama a la implementación real:

Entre las ventajas de este diseño se incluyen:

• Si no agrega un escritor de seguimiento, no se crean instancias de los componentes de seguimiento y no tienen ningún impacto en el rendimiento.
• Si reemplaza los servicios predeterminados, como IHttpControllerSelector por su propia implementación personalizada, el seguimiento no se ve afectado, porque 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 de ITraceManager predeterminado:

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

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