Ablaufverfolgung in ASP.NET Web-API 2

Wenn Sie versuchen, eine webbasierte Anwendung zu debuggen, gibt es keinen Ersatz für einen guten Satz von Ablaufverfolgungsprotokollen. In dieser Anleitung wird gezeigt, wie Sie das Tracing in ASP.NET Web-API aktivieren. Mit diesem Feature können Sie nachverfolgen, was das Web-API-Framework vor und nach dem Aufrufen des Controllers ausführt. Sie können es auch verwenden, um Ihren eigenen Code nachzuverfolgen.

Im Lernprogramm verwendete Softwareversionen

• Visual Studio 2017 (funktioniert auch mit Visual Studio 2015)
• Web-API 2
• Microsoft.AspNet.WebApi.Tracing

System.Diagnostics-Ablaufverfolgung in Web-API aktivieren

Zunächst erstellen wir ein neues ASP.NET Webanwendungsprojekt. Wählen Sie in Visual Studio im Menü "Datei" die Option "Neues Projekt"> aus. Wählen Sie unter "Vorlagen" "Web" ASP.NET Webanwendung aus.

Wählen Sie die Web-API-Projektvorlage aus.

Wählen Sie im Menü "Extras " die Option "NuGet-Paket-Manager" und dann die Konsole "Paket verwalten" aus.

Geben Sie im Paket-Manager-Konsolenfenster die folgenden Befehle ein.

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

Der erste Befehl installiert das neueste Web-API-Ablaufverfolgungspaket. Außerdem werden die wichtigsten Web-API-Pakete aktualisiert. Der zweite Befehl aktualisiert das WebApi.WebHost-Paket auf die neueste Version.

Öffnen Sie die Datei WebApiConfig.cs im Ordner App_Start. Fügen Sie der Register-Methode den folgenden Code hinzu.

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

        // Other configuration code not shown.
    }
}

Dieser Code fügt der Web-API-Pipeline die SystemDiagnosticsTraceWriter-Klasse hinzu. Die SystemDiagnosticsTraceWriter-Klasse schreibt Ablaufverfolgungen in System.Diagnostics.Trace.

Führen Sie die Anwendung im Debugger aus, um die Ablaufverfolgungen anzuzeigen. Navigieren Sie im Browser zu /api/values.

Die Trace-Anweisungen werden im Visual Studio-Ausgabefenster geschrieben. (Wählen Sie im Menü "Ansicht" die Option "Ausgabe" aus.

Da SystemDiagnosticsTraceWriter Ablaufverfolgungen in System.Diagnostics.Trace schreibt, können Sie zusätzliche Ablaufverfolgungs-Listener registrieren, z. B. zum Schreiben von Ablaufverfolgungen in eine Protokolldatei. Weitere Informationen zu Ablaufverfolgungs-Schreibern finden Sie im Thema "Ablaufverfolgungs-Listener" auf MSDN.

Konfigurieren von SystemDiagnosticsTraceWriter

Der folgende Code zeigt, wie der Trace Writer konfiguriert wird.

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

Es gibt zwei Einstellungen, die Sie steuern können:

• IsVerbose: Bei "false" enthält jede Ablaufverfolgung minimale Informationen. Wenn wahr, enthalten Traces mehr Informationen.
• MinimumLevel: Legt die minimale Ablaufverfolgungsebene fest. Ablaufverfolgungsebenen sind in der Reihenfolge "Debug", "Info", "Warn", "Error" und "Fatal".

Zur Web-API-Anwendung Traces hinzufügen

Durch das Hinzufügen eines Ablaufverfolgungsschreibers erhalten Sie sofortigen Zugriff auf die von der Web-API-Pipeline erstellten Ablaufverfolgungen. Sie können auch den Trace Writer verwenden, um Ihren eigenen Code zu tracen.

using System.Web.Http.Tracing;

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

        // ...
    }
}

Rufen Sie "HttpConfiguration.Services.GetTraceWriter" auf, um den Ablaufverfolgungs-Writer abzurufen. Über einen Controller kann über die ApiController.Configuration-Eigenschaft auf diese Methode zugegriffen werden.

Zum Schreiben einer Ablaufverfolgung können Sie die ITraceWriter.Trace-Methode direkt aufrufen, aber die ITraceWriterExtensions-Klasse definiert einige Erweiterungsmethoden, die benutzerfreundlicher sind. Die oben gezeigte Info-Methode erstellt z. B. eine Ablaufverfolgung mit dem Info-Ablaufverfolgungslevel.

Web-API-Ablaufverfolgungsinfrastruktur

In diesem Abschnitt wird beschrieben, wie Sie einen benutzerdefinierten Ablaufverfolgungs-Schreiber für die Web-API schreiben.

Das Microsoft.AspNet.WebApi.Tracing-Paket basiert auf einer allgemeineren Tracing-Infrastruktur in der Web-API. Anstatt Microsoft.AspNet.WebApi.Tracing zu verwenden, können Sie auch eine andere Ablaufverfolgungs-/Protokollierungsbibliothek wie NLog oder Log4net anschließen.

Um Traces zu sammeln, implementieren Sie die ITraceWriter-Schnittstelle. Hier ist ein einfaches Beispiel:

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

Die ITraceWriter.Trace-Methode erstellt eine Ablaufverfolgung. Der Aufrufer gibt eine Kategorie und den Überwachungsgrad an. Die Kategorie kann eine beliebige benutzerdefinierte Zeichenfolge sein. Ihre Implementierung von Trace sollte folgendes ausführen:

1. Erstellen Sie einen neuen TraceRecord. Initialisieren Sie sie mit der Anforderungs-, Kategorie- und Ablaufverfolgungsebene, wie dargestellt. Diese Werte werden vom Aufrufer bereitgestellt.
2. Rufen Sie den traceAction-Delegaten auf. Innerhalb dieses Delegaten wird erwartet, dass der Aufrufer den Rest des TraceRecord ausfüllt.
3. Schreiben Sie den TraceRecord mit jeder beliebigen Protokollierungsmethode. Das hier gezeigte Beispiel ruft einfach System.Diagnostics.Trace auf.

Einrichten des Ablaufverfolgungsschreibers

Um die Ablaufverfolgung zu aktivieren, müssen Sie die Web-API für die Verwendung Ihrer ITraceWriter-Implementierung konfigurieren. Dies erfolgt über das HttpConfiguration-Objekt , wie im folgenden Code gezeigt:

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

Nur ein Ablaufverfolgungsschreiber kann aktiv sein. Standardmäßig legt die Web-API einen „no-op“-Tracer fest, der keine Aktion ausführt. (Der "no-op"-Tracer existiert, damit der Ablaufverfolgungscode nicht überprüfen muss, ob der Trace-Writer null ist, bevor eine Ablaufverfolgung geschrieben wird.)

Funktionsweise der Web-API-Ablaufverfolgung

Die Ablaufverfolgung in der Web-API verwendet ein Fassadenmuster : Wenn die Ablaufverfolgung aktiviert ist, umschließt die Web-API verschiedene Teile der Anforderungspipeline mit Klassen, die Ablaufverfolgungsaufrufe ausführen.

Wenn Sie beispielsweise einen Controller auswählen, verwendet die Pipeline die IHttpControllerSelector-Schnittstelle . Wenn die Ablaufverfolgung aktiviert ist, fügt die Pipeline eine Klasse ein, die IHttpControllerSelector implementiert und den Aufruf an die eigentliche Implementierung weiterleitet.

Zu den Vorteilen dieses Designs gehören:

• Wenn Sie keinen Trace Writer hinzufügen, werden die Ablaufverfolgungskomponenten nicht instanziiert und beeinflussen die Leistung nicht.
• Wenn Sie Standarddienste wie IHttpControllerSelector durch Ihre eigene benutzerdefinierte Implementierung ersetzen, ist die Ablaufverfolgung nicht betroffen, da die Ablaufverfolgung vom Wrapperobjekt erfolgt.

Sie können auch das gesamte Web-API-Ablaufverfolgungsframework durch Ihr eigenes benutzerdefiniertes Framework ersetzen, indem Sie den standardmäßigen ITraceManager-Dienst ersetzen:

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

Implementieren Sie ITraceManager.Initialize , um Ihr Ablaufverfolgungssystem zu initialisieren. Beachten Sie, dass dies das komplette Tracing-Framework ersetzt, einschließlich des kompletten Tracing-Codes, der in die Web-API integriert ist.