Rastreamento no ASP.NET Web API 2

Quando você está tentando depurar um aplicativo baseado na Web, não há substituto para um bom conjunto de logs de rastreamento. Este tutorial mostra como habilitar o rastreamento em ASP.NET Web API. Você pode usar esse recurso para rastrear o que a estrutura da API Web faz antes e depois de invocar o controlador. Você também pode usá-lo para rastrear seu próprio código.

Versões de software usadas no tutorial

• Visual Studio 2017 (também funciona com o Visual Studio 2015)
• API Web 2
• Microsoft.AspNet.WebApi.Tracing

Habilitar o rastreamento system.diagnostics na API Web

Primeiro, criaremos um novo projeto de aplicativo Web ASP.NET. No Visual Studio, no menu Arquivo , selecione Novo>Projeto. Em Modelos, Web, selecione ASP.NET Aplicativo Web.

Escolha o modelo de projeto da API Web.

No menu Ferramentas , selecione Gerenciador de Pacotes NuGet e, em seguida, Console de Gerenciamento de Pacotes.

Na janela Console do Gerenciador de Pacotes, digite os comandos a seguir.

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

O primeiro comando instala o pacote de rastreamento de API Web mais recente. Ele também atualiza os principais pacotes de API Web. O segundo comando atualiza o pacote WebApi.WebHost para a versão mais recente.

Observação

Se você quiser direcionar uma versão específica da API Web, use o sinalizador -Version ao instalar o pacote de rastreamento.

Abra o arquivo WebApiConfig.cs na pasta App_Start. Adicione o código a seguir ao método Register .

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

        // Other configuration code not shown.
    }
}

Esse código adiciona a classe SystemDiagnosticsTraceWriter ao pipeline da API Web. A classe SystemDiagnosticsTraceWriter grava rastreamentos em System.Diagnostics.Trace.

Para ver os rastreamentos, execute o aplicativo no depurador. No navegador, navegue até /api/values.

As instruções de rastreamento são gravadas na janela Saída no Visual Studio. (No menu Exibir , selecione Saída).

Como SystemDiagnosticsTraceWriter grava rastreamentos em System.Diagnostics.Trace, você pode registrar ouvintes de rastreamento adicionais; por exemplo, para gravar rastreamentos em um arquivo de log. Para obter mais informações sobre gravadores de rastreamento, consulte o tópico Ouvintes de Rastreamento no MSDN.

Configurando SystemDiagnosticsTraceWriter

O código a seguir mostra como configurar o gravador de rastreamento.

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

Há duas configurações que você pode controlar:

• IsVerbose: se for falso, cada rastreamento conterá informações mínimas. Se true, os rastreamentos incluem mais informações.
• MinimumLevel: define o nível mínimo de rastreamento. Os níveis de rastreamento, em ordem, são Depurar, Informações, Avisar, Erro e Fatal.

Adicionando rastreamentos ao seu aplicativo de API Web

Adicionar um gravador de rastreamento fornece acesso imediato aos rastreamentos criados pelo pipeline da API Web. Você também pode usar o gravador de rastreamento para rastrear seu próprio 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 obter o gravador de rastreamento, chame HttpConfiguration.Services.GetTraceWriter. De um controlador, esse método é acessível por meio da propriedade ApiController.Configuration .

Para gravar um rastreamento, você pode chamar o método ITraceWriter.Trace diretamente, mas a classe ITraceWriterExtensions define alguns métodos de extensão mais amigáveis. Por exemplo, o método Info mostrado acima cria um rastreamento com informações de nível de rastreamento.

Infraestrutura de rastreamento de API Web

Esta seção descreve como escrever um gravador de rastreamento personalizado para a API Web.

O pacote Microsoft.AspNet.WebApi.Tracing é criado com base em uma infraestrutura de rastreamento mais geral na API Web. Em vez de usar Microsoft.AspNet.WebApi.Tracing, você também pode conectar alguma outra biblioteca de rastreamento/registro em log, como NLog ou log4net.

Para coletar rastreamentos, implemente a interface ITraceWriter . Este é um exemplo simples:

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

O método ITraceWriter.Trace cria um rastreamento. O chamador especifica uma categoria e um nível de rastreamento. A categoria pode ser qualquer cadeia de caracteres definida pelo usuário. Sua implementação do Rastreamento deve fazer o seguinte:

1. Crie um novo TraceRecord. Inicialize-o com o nível de solicitação, categoria e rastreamento, conforme mostrado. Esses valores são fornecidos pelo chamador.
2. Invoque o delegado traceAction . Dentro desse delegado, espera-se que o chamador preencha o restante do TraceRecord.
3. Escreva TraceRecord usando qualquer técnica de registro em log desejada. O exemplo mostrado aqui simplesmente chama System.Diagnostics.Trace.

Definindo o gravador de rastreamento

Para habilitar o rastreamento, você deve configurar a API Web para usar a implementação do ITraceWriter . Faça isso por meio do objeto HttpConfiguration , conforme mostrado no seguinte código:

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

Somente um gravador de rastreamento pode estar ativo. Por padrão, a API Web define um rastreador "sem operação" que não faz nada. (O rastreador "no-op" existe para que o código de rastreamento não precise marcar se o gravador de rastreamento é nulo antes de gravar um rastreamento.)

Como funciona o rastreamento de API Web

O rastreamento na API Web usa um padrão de fachada : quando o rastreamento está habilitado, a API Web encapsula várias partes do pipeline de solicitação com classes que executam chamadas de rastreamento.

Por exemplo, ao selecionar um controlador, o pipeline usa a interface IHttpControllerSelector . Com o rastreamento habilitado, o pipeline insere uma classe que implementa IHttpControllerSelector , mas chama para a implementação real:

Os benefícios desse design incluem:

• Se você não adicionar um gravador de rastreamento, os componentes de rastreamento não serão instanciados e não terão nenhum impacto no desempenho.
• Se você substituir serviços padrão como IHttpControllerSelector por sua própria implementação personalizada, o rastreamento não será afetado, pois o rastreamento é feito pelo objeto wrapper.

Você também pode substituir toda a estrutura de rastreamento da API Web por sua própria estrutura personalizada, substituindo o serviço padrão ITraceManager :

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

Implemente ITraceManager.Initialize para inicializar seu sistema de rastreamento. Lembre-se de que isso substitui toda a estrutura de rastreamento, incluindo todo o código de rastreamento integrado à API Web.