Traccia nell'API Web ASP.NET 2

Quando si tenta di eseguire il debug di un'applicazione basata sul Web, non c'è sostituto per un buon set di log. Questa esercitazione illustra come abilitare la traccia nell'API Web ASP.NET. È possibile usare questa funzionalità per tracciare le operazioni del framework API Web prima e dopo aver richiamato il controller. È anche possibile usarlo per tracciare il proprio codice.

Versioni software usate nell'esercitazione

• Visual Studio 2017 (funziona anche con Visual Studio 2015)
• Web API 2
• Microsoft.AspNet.WebApi.Tracing

Abilitare il tracciamento di System.Diagnostics nell'API Web

Prima di tutto, verrà creato un nuovo progetto di applicazione Web ASP.NET. In Visual Studio, dal menu File, selezionare Nuovo>Progetto. In Modelli, Web, seleziona Applicazione Web ASP.NET.

Scegliere il modello di progetto API Web.

Dal menu Strumenti selezionare Gestione pacchetti NuGet e quindi Console di gestione pacchetti.

Nella finestra Console di Gestione pacchetti digitare i comandi seguenti.

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

Il primo comando installa il pacchetto di traccia dell'API Web più recente. Aggiorna anche i pacchetti principali dell'API Web. Il secondo comando aggiorna il pacchetto WebApi.WebHost alla versione più recente.

Aprire il file WebApiConfig.cs nella cartella App_Start. Aggiungere il codice seguente al metodo Register .

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

        // Other configuration code not shown.
    }
}

Questo codice aggiunge la classe SystemDiagnosticsTraceWriter alla pipeline dell'API Web. La classe SystemDiagnosticsTraceWriter scrive tracce in System.Diagnostics.Trace.

Per visualizzare le tracce, eseguire l'applicazione nel debugger. Nel browser passare a /api/values.

Le istruzioni di traccia vengono scritte nella finestra di Output di Visual Studio. Dal menu Visualizza selezionare Output.

Poiché SystemDiagnosticsTraceWriter scrive tracce in System.Diagnostics.Trace, è possibile registrare listener di traccia aggiuntivi; Ad esempio, per scrivere tracce in un file di log. Per altre informazioni sugli scrittori di tracce, vedere l'argomento Listener di tracce su MSDN.

Configurazione di SystemDiagnosticsTraceWriter

Il codice seguente mostra come configurare il trace writer.

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

Esistono due impostazioni che è possibile controllare:

• IsVerbose: se false, ogni traccia contiene informazioni minime. Se true, le tracce includono altre informazioni.
• MinimumLevel: imposta il livello di traccia minimo. I livelli di traccia, in ordine, sono Debug, Info, Avviso, Errore e Fatale.

Aggiungere tracce all'applicazione API Web

L'aggiunta di un writer di traccia consente di accedere immediatamente alle tracce create dalla pipeline dell'API Web. È anche possibile utilizzare lo strumento di traccia per tracciare il proprio codice:

using System.Web.Http.Tracing;

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

        // ...
    }
}

Per ottenere il writer di traccia, chiamare HttpConfiguration.Services.GetTraceWriter. Da un controller, questo metodo è accessibile tramite la proprietà ApiController.Configuration .

Per scrivere una traccia, è possibile chiamare direttamente il metodo ITraceWriter.Trace , ma la classe ITraceWriterExtensions definisce alcuni metodi di estensione più descrittivi. Ad esempio, il metodo Info illustrato in precedenza crea una traccia con livello di traccia Info.

Infrastruttura di traccia api Web

Questa sezione descrive come scrivere un writer di traccia personalizzato per l'API Web.

Il pacchetto Microsoft.AspNet.WebApi.Tracing si basa su un'infrastruttura di traccia più generale nell'API Web. Anziché usare Microsoft.AspNet.WebApi.Tracing, è anche possibile collegare altre librerie di traccia/registrazione, ad esempio NLog o log4net.

Per raccogliere tracce, implementare l'interfaccia ITraceWriter . Ecco un semplice esempio:

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

Il metodo ITraceWriter.Trace crea una traccia. Il chiamante specifica una categoria e un livello di traccia. La categoria può essere qualsiasi stringa definita dall'utente. L'implementazione di Trace deve eseguire le operazioni seguenti:

1. Creare un nuovo oggetto TraceRecord. Inizializzarlo con la richiesta, la categoria e il livello di traccia, come illustrato. Questi valori vengono forniti dal chiamante.
2. Richiama il delegato traceAction. All'interno di questo delegato, il chiamante dovrebbe compilare il resto del TraceRecord.
3. Scrivere TraceRecord usando qualsiasi tecnica di registrazione desiderata. L'esempio illustrato qui chiama semplicemente System.Diagnostics.Trace.

Impostazione del writer di traccia

Per abilitare la traccia, è necessario configurare l'API Web per l'uso dell'implementazione di ITraceWriter . A tale scopo, usare l'oggetto HttpConfiguration , come illustrato nel codice seguente:

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

Un solo scrittore di traccia può essere attivo. Per impostazione predefinita, l'API Web imposta una traccia "no-op" che non esegue alcuna operazione. La traccia "no-op" esiste affinché il codice di traccia non debba controllare se lo scrittore di tracce è null prima di scrivere una traccia.

Come funziona il tracciamento delle API Web

La traccia nell'API Web usa un modello di facciata : quando la traccia è abilitata, l'API Web esegue il wrapping di varie parti della pipeline di richiesta con classi che eseguono chiamate di traccia.

Ad esempio, quando si seleziona un controller, la pipeline usa l'interfaccia IHttpControllerSelector . Con il tracciamento abilitato, la pipeline inserisce una classe che implementa IHttpControllerSelector ma si collega all'implementazione reale.

I vantaggi di questa progettazione includono:

• Se non si aggiunge un writer di tracing, i componenti di tracing non vengono istanziati e non hanno alcun impatto sulle prestazioni.
• Se si sostituiscono servizi predefiniti come IHttpControllerSelector con la propria implementazione personalizzata, il tracciamento non viene influenzato, perché viene eseguito dall'oggetto di wrapping.

È anche possibile sostituire l'intero framework di traccia API Web con il proprio framework personalizzato, sostituendo il servizio ITraceManager predefinito:

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

Implementare ITraceManager.Initialize per inizializzare il sistema di tracciamento. Tenere presente che sostituisce l'intero framework di traccia, incluso tutto il codice di traccia integrato nell'API Web.