Traccia in API Web ASP.NET 2

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

Versioni software usate nell'esercitazione

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

Abilitare la traccia System.Diagnostics nell'API Web

Prima di tutto verrà creato un nuovo progetto di applicazione Web ASP.NET. In Visual Studio scegliere Nuovo>progetto dal menu File. In Modelliweb selezionare ASP.NET'applicazione Web.

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.

Nota

Se si vuole specificare come destinazione una versione specifica dell'API Web, usare il flag -Version quando si installa il pacchetto di traccia.

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 Output in Visual Studio. Scegliere Output dal menu Visualizza.

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 sui writer di traccia, vedere l'argomento Listener di traccia su MSDN.

Configurazione di SystemDiagnosticsTraceWriter

Nel codice seguente viene illustrato come configurare il writer di traccia.

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

Sono disponibili due impostazioni che è possibile controllare:

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

Aggiunta di 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 usare il writer di traccia per tracciare il codice personalizzato:

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 sopra crea una traccia con informazioni sul livello di traccia.

Infrastruttura di traccia dell'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 . Di seguito è riportato 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. Richiamare il delegato traceAction . All'interno di questo delegato, è previsto che il chiamante compili il resto di TraceRecord.
3. Scrivere TraceRecord usando qualsiasi tecnica di registrazione desiderata. L'esempio illustrato qui chiama semplicemente in 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());
}

Può essere attivo un solo writer di traccia. Per impostazione predefinita, l'API Web imposta un traccia "no-op" che non esegue alcuna operazione. L'analisi "no-op" esiste in modo che il codice di traccia non deve controllare se il writer di traccia è Null prima di scrivere una traccia.

Funzionamento della traccia dell'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 la traccia abilitata, la pipeline inserisce una classe che implementa IHttpControllerSelector , ma chiama attraverso l'implementazione reale:

I vantaggi di questa progettazione includono:

• Se non si aggiunge un writer di traccia, i componenti di traccia non vengono create istanze e non hanno alcun impatto sulle prestazioni.
• Se si sostituiscono servizi predefiniti come IHttpControllerSelector con la propria implementazione personalizzata, la traccia non è interessata, perché la traccia viene eseguita dall'oggetto wrapper.

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

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

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