Trasování ve webovém rozhraní API ASP.NET 2

Když se pokoušíte ladit webovou aplikaci, neexistuje žádná náhrada za dobrou sadu protokolů trasování. V tomto kurzu se dozvíte, jak povolit trasování v ASP.NET webovém rozhraní API. Pomocí této funkce můžete sledovat, co architektura webového rozhraní API dělá před a po vyvolání kontroleru. Můžete ho také použít ke sledování vlastního kódu.

Verze softwaru použité v kurzu

• Visual Studio 2017 (funguje také se sadou Visual Studio 2015)
• Webové rozhraní API 2
• Microsoft.AspNet.WebApi.Tracing

Povolení trasování System.Diagnostics ve webovém rozhraní API

Nejprve vytvoříme nový projekt webové aplikace ASP.NET. V sadě Visual Studio v nabídce Soubor vyberte Nový>projekt. V části Šablony, Web vyberte ASP.NET Webová aplikace.

Zvolte šablonu projektu webového rozhraní API.

V nabídce Nástroje vyberte Správce balíčků NuGet a pak Konzola pro správu balíčků.

V okně Konzola Správce balíčků zadejte následující příkazy.

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

První příkaz nainstaluje nejnovější balíček trasování webového rozhraní API. Aktualizuje také základní balíčky webového rozhraní API. Druhý příkaz aktualizuje balíček WebApi.WebHost na nejnovější verzi.

Ve složce App_Start otevřete soubor WebApiConfig.cs. Do metody Register přidejte následující kód.

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

        // Other configuration code not shown.
    }
}

Tento kód přidá třídu SystemDiagnosticsTraceWriter do kanálu webového rozhraní API. SystemDiagnosticsTraceWriter Třída zapisuje trasování do System.Diagnostics.Trace.

Pokud chcete zobrazit trasování, spusťte aplikaci v ladicím programu. V prohlížeči přejděte na adresu /api/values.

Příkazy trasování se zapisují do okna Výstup v sadě Visual Studio. (V nabídce View (Zobrazení ) vyberte Output (Výstup).

Protože SystemDiagnosticsTraceWriter zapisuje trasování do System.Diagnostics.Trace, můžete zaregistrovat další naslouchací procesy trasování; například k zápisu trasování do souboru protokolu. Další informace o zapisovačích trasování najdete v tématu Naslouchací procesy trasování na webu MSDN.

Konfigurace SystemDiagnosticsTraceWriter

Následující kód ukazuje, jak nakonfigurovat zapisovač trasování.

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

Existují dvě nastavení, která můžete ovládat:

• IsVerbose: Pokud je false, každé trasování obsahuje minimální informace. Pokud je true, trasování obsahuje další informace.
• MinimumLevel: Nastaví minimální úroveň trasování. Úrovně trasování v pořadí jsou Debug (Ladění), Info (Informace), Warn (Upozornění), Error (Chyba) a Fatal (Závažná chyba).

Přidání trasování do aplikace webového rozhraní API

Přidáním zapisovače trasování získáte okamžitý přístup k trasování vytvořeným kanálem webového rozhraní API. K trasování vlastního kódu můžete použít také zapisovač trasování:

using System.Web.Http.Tracing;

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

        // ...
    }
}

Chcete-li získat trasovací zapisovač, zavolejte HttpConfiguration.Services.GetTraceWriter. Z kontroleru je tato metoda přístupná prostřednictvím vlastnosti ApiController.Configuration .

Chcete-li napsat trasování, můžete volat ITraceWriter.Trace metoda přímo, ale ITraceWriterExtensions třída definuje některé rozšiřující metody, které jsou přívětivější. Například výše uvedená metoda Info vytvoří trasování s informacemi na úrovni trasování.

Infrastruktura trasování webového rozhraní API

Tato část popisuje, jak napsat vlastní zapisovač trasování pro webové rozhraní API.

Balíček Microsoft.AspNet.WebApi.Tracing je založený na obecnější infrastruktuře trasování ve webovém rozhraní API. Místo použití Microsoft.AspNet.WebApi.Tracing můžete také připojit jinou knihovnu trasování/protokolování, jako je NLog nebo log4net.

Chcete-li shromažďovat trasování, implementujte rozhraní ITraceWriter . Tady je jednoduchý příklad:

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

ITraceWriter.Trace Metoda vytvoří trasování. Volající určuje kategorii a úroveň trasování. Kategorie může být libovolný řetězec definovaný uživatelem. Implementace trasování by měla provádět následující akce:

1. Vytvořte nový záznam trasování. Inicializujte ho pomocí úrovně požadavku, kategorie a trasování, jak je znázorněno na obrázku. Tyto hodnoty poskytuje volající.
2. Vyvolejte delegáta traceAction . Uvnitř tohoto delegáta se očekává, že volající vyplní zbytek TraceRecord.
3. Zapište trasovacízáznam pomocí libovolné techniky protokolování, která se vám líbí. Zde uvedený příklad jednoduše volá System.Diagnostics.Trace.

Nastavení zapisovače trasování

Pokud chcete povolit trasování, musíte nakonfigurovat webové rozhraní API tak, aby používalo vaši implementaci ITraceWriter . Provedete to prostřednictvím objektu HttpConfiguration , jak je znázorněno v následujícím kódu:

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

Aktivní může být pouze jeden zapisovač trasování. Ve výchozím nastavení webové rozhraní API nastaví trasovací nástroj no-op, který nic nedělá. (Tracer no-op existuje, takže trasovací kód nemusí před zápisem trasování kontrolovat, jestli má zapisovač trasování hodnotu null .)

Jak funguje trasování webového rozhraní API

Trasování ve webovém rozhraní API používá vzor fasády : Pokud je trasování povolené, webové rozhraní API zabalí různé části kanálu požadavku do tříd, které provádějí volání trasování.

Například při výběru kontroleru kanál používá rozhraní IHttpControllerSelector . Když je trasování povolené, kanál vloží třídu, která implementuje IHttpControllerSelector , ale volá ji do skutečné implementace:

Mezi výhody tohoto návrhu patří:

• Pokud nezapisovač trasování nepřidáte, nebudou instance trasovacích komponent vytvořena a nebudou mít žádný dopad na výkon.
• Pokud nahradíte výchozí služby, jako je IHttpControllerSelector vlastní implementací, trasování nebude ovlivněno, protože trasování provádí objekt obálky.

Celou architekturu trasování webového rozhraní API můžete také nahradit vlastní architekturou, a to nahrazením výchozí služby ITraceManager :

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

Implementujte ITraceManager.Initialize pro inicializaci trasovacího systému. Mějte na paměti, že se tím nahradí celá architektura trasování, včetně veškerého kódu trasování, který je integrovaný do webového rozhraní API.