Śledzenie w internetowym interfejsie API ASP.NET 2

Artykuł
06/16/2023

Podczas próby debugowania aplikacji internetowej nie ma substytutu dobrego zestawu dzienników śledzenia. W tym samouczku pokazano, jak włączyć śledzenie w interfejsie API sieci Web ASP.NET. Za pomocą tej funkcji można śledzić, co platforma internetowego interfejsu API wykonuje przed wywołaniami kontrolera i po jego wywołaniu. Można go również użyć do śledzenia własnego kodu.

Wersje oprogramowania używane w samouczku

Visual Studio 2017 (działa również z programem Visual Studio 2015)

Internetowy interfejs API 2

Microsoft.AspNet.WebApi.Tracing

Włączanie śledzenia System.Diagnostics w internetowym interfejsie API

Najpierw utworzymy nowy projekt aplikacji internetowej ASP.NET. W programie Visual Studio z menu Plik wybierz pozycję Nowy>projekt. W obszarze Szablony wybierz pozycję Sieć WebASP.NET aplikacji internetowej.

Wybierz szablon projektu internetowego interfejsu API.

W menu Narzędzia wybierz pozycję Menedżer pakietów NuGet, a następnie pozycję Zarządzaj konsolą pakietu.

W oknie Konsola menedżera pakietów wpisz następujące polecenia.

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

Pierwsze polecenie instaluje najnowszy pakiet śledzenia internetowego interfejsu API. Aktualizuje również podstawowe pakiety internetowego interfejsu API. Drugie polecenie aktualizuje pakiet WebApi.WebHost do najnowszej wersji.

Uwaga

Jeśli chcesz wybrać określoną wersję internetowego interfejsu API, użyj flagi -Version podczas instalowania pakietu śledzenia.

Otwórz plik WebApiConfig.cs w folderze App_Start. Dodaj następujący kod do metody Register .

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

        // Other configuration code not shown.
    }
}

Ten kod dodaje klasę SystemDiagnosticsTraceWriter do potoku internetowego interfejsu API. Klasa SystemDiagnosticsTraceWriter zapisuje ślady w pliku System.Diagnostics.Trace.

Aby wyświetlić ślady, uruchom aplikację w debugerze. W przeglądarce przejdź do strony /api/values.

Obraz przedstawiający zmodyfikowany język U R L

Instrukcje śledzenia są zapisywane w oknie Dane wyjściowe w programie Visual Studio. (Z menu Widok wybierz pozycję Dane wyjściowe).

Ponieważ SystemDiagnosticsTraceWriter zapisuje ślady w pliku System.Diagnostics.Trace, można zarejestrować dodatkowe odbiorniki śledzenia; na przykład w celu zapisania śladów w pliku dziennika. Aby uzyskać więcej informacji na temat zapisywania śladów, zobacz temat Trace Listeners (Odbiorniki śledzenia) w witrynie MSDN.

Konfigurowanie narzędzia SystemDiagnosticsTraceWriter

Poniższy kod przedstawia sposób konfigurowania składnika zapisywania śledzenia.

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

Istnieją dwa ustawienia, które można kontrolować:

IsVerbose: jeśli jest fałsz, każdy ślad zawiera minimalne informacje. Jeśli wartość true, ślady zawierają więcej informacji.
MinimumLevel: ustawia minimalny poziom śledzenia. Poziomy śledzenia, w kolejności, to Debug, Info, Warn, Error i Fatal.

Dodawanie śladów do aplikacji internetowego interfejsu API

Dodanie składnika zapisywania śledzenia zapewnia natychmiastowy dostęp do śladów utworzonych przez potok internetowego interfejsu API. Możesz również użyć modułu zapisywania śledzenia do śledzenia własnego kodu:

using System.Web.Http.Tracing;

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

        // ...
    }
}

Aby uzyskać składnik zapisywania śledzenia, wywołaj metodę HttpConfiguration.Services.GetTraceWriter. Z poziomu kontrolera ta metoda jest dostępna za pośrednictwem właściwości ApiController.Configuration .

Aby napisać ślad, możesz bezpośrednio wywołać metodę ITraceWriter.Trace , ale klasa ITraceWriterExtensions definiuje niektóre metody rozszerzenia, które są bardziej przyjazne. Na przykład metoda Info pokazana powyżej tworzy ślad z informacjami o poziomie śledzenia.

Infrastruktura śledzenia internetowego interfejsu API

W tej sekcji opisano sposób pisania niestandardowego składnika zapisywania śledzenia dla internetowego interfejsu API.

Pakiet Microsoft.AspNet.WebApi.Tracing jest oparty na bardziej ogólnej infrastrukturze śledzenia w internetowym interfejsie API. Zamiast używać funkcji Microsoft.AspNet.WebApi.Tracing, możesz również podłączyć inną bibliotekę śledzenia/rejestrowania, taką jak NLog lub log4net.

Aby zbierać ślady, zaimplementuj interfejs ITraceWriter . Oto prosty przykład:

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

Metoda ITraceWriter.Trace tworzy ślad. Obiekt wywołujący określa kategorię i poziom śledzenia. Kategoria może być dowolnym ciągiem zdefiniowanym przez użytkownika. Implementacja funkcji Trace powinna wykonać następujące czynności:

Utwórz nowy element TraceRecord. Zainicjuj je za pomocą żądania, kategorii i poziomu śledzenia, jak pokazano. Te wartości są dostarczane przez obiekt wywołujący.
Wywołaj delegata traceAction . Wewnątrz tego delegata obiekt wywołujący powinien wypełnić resztę elementu TraceRecord.
Napisz element TraceRecord przy użyciu dowolnej techniki rejestrowania. W tym przykładzie pokazano po prostu wywołanie elementu System.Diagnostics.Trace.

Ustawianie składnika zapisywania śledzenia

Aby włączyć śledzenie, należy skonfigurować internetowy interfejs API do korzystania z implementacji ITraceWriter . Można to zrobić za pośrednictwem obiektu HttpConfiguration , jak pokazano w poniższym kodzie:

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

Tylko jeden składnik zapisywania śledzenia może być aktywny. Domyślnie internetowy interfejs API ustawia ślad "no-op", który nic nie robi. (Śledzenie "no-op" istnieje, aby kod śledzenia nie musiał sprawdzać, czy składnik zapisywania śledzenia ma wartość null przed zapisaniem śladu).

Jak działa śledzenie internetowego interfejsu API

Śledzenie w internetowym interfejsie API używa wzorca fasady : po włączeniu śledzenia internetowy interfejs API opakowuje różne części potoku żądania przy użyciu klas wykonujących wywołania śledzenia.

Na przykład podczas wybierania kontrolera potok używa interfejsu IHttpControllerSelector . Po włączeniu śledzenia potok wstawia klasę, która implementuje klasę IHttpControllerSelector , ale wywołuje metodę do rzeczywistej implementacji:

Śledzenie internetowego interfejsu API używa wzorca fasady.

Zalety tego projektu obejmują:

Jeśli nie dodasz składnika zapisywania śledzenia, składniki śledzenia nie są tworzone i nie mają wpływu na wydajność.
Jeśli zastąpisz domyślne usługi, takie jak IHttpControllerSelector własną implementacją niestandardową, śledzenie nie ma wpływu, ponieważ śledzenie odbywa się przez obiekt otoki.

Możesz również zastąpić całą strukturę śledzenia internetowego interfejsu API własną strukturą niestandardową, zastępując domyślną usługę ITraceManager :

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

Zaimplementuj ITraceManager.Initialize , aby zainicjować system śledzenia. Należy pamiętać, że zastępuje to całą strukturę śledzenia, w tym cały kod śledzenia wbudowany w internetowy interfejs API.

Udostępnij za pośrednictwem