Protokollierungsanbieter in .NET

  • Artikel

Protokollierungsanbieter speichern Protokolle, mit Ausnahme des Console-Anbieters, der nur Anzeigeprotokolle als Standardausgabe anzeigt. Beispielsweise speichert der Azure Application Insights-Anbieter Protokolle in Azure Application Insights. Es können mehrere Anbieter aktiviert werden.

Die Standardvorlagen für .NET Worker-Apps:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

Der vorstehende Code zeigt die Program-Klasse, die mit den .NET Worker-App-Vorlagen erstellt wurde. In den nächsten Abschnitten finden Sie Beispiele, die auf den .NET Worker-App-Vorlagen basieren, die den generischen Host verwenden.

Rufen Sie ClearProviders auf und fügen die gewünschten Protokollierungsanbieter hinzu, um den von Host.CreateApplicationBuilder hinzugefügten Standardsatz von Protokollierungsanbietern zu überschreiben. Beispielsweise folgender Code:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddConsole();

Weitere Anbieter finden Sie unter:

Konfigurieren eines Diensts, der von ILogger abhängig ist

Um einen Dienst zu konfigurieren, der von ILogger<T> abhängt, verwenden Sie die Konstruktorinjektion oder stellen eine Factorymethode bereit. Die Nutzung einer Factorymethode wird nur empfohlen, wenn es keine andere Option gibt. Angenommen, ein Dienst benötigt z. B. eine durch Abhängigkeitsinjektion bereitgestellte ILogger<T>-Instanz:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IExampleService>(
    container => new DefaultExampleService
    {
        Logger = container.GetRequiredService<ILogger<IExampleService>>()
    });

Der vorangehende Code ist ein Func<IServiceProvider, IExampleService>, der zum ersten Mal ausgeführt wird, wenn der DI-Container eine Instanz von IExampleService erstellen muss. Auf diese Weise können Sie auf alle registrierten Dienste zugreifen.

Integrierte Protokollierungsanbieter

Microsoft-Erweiterungen enthalten die folgenden Protokollierungsanbieter als Teil der Runtimebibliotheken:

Die folgenden Protokollierungsanbieter werden von Microsoft ausgeliefert, aber nicht als Teil der Runtimebibliotheken. Sie müssen als zusätzliche NuGet-Pakete installiert werden.

Konsole

Der Console-Anbieter protokolliert die Ausgabe in der Konsole.

Debug

Der Debug-Anbieter schreibt die Protokollausgabe mithilfe der System.Diagnostics.Debug-Klasse, insbesondere über die Debug.WriteLine-Methode und nur, wenn der Debugger angefügt ist. Der DebugLoggerProvider erstellt DebugLogger-Instanzen, bei denen es sich um Implementierungen der ILogger-Schnittstelle handelt.

Ereignisquelle

Der EventSource-Anbieter schreibt in eine plattformübergreifende Ereignisquelle mit dem Namen Microsoft-Extensions-Logging. Unter Windows verwendet der Anbieter die Ereignisablaufverfolgung für Windows (ETW).

dotnet-trace-Tool

Das Tool dotnet-trace ist ein plattformübergreifendes globales Befehlszeilenschnittstellentool zum Sammeln von .NET Core-Ablaufverfolgungen eines ausgeführten Prozesses. Das Tool sammelt Microsoft.Extensions.Logging.EventSource-Anbieterdaten mithilfe einer LoggingEventSource.

Installationsanweisungen finden Sie unter dotnet-trace. Ein Diagnosetutorial mit dotnet-trace finden Sie unter Debuggen einer hohen CPU-Auslastung in .NET Core.

Windows-EventLog

Der EventLog-Anbieter sendet die Protokollausgabe an das Windows-Ereignisprotokoll. Im Gegensatz zu den anderen Anbietern erbt der EventLog-Anbieter nicht die Standardeinstellungen für Nicht-Anbieter. Wenn keine EventLog-Protokolleinstellungen angegeben werden, wird LogLevel.Warning verwendet.

Legen Sie die Protokollierungsebene fest, um Ereignisse, die niedriger als LogLevel.Warning sind, zu protokollieren. Im folgenden Beispiel wird der Standardprotokolliergrad auf LogLevel.Information festgelegt:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

AddEventLog-Überladungen können EventLogSettings übergeben. Wenn null oder nicht angegeben, werden die folgenden Standardeinstellungen verwendet:

  • LogName: „Anwendung“
  • SourceName: „.NET Runtime“
  • MachineName: Der Name des lokalen Computers wird verwendet.

Der folgende Code ändert SourceName aus dem Standardwert ".NET Runtime" in CustomLogs:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddEventLog(
    config => config.SourceName = "CustomLogs");

using IHost host = builder.Build();

host.Run();

Azure App Service

Das Anbieterpaket Microsoft.Extensions.Logging.AzureAppServices schreibt Protokolle in Textdateien in das Dateisystem einer Azure App Service-App und in Blob Storage in einem Azure Storage-Konto.

Das Anbieterpaket ist nicht in den Runtimebibliotheken enthalten. Zum Verwenden des Anbieters müssen Sie das Anbieterpaket dem Projekt hinzufügen.

Verwenden Sie AzureFileLoggerOptions und AzureBlobLoggerOptions wie im folgenden Beispiel, um die Anbietereinstellungen zu konfigurieren:

using Microsoft.Extensions.Logging.AzureAppServices;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args)

builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
    options.FileName = "azure-diagnostics-";
    options.FileSizeLimit = 50 * 1024;
    options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
    options.BlobName = "log.txt";
});

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

Wenn eine Bereitstellung in Azure App Service erfolgt, verwendet die App die Einstellungen im Abschnitt App Service logs (App Service-Protokolle) auf der Seite App Service im Azure-Portal. Bei einem Update der folgenden Einstellungen werden die Änderungen sofort wirksam, ohne dass ein Neustart oder eine erneute Bereitstellung der App notwendig ist.

Der Standardspeicherort für Protokolldateien ist der Ordner D:\home\LogFiles\Application. Zusätzliche Standardwerte variieren je nach Anbieter:

  • Anwendungsprotokollierung (Dateisystem): Der Standarddateiname im Dateisystem ist diagnostics-yyyymmdd.txt. Die Dateigröße ist standardmäßig auf 10 MB beschränkt, und die maximal zulässige Anzahl beibehaltener Dateien lautet 2.
  • Anwendungsprotokollierung (Blob): Der Standardblobname lautet {app-name}/yyyy/mm/dd/hh/{guid}_applicationLog.txt.

Der Anbieter führt nur Protokollierung aus, wenn das Projekt in der Azure-Umgebung ausgeführt wird.

Azure-Protokollstreaming

Azure-Protokollstreaming unterstützt das Anzeigen der Protokollaktivität in Echtzeit:

  • App-Server
  • Webserver
  • Ablaufverfolgung für Anforderungsfehler

So konfigurieren Sie das Azure-Protokollstreaming

  • Navigieren Sie von der Portalseite Ihrer App zur Seite App Service-Protokolle.
  • Legen Sie Anwendungsprotokollierung (Dateisystem) auf Ein fest.
  • Wählen Sie die Protokollierungsebene. Diese Einstellung gilt nur für Azure-Protokollstreaming.

Navigieren Sie zur Seite Log Stream (Protokollstream), um Protokolle anzuzeigen. Die protokollierten Nachrichten werden mit der ILogger-Schnittstelle protokolliert.

Azure Application Insights

Das Microsoft.Extensions.Logging.ApplicationInsights-Anbieterpaket schreibt Protokolle in Azure Application Insights. Application Insights ist ein Dienst, der eine Web-App überwacht und Tools für Abfragen und Analysen von Telemetriedaten zur Verfügung stellt. Wenn Sie diesen Anbieter verwenden, können Sie Ihre Protokolle mithilfe der Application Insights-Tools abfragen und analysieren.

Weitere Informationen finden Sie in den folgenden Ressourcen:

Überlegungen zum Entwurf des Protokollierungsanbieters

Wenn Sie planen, Ihre eigene Implementierung der ILoggerProvider-Schnittstelle und eine entsprechende benutzerdefinierte Implementierung von ILogger zu entwickeln, berücksichtigen Sie die folgenden Punkte:

  • Die Methode ILogger.Log ist synchron.
  • Die Lebensdauer des Protokollzustands und der Objekte sollte nicht angenommen werden.

Eine Implementierung von ILoggerProvider erstellt einen ILogger über die zugehörige Methode ILoggerProvider.CreateLogger. Wenn Ihre Implementierung Protokollierungsmeldungen ohne Blockierung in die Warteschlange einreihen soll, sollten die Meldungen zuerst materialisiert werden, oder der Objektzustand, der zum Materialisieren eines Protokolleintrags verwendet wird, sollte serialisiert werden. Dadurch werden potenzielle Ausnahmen von verworfenen Objekten vermieden.

Weitere Informationen hierzu finden Sie unter Implementieren eines benutzerdefinierten Protokollierungsanbieters in .NET.

Protokollierungsanbieter von Drittanbietern

Nachfolgend werden einige Protokollierungsframeworks von Drittanbietern aufgeführt, die mit .NET-Workloads funktionieren:

Einige Drittanbieterframeworks können eine semantische Protokollierung (auch als strukturierte Protokollierung bezeichnet) ausführen.

Die Verwendung eines Frameworks von Drittanbietern ist ähnlich wie die Verwendung eines integrierten Anbieters:

  1. Fügen Sie Ihrem Paket ein NuGet-Paket hinzu.
  2. Rufen Sie eine ILoggerFactory- oder ILoggingBuilder-Erweiterungsmethode auf, die vom Protokollierungsframework bereitgestellt wird.

Weitere Informationen finden Sie in der Dokumentation zum jeweiligen Anbieter. Protokollierungsanbieter von Drittanbietern werden von Microsoft nicht unterstützt.

Siehe auch