Protokollieren in .NET Core und ASP.NET CoreLogging in .NET Core and ASP.NET Core

Von Kirk Larkin, Jürgen Gutsch und Rick AndersonBy Kirk Larkin, Juergen Gutsch and Rick Anderson

.NET Core unterstützt eine Protokollierungs-API, die mit einer Vielzahl von integrierten Protokollierungsanbietern und Drittanbieter-Protokollierungslösungen zusammenarbeitet..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Dieser Artikel zeigt, wie Sie die Protokollierungs-API mit integrierten Anbietern verwenden können.This article shows how to use the logging API with built-in providers.

Die meisten der Codebeispiele in diesem Artikel stammen aus ASP.NET Core-Apps.Most of the code examples shown in this article are from ASP.NET Core apps. Die auf die Protokollierung bezogenen Teile dieser Codeausschnitte gelten für jede .NET Core-App, die den generischen Host verwendet.The logging-specific parts of these code snippets apply to any .NET Core app that uses the Generic Host. Die ASP.NET Core Web-App-Vorlagen verwenden den generischen Host.The ASP.NET Core web app templates use the Generic Host.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

ProtokollierungsanbieterLogging providers

Protokollierungsanbieter speichern Protokolle, mit Ausnahme des Console-Anbieters, der Protokolle anzeigt.Logging providers store logs, except for the Console provider which displays logs. Beispielsweise speichert der Azure Application Insights-Anbieter Protokolle in Azure Application Insights.For example, the Azure Application Insights provider stores logs in Azure Application Insights. Es können mehrere Anbieter aktiviert werden.Multiple providers can be enabled.

Für die ASP.NET Core-Web-App-Standardvorlagen gilt Folgendes:The default ASP.NET Core web app templates:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Der vorstehende Code zeigt die Program-Klasse, die mit den ASP.NET Core-Web-App-Vorlagen erstellt wurde.The preceding code shows the Program class created with the ASP.NET Core web app templates. In den nächsten Abschnitten finden Sie Beispiele, die auf den ASP.NET Core-Web-App-Vorlagen basieren, die den generischen Host verwenden.The next several sections provide samples based on the ASP.NET Core web app templates, which use the Generic Host. Nicht-Hostkonsolen-Apps werden weiter unten in diesem Dokument erläutert.Non-host console apps are discussed later in this document.

Um den von Host.CreateDefaultBuilder hinzugefügten Standardsatz von Protokollierungsanbietern zu überschreiben, rufen Sie ClearProviders auf und fügen die erforderlichen Protokollierungsanbieter hinzu.To override the default set of logging providers added by Host.CreateDefaultBuilder, call ClearProviders and add the required logging providers. Beispielsweise folgender Code:For example, the following code:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Weitere Anbieter finden Sie unter:For additional providers, see:

Erstellen von ProtokollenCreate logs

Um Protokolle zu erstellen, verwenden Sie ein ILogger<TCategoryName>-Objekt aus der Abhängigkeitsinjektion (DI).To create logs, use an ILogger<TCategoryName> object from dependency injection (DI).

Im Beispiel unten geschieht Folgendes:The following example:

  • Es wird eine Protokollierung (ILogger<AboutModel>) erstellt, die eine Protokollkategorie des vollqualifizierten Namens vom Typ AboutModel verwendet.Creates a logger, ILogger<AboutModel>, which uses a log category of the fully qualified name of the type AboutModel. Die Protokollkategorie ist eine Zeichenfolge, die jedem Protokoll zugeordnet ist.The log category is a string that is associated with each log.
  • Es wird LogInformation aufgerufen, um Protokollierung mit dem Protokolliergrad Information auszuführen.Calls LogInformation to log at the Information level. Der Protokollierungsgrad gibt den Schweregrad des protokollierten Ereignisses an.The Log level indicates the severity of the logged event.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
    public string Message { get; set; }

    public void OnGet()
    {
        Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
        _logger.LogInformation(Message);
    }
}

Grade und Kategorien werden weiter unten in diesem Dokument ausführlicher erläutert.Levels and categories are explained in more detail later in this document.

Weitere Informationen zu Blazor finden Sie unter Erstellen von Protokollen in Blazor und Blazor WebAssembly in diesem Dokument.For information on Blazor, see Create logs in Blazor and Blazor WebAssembly in this document.

Erstellen von Protokollen in „Main“ und „Startup“ zeigt, wie Protokolle in Main und Startup erstellt werden.Create logs in Main and Startup shows how to create logs in Main and Startup.

Konfigurieren der ProtokollierungConfigure logging

Die Konfiguration der Protokollierung wird meistens im Abschnitt Logging von appsettings.{Environment} .json-Dateien angegeben.Logging configuration is commonly provided by the Logging section of appsettings.{Environment}.json files. Die folgende Datei appsettings.Development.json wird von den ASP.NET Core-Web-App-Vorlagen generiert:The following appsettings.Development.json file is generated by the ASP.NET Core web app templates:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Für den oben stehenden JSON-Code gilt:In the preceding JSON:

  • Die Kategorien "Default", "Microsoft" und "Microsoft.Hosting.Lifetime" werden angegeben.The "Default", "Microsoft", and "Microsoft.Hosting.Lifetime" categories are specified.
  • Die Kategorie "Microsoft" gilt für alle Kategorien, die mit "Microsoft" beginnen.The "Microsoft" category applies to all categories that start with "Microsoft". Diese Einstellung gilt z. B. für die Kategorie "Microsoft.AspNetCore.Routing.EndpointMiddleware".For example, this setting applies to the "Microsoft.AspNetCore.Routing.EndpointMiddleware" category.
  • Die Kategorie "Microsoft" protokolliert mit Protokolliergrad Warning oder höher.The "Microsoft" category logs at log level Warning and higher.
  • Die Kategorie "Microsoft.Hosting.Lifetime" ist genauer als die Kategorie "Microsoft", sodass die Kategorie "Microsoft.Hosting.Lifetime" mit dem Protokolliergrad „Information“ oder höher protokolliert.The "Microsoft.Hosting.Lifetime" category is more specific than the "Microsoft" category, so the "Microsoft.Hosting.Lifetime" category logs at log level "Information" and higher.
  • Ein bestimmter Protokollanbieter wird nicht angegeben, sodass LogLevel für alle aktivierten Protokollanbieter mit Ausnahme von Windows EventLog gilt.A specific log provider is not specified, so LogLevel applies to all the enabled logging providers except for the Windows EventLog.

Die Logging-Eigenschaft kann LogLevel und Protokollanbietereigenschaften beinhalten.The Logging property can have LogLevel and log provider properties. LogLevel gibt den Mindestgrad an, der für ausgewählte Kategorien protokolliert werden soll.The LogLevel specifies the minimum level to log for selected categories. Im JSON-Code oben werden die Protokolliergrade Information und Warning angegeben.In the preceding JSON, Information and Warning log levels are specified. LogLevel gibt den Schweregrad des Protokolls an und liegt zwischen 0 und 6:LogLevel indicates the severity of the log and ranges from 0 to 6:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 und None = 6.Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5, and None = 6.

Wenn LogLevel angegeben wird, wird Protokollierung für Meldungen mit dem angegebenen Protokolliergrad oder höher aktiviert.When a LogLevel is specified, logging is enabled for messages at the specified level and higher. Im JSON-Code oben wird die Kategorie Default für Information oder höher protokolliert.In the preceding JSON, the Default category is logged for Information and higher. Beispielsweise werden Information-, Warning-, Error- und Critical-Meldungen protokolliert.For example, Information, Warning, Error, and Critical messages are logged. Wenn kein LogLevel angegeben wird, wird Protokollierung standardmäßig mit dem Protokolliergrad Information verwendet.If no LogLevel is specified, logging defaults to the Information level. Weitere Informationen finden Sie unter Protokolliergrade.For more information, see Log levels.

Eine Anbietereigenschaft kann eine LogLevel-Eigenschaft angeben.A provider property can specify a LogLevel property. LogLevel unter einem Anbieter gibt die Protokolliergrade an, die für diesen Anbieter protokolliert werden sollen, und überschreibt die Nicht-Anbieterprotokolleinstellungen.LogLevel under a provider specifies levels to log for that provider, and overrides the non-provider log settings. Sehen Sie sich die nachfolgende Datei appsettings.json an:Consider the following appsettings.json file:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Die Einstellungen in Logging.{providername}.LogLevel überschreiben die Einstellungen in Logging.LogLevel.Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. Im JSON-Code oben wird der Standardprotokolliergrad Debug des Anbieters auf Information festgelegt:In the preceding JSON, the Debug provider's default log level is set to Information:

Logging:Debug:LogLevel:Default:Information

Die Einstellung oben gibt den Protokolliergrad Information für jede Logging:Debug:-Kategorie mit Ausnahme von Microsoft.Hosting an.The preceding setting specifies the Information log level for every Logging:Debug: category except Microsoft.Hosting. Wenn eine bestimmte Kategorie aufgelistet wird, überschreibt die jeweilige Kategorie die Standardkategorie.When a specific category is listed, the specific category overrides the default category. Im JSON-Code oben überschreiben die Logging:Debug:LogLevel-Kategorien "Microsoft.Hosting" und "Default" die Einstellungen in Logging:LogLevel.In the preceding JSON, the Logging:Debug:LogLevel categories "Microsoft.Hosting" and "Default" override the settings in Logging:LogLevel

Der Mindestprotokolliergrad kann für Folgendes angegeben werden:The minimum log level can be specified for any of:

  • Bestimmte Anbieter: Beispiel: Logging:EventSource:LogLevel:Default:InformationSpecific providers: For example, Logging:EventSource:LogLevel:Default:Information
  • Bestimmte Kategorien: Beispiel: Logging:LogLevel:Microsoft:WarningSpecific categories: For example, Logging:LogLevel:Microsoft:Warning
  • Alle Anbieter und alle Kategorien: Logging:LogLevel:Default:WarningAll providers and all categories: Logging:LogLevel:Default:Warning

Alle Protokolle unterhalb des Mindestprotokolliergrads werden nicht:Any logs below the minimum level are not:

  • An den Anbieter übergeben.Passed to the provider.
  • Protokolliert oder angezeigt.Logged or displayed.

Um alle Protokolle zu unterdrücken, geben Sie LogLevel.None an.To suppress all logs, specify LogLevel.None. LogLevel.None hat den Wert 6, der höher als LogLevel.Critical (5) ist.LogLevel.None has a value of 6, which is higher than LogLevel.Critical (5).

Wenn ein Anbieter Protokollbereiche unterstützt, gibt IncludeScopes an, ob sie aktiviert sind.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Weitere Informationen finden Sie unter Protokollierbereiche.For more information, see log scopes

Die folgende Datei appsettings.json enthält alle Anbieter, die standardmäßig aktiviert sind:The following appsettings.json file contains all the providers enabled by default:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Im vorgehenden Beispiel:In the preceding sample:

  • Die Kategorien und Protokolliergrade sind keine vorgeschlagenen Werte.The categories and levels are not suggested values. Das Beispiel wird bereitgestellt, um alle Standardanbieter zu zeigen.The sample is provided to show all the default providers.
  • Die Einstellungen in Logging.{providername}.LogLevel überschreiben die Einstellungen in Logging.LogLevel.Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. Beispielsweise überschreibt der Protokolliergrad in Debug.LogLevel.Default den Protokolliergrad in LogLevel.Default.For example, the level in Debug.LogLevel.Default overrides the level in LogLevel.Default.
  • Jeder Standardanbieteralias wird verwendet.Each default provider alias is used. Jeder Anbieter definiert einen Alias, der in der Konfiguration anstelle des vollqualifizierten Typnamens verwendet werden kann.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Die folgenden Anbieteraliase sind integriert:The built-in providers aliases are:
    • KonsoleConsole
    • DebugDebug
    • EventSourceEventSource
    • EventLogEventLog
    • AzureAppServicesFileAzureAppServicesFile
    • AzureAppServicesBlobAzureAppServicesBlob
    • ApplicationInsightsApplicationInsights

Festlegen des Protokolliergrads über die Befehlszeile, Umgebungsvariablen und andere KonfigurationenSet log level by command line, environment variables, and other configuration

Der Protokolliergrad kann von einem beliebigen Konfigurationsanbieter festgelegt werden.Log level can be set by any of the configuration providers.

Das Trennzeichen : funktioniert nicht auf allen Plattformen mit den hierarchischen Schlüsseln von Umgebungsvariablen.The : separator doesn't work with environment variable hierarchical keys on all platforms. Der doppelte Unterstrich __:__, the double underscore, is:

  • wird auf allen Plattformen unterstützt.Supported by all platforms. Das Trennzeichen : wird beispielsweise nicht von Bash unterstützt, __ hingegen schon.For example, the : separator is not supported by Bash, but __ is.
  • automatisch durch : ersetzt.Automatically replaced by a :

Die folgenden Befehle:The following commands:

  • Legen den Umgebungsschlüssel Logging:LogLevel:Microsoft auf den Wert Information unter Windows fest.Set the environment key Logging:LogLevel:Microsoft to a value of Information on Windows.
  • Testen die Einstellungen, wenn eine App verwendet wird, die mit den ASP.NET Core-Webanwendungsvorlagen erstellt wurde.Test the settings when using an app created with the ASP.NET Core web application templates. Der dotnet run-Befehl muss im Projektverzeichnis nach der Verwendung von set ausgeführt werden.The dotnet run command must be run in the project directory after using set.
set Logging__LogLevel__Microsoft=Information
dotnet run

Die oben gezeigte Umgebungseinstellungen:The preceding environment setting:

  • Werden nur in Prozessen festgelegt, die über das Befehlsfenster gestartet werden, in dem sie festgelegt wurden.Is only set in processes launched from the command window they were set in.
  • Werden nicht von Browsern gelesen, die mit Visual Studio gestartet wurden.Isn't read by browsers launched with Visual Studio.

Mit dem folgenden setx-Befehl werden auch der Umgebungsschlüssel und der Wert unter Windows festgelegt.The following setx command also sets the environment key and value on Windows. Anders als set werden setx-Einstellungen beibehalten.Unlike set, setx settings are persisted. Der Schalter /M legt die Variable in der Systemumgebung fest.The /M switch sets the variable in the system environment. Wenn /M nicht verwendet wird, wird eine Benutzerumgebungsvariable festgelegt.If /M isn't used, a user environment variable is set.

setx Logging__LogLevel__Microsoft=Information /M

Wählen Sie in Azure App Service auf der Seite Einstellungen > Konfiguration die Option Neue Anwendungseinstellung aus.On Azure App Service, select New application setting on the Settings > Configuration page. Anwendungseinstellungen von Azure App Service werden:Azure App Service application settings are:

  • Im Ruhezustand verschlüsselt und über einen verschlüsselten Kanal übermittelt.Encrypted at rest and transmitted over an encrypted channel.
  • Als Umgebungsvariablen verfügbar gemacht.Exposed as environment variables.

Weitere Informationen finden Sie unter Azure-Apps: Überschreiben der App-Konfiguration im Azure-Portal.For more information, see Azure Apps: Override app configuration using the Azure Portal.

Weitere Informationen zum Festlegen von ASP.NET Core-Konfigurationswerten mithilfe von Umgebungsvariablen finden Sie unter Umgebungsvariablen.For more information on setting ASP.NET Core configuration values using environment variables, see environment variables. Informationen zur Verwendung anderer Konfigurationsquellen, einschließlich der Befehlszeile, Azure Key Vault, Azure App Configuration, anderer Dateiformate und mehr finden Sie unter Konfiguration in ASP.NET Core.For information on using other configuration sources, including the command line, Azure Key Vault, Azure App Configuration, other file formats, and more, see Konfiguration in ASP.NET Core.

Anwendung von FilterregelnHow filtering rules are applied

Wenn ein ILogger<TCategoryName>-Objekt erstellt wird, wählt das ILoggerFactory-Objekt eine einzige Regel pro Anbieter aus, die auf diese Protokollierung angewendet wird.When an ILogger<TCategoryName> object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Alle von einer ILogger-Instanz geschriebenen Meldungen werden auf Grundlage der ausgewählten Regeln gefiltert.All messages written by an ILogger instance are filtered based on the selected rules. Aus den verfügbaren Regeln wird die für jeden Anbieter und jedes Kategoriepaar spezifischste Regel ausgewählt.The most specific rule for each provider and category pair is selected from the available rules.

Beim Erstellen von ILogger für eine vorgegebene Kategorie wird für jeden Anbieter der folgende Algorithmus verwendet:The following algorithm is used for each provider when an ILogger is created for a given category:

  • Es werden alle Regeln ausgewählt, die dem Anbieter oder dem zugehörigen Alias entsprechen.Select all rules that match the provider or its alias. Wenn keine Übereinstimmung gefunden wird, werden alle Regeln mit einem leeren Anbieter ausgewählt.If no match is found, select all rules with an empty provider.
  • Aus dem Ergebnis des vorherigen Schritts werden die Regeln mit dem längsten übereinstimmenden Kategoriepräfix ausgewählt.From the result of the preceding step, select rules with longest matching category prefix. Wenn keine Übereinstimmung gefunden wird, werden alle Regeln ohne Angabe einer Kategorie ausgewählt.If no match is found, select all rules that don't specify a category.
  • Wenn mehrere Regeln ausgewählt sind, wird die letzte Regel verwendet.If multiple rules are selected, take the last one.
  • Wenn keine Regel ausgewählt ist, wird MinimumLevel verwendet.If no rules are selected, use MinimumLevel.

Protokollieren der Ausgabe von dotnet run und Visual StudioLogging output from dotnet run and Visual Studio

Protokolle, die mit den Standardprotokollierungsanbietern erstellt werden, werden angezeigt:Logs created with the default logging providers are displayed:

  • In Visual StudioIn Visual Studio
    • Im Ausgabefenster „Debuggen“ beim Debuggen.In the Debug output window when debugging.
    • Im ASP.NET Core Web Server-Fenster.In the ASP.NET Core Web Server window.
  • Im Konsolenfenster, wenn die App mit dotnet run ausgeführt wird.In the console window when the app is run with dotnet run.

Protokolle, die mit „Microsoft“-Kategorien beginnen, stammen aus ASP.NET Core-Frameworkcode.Logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core und Anwendungscode verwenden dieselbe Protokollierungs-API und dieselben Protokollierungsanbieter.ASP.NET Core and application code use the same logging API and providers.

ProtokollkategorieLog category

Wenn ein ILogger-Objekt erstellt wird, wird eine Kategorie angegeben.When an ILogger object is created, a category is specified. Diese Kategorie ist in jeder Protokollmeldung enthalten, die von dieser Instanz von ILogger erstellt wird.That category is included with each log message created by that instance of ILogger. Die Kategoriezeichenfolge ist willkürlich, aber die Konvention besteht darin, den Klassennamen zu verwenden.The category string is arbitrary, but the convention is to use the class name. Beispielsweise kann in einem Controller der Name "TodoApi.Controllers.TodoController" lauten.For example, in a controller the name might be "TodoApi.Controllers.TodoController". Die ASP.NET Core-Web-Apps verwenden ILogger<T> zum automatischen Abrufen einer ILogger-Instanz, die den vollqualifizierten Typnamen von T als Kategorie verwendet:The ASP.NET Core web apps use ILogger<T> to automatically get an ILogger instance that uses the fully qualified type name of T as the category:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Um die Kategorie explizit anzugeben, rufen Sie ILoggerFactory.CreateLogger auf:To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

ILogger<T> entspricht dem Aufruf von CreateLogger mit dem vollqualifizierten Typnamen T.ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

ProtokolliergradLog level

In der folgenden Tabelle werden die LogLevel-Werte, die Erweiterungsmethode Log{LogLevel} und die empfohlene Syntax aufgeführt:The following table lists the LogLevel values, the convenience Log{LogLevel} extension method, and the suggested usage:

LogLevelLogLevel WertValue MethodeMethod BESCHREIBUNGDescription
AblaufverfolgungTrace 00 LogTrace Enthält die ausführlichsten Meldungen.Contain the most detailed messages. Diese Meldungen enthalten möglicherweise sensible App-Daten.These messages may contain sensitive app data. Sie sind standardmäßig deaktiviert und sollten nicht in einer Produktionsumgebung aktiviert werden.These messages are disabled by default and should not be enabled in production.
DebuggenDebug 11 LogDebug Zum Debuggen und für die Entwicklung.For debugging and development. Wegen des großen Volumens in der Produktion mit Vorsicht zu verwenden.Use with caution in production due to the high volume.
InformationInformation 22 LogInformation Verfolgt den allgemeinen Ablauf der App nach.Tracks the general flow of the app. Kann über einen langfristigen Wert verfügen.May have long-term value.
WarnungWarning 33 LogWarning Für ungewöhnliche oder unerwartete Ereignisse.For abnormal or unexpected events. Schließt in der Regel Fehler oder Bedingungen ein, die nicht bewirken, dass die App fehlschlägt.Typically includes errors or conditions that don't cause the app to fail.
FehlerError 44 LogError Für Fehler und Ausnahmen, die nicht behandelt werden können.For errors and exceptions that cannot be handled. Diese Meldungen weisen auf einen Fehler im aktuellen Vorgang oder der aktuellen Anforderung und nicht auf einen anwendungsweiten Fehler hin.These messages indicate a failure in the current operation or request, not an app-wide failure.
Critical (Kritisch)Critical 55 LogCritical Für Fehler, die sofortige Aufmerksamkeit erfordern.For failures that require immediate attention. Beispiel: Szenarios mit Datenverlust, Speichermangel.Examples: data loss scenarios, out of disk space.
KeineNone 66 Gibt an, dass eine Protokollierungskategorie keine Meldungen schreiben soll.Specifies that a logging category should not write any messages.

In der Tabelle oben wird der LogLevel vom niedrigsten bis zum höchsten Schweregrad aufgelistet.In the previous table, the LogLevel is listed from lowest to highest severity.

Der erste Parameter der Log-Methode (LogLevel) gibt den Schweregrad des Protokolls an.The Log method's first parameter, LogLevel, indicates the severity of the log. Anstatt Log(LogLevel, ...) aufzurufen, rufen die meisten Entwickler die Log{LogLevel}-Erweiterungsmethoden auf.Rather than calling Log(LogLevel, ...), most developers call the Log{LogLevel} extension methods. Die Log{LogLevel}-Erweiterungsmethoden rufen die Log-Methode auf und geben den LogLevel an.The Log{LogLevel} extension methods call the Log method and specify the LogLevel. Beispielsweise sind die folgenden beiden Protokollierungsaufrufe funktionell gleichwertig und generieren das gleiche Protokoll:For example, the following two logging calls are functionally equivalent and produce the same log:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem ist die Ereignis-ID.MyLogEvents.TestItem is the event ID. MyLogEvents ist Teil der Beispiel-App und wird im Abschnitt Log Event ID (Protokollereignis-ID) angezeigt.MyLogEvents is part of the sample app and is displayed in the Log event ID section.

MyDisplayRouteInfo und ToCtxString werden über das NuGet-Paket Rick.Docs.Samples.RouteInfo bereitgestellt.MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. Diese Methoden zeigen Controller-Routeninformationen an.The methods display Controller route information.

Der folgende Code erstellt Information- und Warning-Protokolle:The following code creates Information and Warning logs:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Im Code oben ist der erste Log{LogLevel}-Parameter (MyLogEvents.GetItem) die Protokollereignis-ID.In the preceding code, the first Log{LogLevel} parameter,MyLogEvents.GetItem, is the Log event ID. Der zweite Parameter ist eine Meldungsvorlage mit Platzhaltern für Argumentwerte, die von den verbleibenden Methodenparametern bereitgestellt werden.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Die Methodenparameter werden im Abschnitt „Meldungsvorlage“ weiter unten in diesem Dokument erläutert.The method parameters are explained in the message template section later in this document.

Rufen Sie die entsprechende Log{LogLevel}-Methode auf, um die Menge an Protokollausgabedaten zu steuern, die in ein bestimmtes Speichermedium geschrieben werden.Call the appropriate Log{LogLevel} method to control how much log output is written to a particular storage medium. Zum Beispiel:For example:

  • In einer ProduktionsumgebungIn production:
    • Das Protokollieren mit den Protokolliergraden Trace oder Information verursacht viele detaillierte Protokollmeldungen.Logging at the Trace or Information levels produces a high-volume of detailed log messages. Um die Kosten zu kontrollieren und die Datenspeichergrenzen nicht zu überschreiten, protokollieren Sie Meldungen der Protokolliergrade Trace und Information in einem kostengünstigen Datenspeicher mit hohem Datenvolumen.To control costs and not exceed data storage limits, log Trace and Information level messages to a high-volume, low-cost data store. Erwägen Sie eine Beschränkung von Trace und Information auf bestimmte Kategorien.Consider limiting Trace and Information to specific categories.
    • Bei der Protokollierung mit den Protokolliergraden Warning bis Critical sollten nur wenige Protokollmeldungen generiert werden.Logging at Warning through Critical levels should produce few log messages.
      • Kosten und Speichergrenzwerte stellen in der Regel kein Problem dar.Costs and storage limits usually aren't a concern.
      • Wenige Protokolle ermöglichen eine größere Flexibilität bei der Auswahl von Datenspeichern.Few logs allow more flexibility in data store choices.
  • Bei der Entwicklung:In development:
    • Legen Sie diese Option auf Warning fest.Set to Warning.
    • Fügen Sie bei der Problembehandlung Trace- oder Information-Meldungen hinzu.Add Trace or Information messages when troubleshooting. Um die Ausgabe einzuschränken, legen Sie Trace oder Information nur für die zu untersuchenden Kategorien fest.To limit output, set Trace or Information only for the categories under investigation.

ASP.NET Core schreibt Protokolle für Frameworkereignisse.ASP.NET Core writes logs for framework events. Berücksichtigen Sie z. B. die Protokollausgabe für Folgendes:For example, consider the log output for:

  • Eine Razor Pages-App, die mit den ASP.NET Core-Vorlagen erstellt wurde.A Razor Pages app created with the ASP.NET Core templates.
  • Protokollierung festgelegt auf Logging:Console:LogLevel:Microsoft:InformationLogging set to Logging:Console:LogLevel:Microsoft:Information
  • Navigation Sie zur Seite „Datenschutz“:Navigation to the Privacy page:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

Der folgende JSON-Code legt Logging:Console:LogLevel:Microsoft:Information fest:The following JSON sets Logging:Console:LogLevel:Microsoft:Information:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

Protokollereignis-IDLog event ID

Jedes Protokoll kann eine Ereignis-ID angeben.Each log can specify an event ID. Die Beispiel-App verwendet die MyLogEvents-Klasse zum Definieren von Ereignis-IDs:The sample app uses the MyLogEvents class to define event IDs:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}
[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Eine Ereignis-ID ordnet eine Gruppe von Ereignissen zu.An event ID associates a set of events. Beispielsweise können alle Protokolle, die sich auf die Anzeige einer Liste von Elementen auf einer Seite beziehen, 1001 sein.For example, all logs related to displaying a list of items on a page might be 1001.

Der Protokollierungsanbieter kann die Ereignis-ID in einem ID-Feld, in der Protokollierungsmeldung oder gar nicht speichern.The logging provider may store the event ID in an ID field, in the logging message, or not at all. Der Debuganbieter zeigt keine Ereignis-IDs an.The Debug provider doesn't show event IDs. Der Konsolenanbieter zeigt Ereignis-IDs in Klammern hinter der Kategorie an:The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Einige Protokollierungsanbieter speichern die Ereignis-ID in einem Feld, das das Filtern nach der ID ermöglicht.Some logging providers store the event ID in a field, which allows for filtering on the ID.

ProtokollmeldungsvorlageLog message template

Jede Protokoll-API verwendet eine Meldungsvorlage.Each log API uses a message template. Die Meldungsvorlage kann Platzhalter enthalten, für die Argumente bereitgestellt werden.The message template can contain placeholders for which arguments are provided. Verwenden Sie Namen für die Platzhalter, keine Zahlen.Use names for the placeholders, not numbers.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Die Reihenfolge der Platzhalter – nicht ihre Namen – bestimmt, welche Parameter verwendet werden, um ihre Werte zur Verfügung zu stellen.The order of placeholders, not their names, determines which parameters are used to provide their values. Im folgenden Code befinden sich die Parameternamen in der Meldungsvorlage nicht in der richtigen Reihenfolge:In the following code, the parameter names are out of sequence in the message template:

string p1 = "param1";
string p2 = "param2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

Dieser Code oben erstellt eine Protokollierungsmeldung mit den Parameterwerten in der richtigen Reihenfolge:The preceding code creates a log message with the parameter values in sequence:

Parameter values: param1, param2

Dieser Ansatz ermöglicht es Protokollierungsanbietern, semantische oder strukturierte Protokollierung zu implementieren.This approach allows logging providers to implement semantic or structured logging. Die Argumente selbst (nicht nur die formatierte Meldungsvorlage) werden an das Protokollierungssystem übergeben.The arguments themselves are passed to the logging system, not just the formatted message template. Dies ermöglicht es Protokollierungsanbietern, die Parameterwerte als Felder zu speichern.This enables logging providers to store the parameter values as fields. Sehen Sie sich z. B. die folgende Protokollierungsmethode an:For example, consider the following logger method:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Beispielsweise bei der Protokollierung in Azure Table Storage:For example, when logging to Azure Table Storage:

  • Jede Azure Table-Entität kann über ID- und RequestTime-Eigenschaften verfügen.Each Azure Table entity can have ID and RequestTime properties.
  • Tabellen mit Eigenschaften vereinfachen Abfragen für protokollierte Daten.Tables with properties simplify queries on logged data. Beispielsweise kann eine Abfrage alle Protokolle innerhalb eines bestimmten RequestTime-Bereichs ermitteln, ohne die Zeitangabe aus der Textnachricht analysieren zu müssen.For example, a query can find all logs within a particular RequestTime range without having to parse the time out of the text message.

Protokollieren von AusnahmenLog exceptions

Die Protokollierungsmethoden verfügen über Überladungen, die einen Ausnahmeparameter annehmen:The logger methods have overloads that take an exception parameter:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo und ToCtxString werden über das NuGet-Paket Rick.Docs.Samples.RouteInfo bereitgestellt.MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. Diese Methoden zeigen Controller-Routeninformationen an.The methods display Controller route information.

Ausnahmeprotokollierung ist anbieterspezifisch.Exception logging is provider-specific.

StandardprotokolliergradDefault log level

Wenn der Standardprotokolliergrad nicht festgelegt ist, ist der Standardwert des Standardprotokolliergrads Information.If the default log level is not set, the default log level value is Information.

Betrachten Sie z. B. die folgende Web-App:For example, consider the following web app:

  • Sie wurde mit den ASP.NET-Web-App-Vorlagen erstellt.Created with the ASP.NET web app templates.
  • appsettings.json und appsettings.Development.json wurden gelöscht oder umbenannt.appsettings.json and appsettings.Development.json deleted or renamed.

Mit dem oben beschriebenen Setup generiert die Navigation zur Datenschutz- oder Homepage viele Trace-, Debug- und Information-Meldungen mit Microsoft im Kategorienamen.With the preceding setup, navigating to the privacy or home page produces many Trace, Debug, and Information messages with Microsoft in the category name.

Mit dem folgenden Code wird der Standardprotokolliergrad festgelegt, wenn der Standardprotokolliergrad nicht in der Konfiguration festgelegt ist:The following code sets the default log level when the default log level is not set in configuration:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Im Allgemeinen sollten Standardprotokolliergrads in der Konfiguration und nicht im Code angegeben werden.Generally, log levels should be specified in configuration and not code.

FilterfunktionFilter function

Eine Filterfunktion wird für alle Anbieter und Kategorien aufgerufen, denen keine Regeln durch Konfiguration oder Code zugewiesen sind:A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddFilter((provider, category, logLevel) =>
                {
                    if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Controller")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Microsoft")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else
                    {
                        return false;
                    }
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Der Code oben zeigt Konsolenprotokolle an, wenn die Kategorie Controller oder Microsoft enthält und der Protokolliergrad Information oder höher ist.The preceding code displays console logs when the category contains Controller or Microsoft and the log level is Information or higher.

Im Allgemeinen sollten Standardprotokolliergrads in der Konfiguration und nicht im Code angegeben werden.Generally, log levels should be specified in configuration and not code.

ASP.NET Core- und EF Core-KategorienASP.NET Core and EF Core categories

Die folgende Tabelle enthält einige Kategorien, die von ASP.NET Core und Entity Framework Core verwendet werden, mit Hinweisen zu den Protokollen:The following table contains some categories used by ASP.NET Core and Entity Framework Core, with notes about the logs:

KategorieCategory HinweiseNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore Allgemeine ASP.NET Core-Diagnose.General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection Gibt an, welche Schlüssel in Betracht gezogen, gefunden und verwendet wurden.Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering Hosts sind zulässig.Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting Gibt an, wie lange es bis zum Abschluss von HTTP-Anforderungen gedauert hat und zu welcher Zeit sie gestartet wurden.How long HTTP requests took to complete and what time they started. Gibt an, welche Hostingstartassemblys geladen wurden.Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc MVC und Razor-DiagnoseMVC and Razor diagnostics. Modellbindung, Filterausführung, Ansichtskompilierung, Aktionsauswahl.Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing Gibt Routenabgleichsinformationen an.Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server Start-, Beendigungs- und Keep-Alive-Antworten der Verbindung.Connection start, stop, and keep alive responses. HTTPS-Zertifikatinformationen.HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles Die bereitgestellten Dateien.Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Allgemeine Entity Framework Core-Diagnose.General Entity Framework Core diagnostics. Datenbankaktivität und -konfiguration, Änderungserkennung, Migrationen.Database activity and configuration, change detection, migrations.

Wenn Sie weitere Kategorien im Konsolenfenster anzeigen möchten, legen Sie appsettings.Development.json auf Folgendes fest:To view more categories in the console window, set appsettings.Development.json to the following:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

ProtokollbereicheLog scopes

Ein Bereich kann einen Satz logischer Vorgänge gruppieren.A scope can group a set of logical operations. Diese Gruppierung kann verwendet werden, um an jedes Protokoll, das als Teil einer Gruppe erstellt wird, die gleichen Daten anzufügen.This grouping can be used to attach the same data to each log that's created as part of a set. So kann beispielsweise jedes Protokoll, das im Rahmen der Verarbeitung einer Transaktion erstellt wird, die Transaktions-ID enthalten.For example, every log created as part of processing a transaction can include the transaction ID.

Ein Bereich:A scope:

  • Ist ein IDisposable-Typ, der von der BeginScope-Methode zurückgegeben wird.Is an IDisposable type that's returned by the BeginScope method.
  • Er bleibt bestehen, bis er verworfen wird.Lasts until it's disposed.

Die folgenden Anbieter unterstützen Bereiche:The following providers support scopes:

Verwenden Sie einen Bereich, indem Sie Protokollierungsaufrufe mit einem using-Block umschließen, der als Wrapper verwendet wird:Use a scope by wrapping logger calls in a using block:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;

    using (_logger.BeginScope("using block message"))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Der folgende JSON-Code aktiviert Bereiche für den Konsolenanbieter:The following JSON enables scopes for the console provider:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": true, // Required to use Scopes.
      "LogLevel": {
        "Microsoft": "Warning",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Der folgende Code aktiviert Bereiche für den Konsolenanbieter:The following code enables scopes for the console provider:

Im Allgemeinen sollte Protokollierung in der Konfiguration und nicht im Code angegeben werden.Generally, logging should be specified in configuration and not code.

Integrierte ProtokollierungsanbieterBuilt-in logging providers

ASP.NET Core umfasst die folgenden Protokollierungsanbieter:ASP.NET Core includes the following logging providers:

Informationen zu stdout und zur Debugprotokollierung mit dem ASP.NET Core-Modul finden Sie unter Problembehandlung bei ASP.NET Core in Azure App Service und IIS und ASP.NET Core-Modul.For information on stdout and debug logging with the ASP.NET Core Module, see Problembehandlung bei ASP.NET Core in Azure App Service und IIS and ASP.NET Core-Modul.

KonsoleConsole

Der Console-Anbieter protokolliert die Ausgabe in der Konsole.The Console provider logs output to the console. Weitere Informationen zum Anzeigen von Console-Protokollen in der Entwicklung finden Sie unter Protokollieren der Ausgabe von dotnet run und Visual Studio.For more information on viewing Console logs in development, see Logging output from dotnet run and Visual Studio.

DebugDebug

Der Debug-Anbieter schreibt die Protokollausgabe mithilfe der System.Diagnostics.Debug-Klasse.The Debug provider writes log output by using the System.Diagnostics.Debug class. Aufrufe von System.Diagnostics.Debug.WriteLine schreiben in den Debug-Anbieter.Calls to System.Diagnostics.Debug.WriteLine write to the Debug provider.

Unter Linux ist der Speicherort des Protokolls des Debug-Anbieters abhängig von der Distribution und kann wie folgt lauten:On Linux, the Debug provider log location is distribution-dependent and may be one of the following:

  • /var/log/message/var/log/message
  • /var/log/syslog/var/log/syslog

EreignisquelleEvent Source

Der EventSource-Anbieter schreibt in eine plattformübergreifende Ereignisquelle mit dem Namen Microsoft-Extensions-Logging.The EventSource provider writes to a cross-platform event source with the name Microsoft-Extensions-Logging. Unter Windows verwendet der Anbieter die Ereignisablaufverfolgung für Windows (ETW).On Windows, the provider uses ETW.

dotnet-trace-Tooldotnet trace tooling

Das Tool dotnet-trace ist ein plattformübergreifendes globales Befehlszeilenschnittstellentool zum Sammeln von .NET Core-Ablaufverfolgungen eines ausgeführten Prozesses.The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process. Das Tool sammelt Microsoft.Extensions.Logging.EventSource-Anbieterdaten mithilfe einer LoggingEventSource.The tool collects Microsoft.Extensions.Logging.EventSource provider data using a LoggingEventSource.

Installationsanweisungen finden Sie unter dotnet-trace.See dotnet-trace for installation instructions.

Verwenden Sie das dotnet-trace-Tool, um die Ablaufverfolgung aus einer App zu erfassen:Use the dotnet trace tooling to collect a trace from an app:

  1. Führen Sie die App mit dem Befehl dotnet run aus.Run the app with the dotnet run command.

  2. Bestimmen Sie den Prozessbezeichner der .NET Core-App:Determine the process identifier (PID) of the .NET Core app:

    Suchen Sie den Prozessbezeichner für den Prozess, der den gleichen Namen wie die App-Assembly hat.Find the PID for the process that has the same name as the app's assembly.

  3. Führen Sie den dotnet trace-Befehl aus.Execute the dotnet trace command.

    Allgemeine Befehlssyntax:General command syntax:

    dotnet trace collect -p {PID} 
        --providers Microsoft-Extensions-Logging:{Keyword}:{Event Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Event Level 1};
                {Logger Category 2}:{Event Level 2};
                ...
                {Logger Category N}:{Event Level N}\"
    

    Wenn Sie eine PowerShell-Befehlsshell verwenden, schließen Sie den --providers-Wert in einfache Anführungszeichen (') ein:When using a PowerShell command shell, enclose the --providers value in single quotes ('):

    dotnet trace collect -p {PID} 
        --providers 'Microsoft-Extensions-Logging:{Keyword}:{Event Level}
            :FilterSpecs=\"
                {Logger Category 1}:{Event Level 1};
                {Logger Category 2}:{Event Level 2};
                ...
                {Logger Category N}:{Event Level N}\"'
    

    Auf Plattformen, die nicht unter Windows ausgeführt werden, fügen Sie die -f speedscope-Option hinzu, um das Format der Ablaufverfolgungsdatei der Ausgabe in speedscope zu ändern.On non-Windows platforms, add the -f speedscope option to change the format of the output trace file to speedscope.

    StichwortKeyword BESCHREIBUNGDescription
    11 Protokolliert Metaereignisse über die LoggingEventSource.Log meta events about the LoggingEventSource. Es werden keine Ereignisse von ILogger) protokolliert.Doesn't log events from ILogger).
    22 Aktiviert das Message-Ereignis, wenn ILogger.Log() aufgerufen wird.Turns on the Message event when ILogger.Log() is called. Die Informationen werden in einer programmgesteuerten (nicht formatierten) Weise ausgegeben.Provides information in a programmatic (not formatted) way.
    44 Aktiviert das FormatMessage-Ereignis, wenn ILogger.Log() aufgerufen wird.Turns on the FormatMessage event when ILogger.Log() is called. Gibt die formatierte Zeichenfolgeversion der Informationen an.Provides the formatted string version of the information.
    88 Aktiviert das MessageJson-Ereignis, wenn ILogger.Log() aufgerufen wird.Turns on the MessageJson event when ILogger.Log() is called. Stellt eine JSON-Darstellung der Argumente bereit.Provides a JSON representation of the arguments.
    EreignisgradEvent Level BeschreibungDescription
    00 LogAlways
    11 Critical
    22 Error
    33 Warning
    44 Informational
    55 Verbose

    FilterSpecs-Einträge für {Logger Category} und {Event Level} stellen zusätzliche Protokollfilterbedingungen dar.FilterSpecs entries for {Logger Category} and {Event Level} represent additional log filtering conditions. Trennen Sie die FilterSpecs-Einträge durch ein Semikolon (;).Separate FilterSpecs entries with a semicolon (;).

    Beispiel mit einer Windows-Befehlsshell (keine einfachen Anführungszeichen um den --providers-Wert):Example using a Windows command shell (no single quotes around the --providers value):

    dotnet trace collect -p {PID} --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
    

    Mit dem vorangestellten Komma wird Folgendes aktiviert:The preceding command activates:

    • Die Ereignisquellenprotokollierung zur Erzeugung von formatierten Zeichenfolgen (4) für Fehler (2)The Event Source logger to produce formatted strings (4) for errors (2).
    • Microsoft.AspNetCore.Hosting-Protokollierung auf Informational-Protokollierungsebene (4)Microsoft.AspNetCore.Hosting logging at the Informational logging level (4).
  4. Halten Sie das dotnet-trace-Tool an, indem Sie die EINGABETASTE oder STRG+C drücken.Stop the dotnet trace tooling by pressing the Enter key or Ctrl+C.

    Die Ablaufverfolgung wird mit dem Namen trace.nettrace in dem Ordner gespeichert, in dem der dotnet trace-Befehl ausgeführt wird.The trace is saved with the name trace.nettrace in the folder where the dotnet trace command is executed.

  5. Öffnen Sie die Ablaufverfolgung mit Perfview.Open the trace with Perfview. Öffnen Sie die Datei trace.nettrace, und untersuchen Sie die Ablaufverfolgungsereignisse.Open the trace.nettrace file and explore the trace events.

Wenn die App den Host nicht mit CreateDefaultBuilder erstellt, fügen Sie den Ereignisquellenanbieter zur Protokollierungskonfiguration der App hinzu.If the app doesn't build the host with CreateDefaultBuilder, add the Event Source provider to the app's logging configuration.

Weitere Informationen finden Sie unter:For more information, see:

PerfViewPerfview

Verwenden Sie das PerfView-Hilfsprogramm zum Sammeln und Anzeigen von Protokollen.Use the PerfView utility to collect and view logs. Es gibt andere Tools zur Anzeige von ETW-Protokollen, aber PerfView bietet die besten Ergebnisse bei der Arbeit mit ETW-Ereignissen, die von ASP.NET Core ausgegeben werden.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET Core.

Um PerfView für das Erfassen von Ereignissen zu konfigurieren, die von diesem Anbieter protokolliert wurden, fügen Sie die Zeichenfolge *Microsoft-Extensions-Logging zur Liste Zusätzliche Anbieter hinzu.To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. Vergessen Sie nicht das * am Anfang der Zeichenfolge.Don't miss the * at the start of the string.

Windows-EventLogWindows EventLog

Der EventLog-Anbieter sendet die Protokollausgabe an das Windows-Ereignisprotokoll.The EventLog provider sends log output to the Windows Event Log. Im Gegensatz zu den anderen Anbietern erbt der EventLog-Anbieter nicht die Standardeinstellungen für Nicht-Anbieter.Unlike the other providers, the EventLog provider does not inherit the default non-provider settings. Wenn keine EventLog-Protokolleinstellungen angegeben werden, wird standardmäßig LogLevel.Warning verwendet.If EventLog log settings aren't specified, they default to LogLevel.Warning.

Legen Sie die Protokollierungsebene fest, um Ereignisse, die niedriger als LogLevel.Warning sind, zu protokollieren.To log events lower than LogLevel.Warning, explicitly set the log level. Im folgenden Beispiel wird der Standardprotokolliergrad auf LogLevel.Information festgelegt:The following example sets the Event Log default log level to LogLevel.Information:

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

AddEventLog-Überladungen können EventLogSettings übergeben.AddEventLog overloads can pass in EventLogSettings. Wenn null oder nicht angegeben, werden die folgenden Standardeinstellungen verwendet:If null or not specified, the following default settings are used:

  • LogName: „Anwendung“LogName: "Application"
  • SourceName: „.NET Runtime“SourceName: ".NET Runtime"
  • MachineName: Der Name des lokalen Computers wird verwendet.MachineName: The local machine name is used.

Der folgende Code ändert SourceName aus dem Standardwert ".NET Runtime" in MyLogs:The following code changes the SourceName from the default value of ".NET Runtime" to MyLogs:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddEventLog(eventLogSettings =>
                {
                    eventLogSettings.SourceName = "MyLogs"; 
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Azure App ServiceAzure 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.The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

Das Anbieterpaket ist nicht im freigegebenen Framework enthalten.The provider package isn't included in the shared framework. Zum Verwenden des Anbieters müssen Sie das Anbieterpaket dem Projekt hinzufügen.To use the provider, add the provider package to the project.

Verwenden Sie AzureFileLoggerOptions und AzureBlobLoggerOptions wie im folgenden Beispiel, um die Anbietereinstellungen zu konfigurieren:To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

public class Scopes
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
                .ConfigureServices(serviceCollection => serviceCollection
                    .Configure<AzureFileLoggerOptions>(options =>
                    {
                        options.FileName = "azure-diagnostics-";
                        options.FileSizeLimit = 50 * 1024;
                        options.RetainedFileCountLimit = 5;
                    })
                    .Configure<AzureBlobLoggerOptions>(options =>
                    {
                        options.BlobName = "log.txt";
                    }))
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
    }
}

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.When deployed to Azure App Service, the app uses the settings in the App Service logs section of the App Service page of the 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.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Anwendungsprotokoll (Dateisystem)Application Logging (Filesystem)
  • Anwendungsprotokoll (Blob)Application Logging (Blob)

Der Standardspeicherort für Protokolldateien ist der Ordner D:\home\LogFiles\Application, und der standardmäßige Dateiname lautet diagnostics-yyyymmdd.txt.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. Die Dateigröße ist standardmäßig auf 10 MB beschränkt, und die maximal zulässige Anzahl beibehaltener Dateien lautet 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Der Standardblobname lautet {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Der Anbieter führt nur Protokollierung aus, wenn das Projekt in der Azure-Umgebung ausgeführt wird.This provider only logs when the project runs in the Azure environment.

Azure-ProtokollstreamingAzure log streaming

Azure-Protokollstreaming unterstützt das Anzeigen der Protokollaktivität in Echtzeit:Azure log streaming supports viewing log activity in real time from:

  • App-ServerThe app server
  • WebserverThe web server
  • Ablaufverfolgung für AnforderungsfehlerFailed request tracing

So konfigurieren Sie das Azure-ProtokollstreamingTo configure Azure log streaming:

  • Navigieren Sie von der Portalseite Ihrer App zur Seite App Service-Protokolle.Navigate to the App Service logs page from the app's portal page.
  • Legen Sie Anwendungsprotokollierung (Dateisystem) auf Ein fest.Set Application Logging (Filesystem) to On.
  • Wählen Sie die Protokollierungsebene.Choose the log Level. Diese Einstellung gilt nur für Azure-Protokollstreaming.This setting only applies to Azure log streaming.

Navigieren Sie zur Seite Log Stream (Protokollstream), um Protokolle anzuzeigen.Navigate to the Log Stream page to view logs. Die protokollierten Nachrichten werden mit der ILogger-Schnittstelle protokolliert.The logged messages are logged with the ILogger interface.

Azure Application InsightsAzure Application Insights

Das Microsoft.Extensions.Logging.ApplicationInsights-Anbieterpaket schreibt Protokolle in Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to 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.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Wenn Sie diesen Anbieter verwenden, können Sie Ihre Protokolle mithilfe der Application Insights-Tools abfragen und analysieren.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

Der Protokollierungsanbieter ist als Abhängigkeit von Microsoft.ApplicationInsights.AspNetCore enthalten, d.h. als das Paket, das alle verfügbaren Telemetriedaten für ASP.NET Core bereitstellt.The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. Wenn Sie dieses Paket verwenden, ist nicht erforderlich, das Anbieterpaket zu installieren.If you use this package, you don't have to install the provider package.

Das Microsoft.ApplicationInsights.Web-Paket bezieht sich auf ASP.NET 4.x, nicht auf ASP.NET Core.The Microsoft.ApplicationInsights.Web package is for ASP.NET 4.x, not ASP.NET Core.

Weitere Informationen finden Sie in den folgenden Ressourcen:For more information, see the following resources:

Protokollierungsanbieter von DrittanbieternThird-party logging providers

Protokollierungsframeworks von Drittanbietern aufgeführt, die mit ASP.NET Core funktionieren:Third-party logging frameworks that work with ASP.NET Core:

Einige Drittanbieterframeworks können eine semantische Protokollierung (auch als strukturierte Protokollierung bezeichnet) ausführen.Some third-party frameworks can perform semantic logging, also known as structured logging.

Die Verwendung eines Frameworks von Drittanbietern ist ähnlich wie die Verwendung eines integrierten Anbieters:Using a third-party framework is similar to using one of the built-in providers:

  1. Fügen Sie Ihrem Paket ein NuGet-Paket hinzu.Add a NuGet package to your project.
  2. Rufen Sie eine ILoggerFactory-Erweiterungsmethode auf, die vom Protokollierungsframework bereitgestellt wird.Call an ILoggerFactory extension method provided by the logging framework.

Weitere Informationen finden Sie in der Dokumentation zum jeweiligen Anbieter.For more information, see each provider's documentation. Protokollierungsanbieter von Drittanbietern werden von Microsoft nicht unterstützt.Third-party logging providers aren't supported by Microsoft.

Nicht-Host-Konsolen-AppNon-host console app

Ein Beispiel zum Verwenden des generischen Hosts in einer nicht webbasierten Konsolen-App finden Sie in der Program.cs-Datei der Beispiel-App für Hintergrundaufgaben (Hintergrundtasks mit gehosteten Diensten in ASP.NET Core).For an example of how to use the Generic Host in a non-web console app, see the Program.cs file of the Background Tasks sample app (Hintergrundtasks mit gehosteten Diensten in ASP.NET Core).

Das Protokollieren von Code für Apps ohne generischen Host weicht in Bezug auf das Hinzufügen von Anbietern und das Erstellen von Protokollierungen ab.Logging code for apps without Generic Host differs in the way providers are added and loggers are created.

ProtokollierungsanbieterLogging providers

Rufen Sie in einer Konsolen-App ohne Host die Add{provider name}-Erweiterungsmethode des Anbieters auf, während Sie eine LoggerFactory erstellen:In a non-host console app, call the provider's Add{provider name} extension method while creating a LoggerFactory:

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Erstellen von ProtokollenCreate logs

Verwenden Sie zum Erstellen von Protokollen ein ILogger<TCategoryName>-Objekt.To create logs, use an ILogger<TCategoryName> object. Verwenden Sie LoggerFactory, um ein ILogger-Element zu erstellen.Use the LoggerFactory to create an ILogger.

Im folgenden Beispiel wird eine Protokollierung mit LoggingConsoleApp.Program als Kategorie erstellt.The following example creates a logger with LoggingConsoleApp.Program as the category.

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

In den folgenden ASP.NET Core-Beispielen werden von der Protokollierung Protokolle mit dem Protokolliergrad Information erstellt.In the following ASP.NET CORE examples, the logger is used to create logs with Information as the level. Der Protokollierungsgrad gibt den Schweregrad des protokollierten Ereignisses an.The Log level indicates the severity of the logged event.

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Grade und Kategorien werden in diesem Dokument ausführlicher erläutert.Levels and categories are explained in more detail in this document.

Protokollierung während der HosterstellungLog during host construction

Die Protokollierung während der Hosterstellung wird nicht direkt unterstützt.Logging during host construction isn't directly supported. Es kann jedoch eine separate Protokollierung verwendet werden.However, a separate logger can be used. Im folgenden Beispiel wird eine Serilog-Protokollierung zum Anmelden von CreateHostBuilder verwendet.In the following example, a Serilog logger is used to log in CreateHostBuilder. AddSerilog verwendet die in Log.Logger angegebene statische Konfiguration:AddSerilog uses the static configuration specified in Log.Logger:

using System;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddRazorPages();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {   
                    logging.AddSerilog();
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

Konfigurieren eines Diensts, der von ILogger abhängig istConfigure a service that depends on ILogger

Die Konstruktorinjektion einer Protokollierung in Startup funktioniert in früheren Versionen von ASP.NET Core, da für den Webhost ein separater Abhängigkeitsinjektion-Container erstellt wird.Constructor injection of a logger into Startup works in earlier versions of ASP.NET Core because a separate DI container is created for the Web Host. Weitere Informationen dazu, warum nur ein Container für den generischen Host erstellt wird, erhalten Sie in der Breaking Change-Ankündigung.For information about why only one container is created for the Generic Host, see the breaking change announcement.

Um einen Dienst zu konfigurieren, der von ILogger<T> abhängt, verwenden Sie die Konstruktorinjektion oder stellen eine Factorymethode bereit.To configure a service that depends on ILogger<T>, use constructor injection or provide a factory method. Die Nutzung einer Factorymethode wird nur empfohlen, wenn Sie keine andere Wahl haben.The factory method approach is recommended only if there is no other option. Angenommen, ein Dienst benötigt z. B. eine durch Abhängigkeitsinjektion bereitgestellte ILogger<T>-Instanz:For example, consider a service that needs an ILogger<T> instance provided by DI:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddRazorPages();

    services.AddSingleton<IMyService>((container) =>
    {
        var logger = container.GetRequiredService<ILogger<MyService>>();
        return new MyService() { Logger = logger };
    });
}

Der hervorgehobene Code oben ist eine Func, die ausgeführt wird, wenn der Abhängigkeitsinjektionscontainer erstmals eine Instanz von MyService erstellen muss.The preceding highlighted code is a Func that runs the first time the DI container needs to construct an instance of MyService. Auf diese Weise können Sie auf alle registrierten Dienste zugreifen.You can access any of the registered services in this way.

Erstellen von Protokollen in MainCreate logs in Main

Der folgende Code führt Protokollierung in Main aus, indem nach dem Erstellen des Hosts eine ILogger-Instanz von der Abhängigkeitsinjektion abgerufen wird:The following code logs in Main by getting an ILogger instance from DI after building the host:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Host created.");

    host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Erstellen von Protokollen in der StartklasseCreate logs in Startup

Der folgende Code schreibt Protokolle in Startup.Configure:The following code writes logs in Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env,
                      ILogger<Startup> logger)
{
    if (env.IsDevelopment())
    {
        logger.LogInformation("In Development.");
        app.UseDeveloperExceptionPage();
    }
    else
    {
        logger.LogInformation("Not Development.");
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorPages();
    });
}

Das Schreiben von Protokollen vor Abschluss der Einrichtung des Abhängigkeitsinjektion-Containers in der Startup.ConfigureServices-Methode wird nicht unterstützt:Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not supported:

  • Die Protokollierungsinjektion in den Startup-Konstruktor wird nicht unterstützt.Logger injection into the Startup constructor is not supported.
  • Die Protokollierungsinjektion in die Startup.ConfigureServices-Methodensignatur wird nicht unterstützt.Logger injection into the Startup.ConfigureServices method signature is not supported

Dies Einschränkung ist darauf zurückzuführen, dass die Protokollierung von der Abhängigkeitsinjektion und der Konfiguration abhängt (die wiederum von der Abhängigkeitsinjektion abhängt).The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on DI. Der Abhängigkeitsinjektion-Container wird erst nach Fertigstellung von ConfigureServices eingerichtet.The DI container isn't set up until ConfigureServices finishes.

Informationen zum Konfigurieren eines Diensts, der von ILogger<T> abhängt, oder dazu, warum die Konstruktorinjektion einer Protokollierung in Startup in früheren Versionen funktioniert hat, finden Sie unter Konfigurieren eines Diensts, der von ILogger abhängt.For information on configuring a service that depends on ILogger<T> or why constructor injection of a logger into Startup worked in earlier versions, see Configure a service that depends on ILogger

Keine asynchronen ProtokollierungsmethodenNo asynchronous logger methods

Die Protokollierung sollte so schnell erfolgen, dass sich die Leistungskosten von asynchronem Code nicht lohnen.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Wenn ein Protokollierungsdatenspeicher langsam ist, schreiben Sie nicht direkt in diesen.If a logging data store is slow, don't write to it directly. Erwägen Sie, die Protokollnachrichten zunächst in einen schnellen Speicher zu schreiben und sie dann später in den langsamen Speicher zu verschieben.Consider writing the log messages to a fast store initially, then moving them to the slow store later. Wenn Sie beispielsweise in SQL Server protokollieren, verwenden Sie nicht direkt eine Log-Methode, da die Log-Methoden synchron sind.For example, when logging to SQL Server, don't do so directly in a Log method, since the Log methods are synchronous. Fügen Sie stattdessen die Protokollmeldungen synchron zu einer Warteschlange im Arbeitsspeicher hinzu, und rufen Sie mithilfe eines Hintergrundworkers die Nachrichten aus der Warteschlange ab, um sie dann asynchron per Pushvorgang an SQL Server zu übertragen.Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. Weitere Informationen finden Sie in diesem GitHub-Issue.For more information, see this GitHub issue.

Ändern von Protokolliergraden in einer aktuell ausgeführten AppChange log levels in a running app

Die Protokollierungs-API umfasst kein Szenario zum Ändern der Protokollebene, während eine App ausgeführt wird.The Logging API doesn't include a scenario to change log levels while an app is running. Einige Konfigurationsanbieter können jedoch die Konfiguration erneut laden, was sich unmittelbar auf die Protokollierungskonfiguration auswirkt.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. Beispielsweise lädt der Dateikonfigurationsanbieter die Protokollierungskonfiguration standardmäßig erneut.For example, the File Configuration Provider, reloads logging configuration by default. Wenn die Konfiguration im Code geändert wird, während eine App ausgeführt wird, kann die App IConfigurationRoot.Reload aufrufen, um ihre Protokollierungskonfiguration zu aktualisieren.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

ILogger und ILoggerFactoryILogger and ILoggerFactory

Die ILogger<TCategoryName>- und ILoggerFactory-Schnittstellen und -Implementierungen sind im .NET Core SDK enthalten.The ILogger<TCategoryName> and ILoggerFactory interfaces and implementations are included in the .NET Core SDK. Sie sind auch in den folgenden NuGet-Paketen verfügbar:They are also available in the following NuGet packages:

Anwenden von Protokollfilterregeln in CodeApply log filter rules in code

Die bevorzugte Vorgehensweise zum Festlegen von Protokollfilterregeln ist die Verwendung von Konfiguration.The preferred approach for setting log filter rules is by using Configuration.

Das folgende Beispiel zeigt, wie Filterregeln im Code registriert werden:The following example shows how to register filter rules in code:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
               logging.AddFilter("System", LogLevel.Debug)
                  .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
                  .AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

logging.AddFilter("System", LogLevel.Debug) gibt die System-Kategorie und den Protokolliergrad Debug an.logging.AddFilter("System", LogLevel.Debug) specifies the System category and log level Debug. Der Filter wird auf alle Anbieter angewendet, da kein bestimmter Anbieter konfiguriert wurde.The filter is applied to all providers because a specific provider was not configured.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) gibt Folgendes an:AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) specifies:

  • Den Debug-Protokollanbieter.The Debug logging provider.
  • Der Protokolliergrad Information oder höher.Log level Information and higher.
  • Alle Kategorien, die mit "Microsoft" beginnen.All categories starting with "Microsoft".

Erstellen einer benutzerdefinierten ProtokollierungCreate a custom logger

Fügen Sie einen ILoggerProvider mit einer ILoggerFactory hinzu, um eine benutzerdefinierte Protokollierung hinzuzufügen:To add a custom logger, add an ILoggerProvider with ILoggerFactory:

public void Configure(
    IApplicationBuilder app,
    IWebHostEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory.AddProvider(new CustomLoggerProvider(new CustomLoggerConfiguration()));

ILoggerProvider erstellt mindestens eine ILogger-Instanz.The ILoggerProvider creates one or more ILogger instances. Die ILogger-Instanzen werden vom Framework zum Protokollieren der Informationen verwendet.The ILogger instances are used by the framework to log the information.

Beispielkonfiguration für benutzerdefinierte ProtokollierungSample custom logger configuration

Im Beispiel geschieht Folgendes:The sample:

  • Es ist ein sehr einfaches Beispiel, mit dem die Farbe der Protokollkonsole nach Ereignis-ID und Protokolliergrad festgelegt wird.Is designed to be a very basic sample that sets the color of the log console by event ID and log level. Protokollierungen ändern sich in der Regel nicht anhand der Ereignis-ID und sind nicht spezifisch für den Protokolliergrad.Loggers generally don't change by event ID and are not specific to log level.
  • Es werden unterschiedliche Farbkonsoleneinträge pro Protokolliergrad und Ereignis-ID mithilfe des folgenden Konfigurationstyps erstellt:Creates different color console entries per log level and event ID using the following configuration type:
public class ColorConsoleLoggerConfiguration
{
    public LogLevel LogLevel { get; set; } = LogLevel.Warning;
    public int EventId { get; set; } = 0;
    public ConsoleColor Color { get; set; } = ConsoleColor.Yellow;
}

Der vorangehende Code legt den Standardprotokolliergrad auf Warning und die Farbe auf Yellow fest.The preceding code sets the default level to Warning and the color to Yellow. Wenn die EventId auf 0 festgelegt ist, werden alle Ereignisse protokolliert.If the EventId is set to 0, we will log all events.

Erstellen der benutzerdefinierten ProtokollierungCreate the custom logger

Der Kategoriename der ILogger-Implementierung ist in der Regel die Protokollierungsquelle.The ILogger implementation category name is typically the logging source. Beispielsweise der Typ, in dem die Protokollierung erstellt wird:For example, the type where the logger is created:

public class ColorConsoleLogger : ILogger
{
    private readonly string _name;
    private readonly ColorConsoleLoggerConfiguration _config;

    public ColorConsoleLogger(string name, ColorConsoleLoggerConfiguration config)
    {
        _name = name;
        _config = config;
    }

    public IDisposable BeginScope<TState>(TState state)
    {
        return null;
    }

    public bool IsEnabled(LogLevel logLevel)
    {
        return logLevel == _config.LogLevel;
    }

    public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, 
                        Exception exception, Func<TState, Exception, string> formatter)
    {
        if (!IsEnabled(logLevel))
        {
            return;
        }

        if (_config.EventId == 0 || _config.EventId == eventId.Id)
        {
            var color = Console.ForegroundColor;
            Console.ForegroundColor = _config.Color;
            Console.WriteLine($"{logLevel} - {eventId.Id} " +
                              $"- {_name} - {formatter(state, exception)}");
            Console.ForegroundColor = color;
        }
    }
}

Der vorangehende Code:The preceding code:

  • Erstellt eine Protokollierungsinstanz pro Kategoriename.Creates a logger instance per category name.
  • Überprüft logLevel == _config.LogLevel in IsEnabled, sodass jedes logLevel-Element über eine eindeutige Protokollierung verfügt.Checks logLevel == _config.LogLevel in IsEnabled, so each logLevel has a unique logger. Protokollierungen sollten im Allgemeinen auch für alle höheren Protokolliergrade aktiviert werden:Generally, loggers should also be enabled for all higher log levels:
public bool IsEnabled(LogLevel logLevel)
{
    return logLevel >= _config.LogLevel;
}

Erstellen des benutzerdefinierten LoggerProviderCreate the custom LoggerProvider

LoggerProvider ist die Klasse, mit der die Protokollierungsinstanzen erstellt werden.The LoggerProvider is the class that creates the logger instances. Möglicherweise ist sie nicht erforderlich, um eine Protokollierungsinstanz pro Kategorie zu erstellen. Dies ist jedoch für einige Protokollierungen sinnvoll, etwa für NLog oder log4net.Maybe it is not needed to create a logger instance per category, but this makes sense for some Loggers, like NLog or log4net. Auf diese Weise können Sie bei Bedarf auch verschiedene Protokollierungsausgabeziele pro Kategorie auswählen:Doing this you are also able to choose different logging output targets per category if needed:

public class ColorConsoleLoggerProvider : ILoggerProvider
{
    private readonly ColorConsoleLoggerConfiguration _config;
    private readonly ConcurrentDictionary<string, ColorConsoleLogger> _loggers = new ConcurrentDictionary<string, ColorConsoleLogger>();

    public ColorConsoleLoggerProvider(ColorConsoleLoggerConfiguration config)
    {
        _config = config;
    }

    public ILogger CreateLogger(string categoryName)
    {
        return _loggers.GetOrAdd(categoryName, name => new ColorConsoleLogger(name, _config));
    }

    public void Dispose()
    {
        _loggers.Clear();
    }
}

Im Code oben erstellt CreateLogger eine einzelne Instanz von ColorConsoleLogger pro Kategoriename und speichert sie in ConcurrentDictionary<TKey,TValue>;In the preceding code, CreateLogger creates a single instance of the ColorConsoleLogger per category name and stores it in the ConcurrentDictionary<TKey,TValue>;

Verwendung und Registrierung der benutzerdefinierten ProtokollierungUsage and registration of the custom logger

Registrieren Sie die Protokollierung in Startup.Configure:Register the logger in the Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 
                      ILoggerFactory loggerFactory)
{
    // Default registration.
    loggerFactory.AddProvider(new ColorConsoleLoggerProvider(
                              new ColorConsoleLoggerConfiguration
    {
        LogLevel = LogLevel.Error,
        Color = ConsoleColor.Red
    }));

    // Custom registration with default values.
    loggerFactory.AddColorConsoleLogger();

    // Custom registration with a new configuration instance.
    loggerFactory.AddColorConsoleLogger(new ColorConsoleLoggerConfiguration
    {
        LogLevel = LogLevel.Debug,
        Color = ConsoleColor.Gray
    });

    // Custom registration with a configuration object.
    loggerFactory.AddColorConsoleLogger(c =>
    {
        c.LogLevel = LogLevel.Information;
        c.Color = ConsoleColor.Blue;
    });

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }
    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Geben Sie für den Code oben mindestens eine Erweiterungsmethode für ILoggerFactory an:For the preceding code, provide at least one extension method for the ILoggerFactory:

public static class ColorConsoleLoggerExtensions
{
    public static ILoggerFactory AddColorConsoleLogger(
                                      this ILoggerFactory loggerFactory, 
                                      ColorConsoleLoggerConfiguration config)
    {
        loggerFactory.AddProvider(new ColorConsoleLoggerProvider(config));
        return loggerFactory;
    }
    public static ILoggerFactory AddColorConsoleLogger(
                                      this ILoggerFactory loggerFactory)
    {
        var config = new ColorConsoleLoggerConfiguration();
        return loggerFactory.AddColorConsoleLogger(config);
    }
    public static ILoggerFactory AddColorConsoleLogger(
                                    this ILoggerFactory loggerFactory, 
                                    Action<ColorConsoleLoggerConfiguration> configure)
    {
        var config = new ColorConsoleLoggerConfiguration();
        configure(config);
        return loggerFactory.AddColorConsoleLogger(config);
    }
}

Zusätzliche RessourcenAdditional resources

Von Tom Dykstra und Steve SmithBy Tom Dykstra and Steve Smith

.NET Core unterstützt eine Protokollierungs-API, die mit einer Vielzahl von integrierten Protokollierungsanbietern und Drittanbieter-Protokollierungslösungen zusammenarbeitet..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Dieser Artikel zeigt, wie Sie die Protokollierungs-API mit integrierten Anbietern verwenden können.This article shows how to use the logging API with built-in providers.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

Hinzufügen von AnbieternAdd providers

Ein Protokollierungsanbieter zeigt Protokolle an oder speichert diese.A logging provider displays or stores logs. Beispielsweise zeigt der Konsolenanbieter Protokolle in der Konsole an, und der Azure Application Insights-Anbieter speichert sie in Azure Application Insights.For example, the Console provider displays logs on the console, and the Azure Application Insights provider stores them in Azure Application Insights. Protokolle können durch das Hinzufügen mehrerer Anbieter an mehrere Ziele gesendet werden.Logs can be sent to multiple destinations by adding multiple providers.

Um einen Anbieter hinzuzufügen, rufen Sie die Add{provider name}-Erweiterungsmethode des Anbieters in Program.cs auf:To add a provider, call the provider's Add{provider name} extension method in Program.cs:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            var env = hostingContext.HostingEnvironment;
            config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                  .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                      optional: true, reloadOnChange: true);
            config.AddEnvironmentVariables();
        })
        .ConfigureLogging((hostingContext, logging) =>
        {
            // Requires `using Microsoft.Extensions.Logging;`
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

Der vorstehende Code erfordert Verweise auf Microsoft.Extensions.Logging und Microsoft.Extensions.Configuration.The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration.

Die Standardprojektvorlage ruft die Methode CreateDefaultBuilder auf, die die folgenden Protokollierungsanbieter hinzufügt:The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • KonsoleConsole
  • DebugDebug
  • EventSource (beginnend mit ASP.NET Core 2.2)EventSource (starting in ASP.NET Core 2.2)
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

Bei Verwendung von CreateDefaultBuilder können Sie die Standardanbieter durch Ihre eigene Auswahl ersetzen.If you use CreateDefaultBuilder, you can replace the default providers with your own choices. Rufen Sie ClearProviders auf, und fügen Sie die gewünschten Anbieter hinzu.Call ClearProviders, and add the providers you want.

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Informationen zu den integrierten Protokollierungsanbietern sowie zu Protokollierungsanbietern von Drittanbietern finden Sie weiter unten in diesem Artikel.Learn more about built-in logging providers and third-party logging providers later in the article.

Erstellen von ProtokollenCreate logs

Verwenden Sie zum Erstellen von Protokollen ein ILogger<TCategoryName>-Objekt.To create logs, use an ILogger<TCategoryName> object. Rufen Sie in einer Web-App oder einem gehosteten Dienst einen ILogger aus der Abhängigkeitsinjektion ab.In a web app or hosted service, get an ILogger from dependency injection (DI). Verwenden Sie in Konsolen-Apps ohne Host LoggerFactory, um einen ILogger zu erstellen.In non-host console apps, use the LoggerFactory to create an ILogger.

Im folgenden ASP.NET Core-Beispiel wird eine Protokollierung mit TodoApiSample.Pages.AboutModel als Kategorie erstellt.The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category. Die Protokollkategorie ist eine Zeichenfolge, die jedem Protokoll zugeordnet ist.The log category is a string that is associated with each log. Die von der Abhängigkeitsinjektion bereitgestellte ILogger<T>-Instanz erstellt Protokolle, die den vollqualifizierten Namen vom Typ T als Kategorie aufweisen.The ILogger<T> instance provided by DI creates logs that have the fully qualified name of type T as the category.

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }

In den folgenden Beispielen zu ASP.NET Core und einer Konsolen-App werden von der Protokollierung Protokolle mit dem Protokolliergrad Information erstellt.In the following ASP.NET Core and console app examples, the logger is used to create logs with Information as the level. Der Protokollierungsgrad gibt den Schweregrad des protokollierten Ereignisses an.The Log level indicates the severity of the logged event.

public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}

Grade und Kategorien werden weiter unten in diesem Artikel ausführlicher erläutert.Levels and categories are explained in more detail later in this article.

Erstellen von Protokollen in der StartklasseCreate logs in Startup

Zum Schreiben von Protokollen in der Startup-Klasse schließen Sie einen ILogger-Parameter in die Konstruktorsignatur ein:To write logs in the Startup class, include an ILogger parameter in the constructor signature:

public class Startup
{
    private readonly ILogger _logger;

    public Startup(IConfiguration configuration, ILogger<Startup> logger)
    {
        Configuration = configuration;
        _logger = logger;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        // Add our repository type
        services.AddSingleton<ITodoRepository, TodoRepository>();
        _logger.LogInformation("Added TodoRepository to services");
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            _logger.LogInformation("In Development environment");
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseCookiePolicy();

        app.UseMvc();
    }
}

Erstellen von Protokollen in der Program-KlasseCreate logs in the Program class

Zum Schreiben von Protokollen in der Program-Klasse rufen Sie eine ILogger-Instanz aus DI ab:To write logs in the Program class, get an ILogger instance from DI:

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Die Protokollierung während der Hosterstellung wird nicht direkt unterstützt.Logging during host construction isn't directly supported. Es kann jedoch eine separate Protokollierung verwendet werden.However, a separate logger can be used. Im folgenden Beispiel wird eine Serilog-Protokollierung zum Anmelden von CreateWebHostBuilder verwendet.In the following example, a Serilog logger is used to log in CreateWebHostBuilder. AddSerilog verwendet die in Log.Logger angegebene statische Konfiguration:AddSerilog uses the static configuration specified in Log.Logger:

using System;
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return WebHost.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddMvc();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {
                    logging.AddSerilog();
                })
                .UseStartup<Startup>();
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

Keine asynchronen ProtokollierungsmethodenNo asynchronous logger methods

Die Protokollierung sollte so schnell erfolgen, dass sich die Leistungskosten von asynchronem Code nicht lohnen.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Wenn Ihr Protokollierungsdatenspeicher langsam ist, schreiben Sie nicht direkt in ihn.If your logging data store is slow, don't write to it directly. Erwägen Sie, die Protokollnachrichten zunächst in einen schnellen Speicher zu schreiben und sie dann später in den langsamen Speicher zu verschieben.Consider writing the log messages to a fast store initially, then move them to the slow store later. Wenn Sie beispielsweise in SQL Server protokollieren, möchten Sie dies nicht direkt in einer Log-Methode tun, da die Log-Methoden synchron sind.For example, if you're logging to SQL Server, you don't want to do that directly in a Log method, since the Log methods are synchronous. Fügen Sie stattdessen die Protokollmeldungen synchron zu einer Warteschlange im Arbeitsspeicher hinzu, und rufen Sie mithilfe eines Hintergrundworkers die Nachrichten aus der Warteschlange ab, um sie dann asynchron per Pushvorgang an SQL Server zu übertragen.Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. Weitere Informationen finden Sie in diesem GitHub-Issue.For more information, see this GitHub issue.

KonfigurationConfiguration

Die Konfiguration von Protokollierungsanbietern erfolgt durch mindestens einen Konfigurationsanbieter:Logging provider configuration is provided by one or more configuration providers:

  • Dateiformate (INI, JSON und XML)File formats (INI, JSON, and XML).
  • BefehlszeilenargumentenCommand-line arguments.
  • Umgebungsvariablen.Environment variables.
  • Speicherinterne .NET-ObjekteIn-memory .NET objects.
  • Der unverschlüsselte Speicher von Secret Manager.The unencrypted Secret Manager storage.
  • Ein unverschlüsselter Benutzerspeicher, z.B. Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Benutzerdefinierte Anbieter (installiert oder erstellt).Custom providers (installed or created).

Die Konfiguration der Protokollierung wird meist vom Logging-Abschnitt von Anwendungseinstellungsdateien angegeben.For example, logging configuration is commonly provided by the Logging section of app settings files. Im folgenden Beispiel werden die Inhalte einer herkömmlichen appsettings.Development.json-Datei veranschaulicht:The following example shows the contents of a typical appsettings.Development.json file:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console":
    {
      "IncludeScopes": true
    }
  }
}

Die Logging-Eigenschaft kann den LogLevel und Protokollanbietereigenschaften beinhalten (Konsole wird angezeigt).The Logging property can have LogLevel and log provider properties (Console is shown).

Die LogLevel-Eigenschaft unter Logging gibt den Mindestgrad an, der für ausgewählte Kategorien protokolliert werden soll.The LogLevel property under Logging specifies the minimum level to log for selected categories. Im Beispiel protokollieren die Kategorien System und Microsoft mit dem Grad Information und alle anderen Kategorien mit dem Grad Debug.In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Weitere Eigenschaften unter Logging geben Protokollierungsanbieter an.Other properties under Logging specify logging providers. Das Beispiel bezieht sich auf den Konsolenanbieter.The example is for the Console provider. Wenn ein Anbieter Protokollbereiche unterstützt, gibt IncludeScopes an, ob sie aktiviert sind.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Eine Anbietereigenschaft (z.B. Console im Beispiel) kann auch eine LogLevel-Eigenschaft angeben.A provider property (such as Console in the example) may also specify a LogLevel property. LogLevel unter einem Anbieter gibt die Grade an, die für diesen Anbieter protokolliert werden sollen.LogLevel under a provider specifies levels to log for that provider.

Wenn Grade in Logging.{providername}.LogLevel angegeben werden, überschreiben sie alle Angaben in Logging.LogLevel.If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel. Betrachten Sie beispielsweise den folgenden JSON-Code:For example, consider the following JSON:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

Im JSON-Code oben wird der vorherige Protokolliergrad (Standardprotokolliergrad) durch die Console-Anbietereinstellungen überschrieben.In the preceding JSON, the Console provider settings overrides the preceding (default) log level.

Die Protokollierungs-API umfasst kein Szenario zum Ändern der Protokollebene, während eine App ausgeführt wird.The Logging API doesn't include a scenario to change log levels while an app is running. Einige Konfigurationsanbieter können jedoch die Konfiguration erneut laden, was sich unmittelbar auf die Protokollierungskonfiguration auswirkt.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. Beispielsweise lädt der Dateikonfigurationsanbieter, der durch CreateDefaultBuilder zum Lesen von Einstellungsdateien hinzugefügt wird, die Protokollierungskonfiguration standardmäßig erneut.For example, the File Configuration Provider, which is added by CreateDefaultBuilder to read settings files, reloads logging configuration by default. Wenn die Konfiguration im Code geändert wird, während eine App ausgeführt wird, kann die App IConfigurationRoot.Reload aufrufen, um ihre Protokollierungskonfiguration zu aktualisieren.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

Informationen zur Implementierung von Konfigurationsanbieter finden Sie hier: Konfiguration in ASP.NET Core.For information on implementing configuration providers, see Konfiguration in ASP.NET Core.

Beispiel einer ProtokollierungsausgabeSample logging output

Mit dem im vorherigen Abschnitt gezeigten Beispielcode werden Protokolle in der Konsole angezeigt, wenn die Anwendung über die Befehlszeile ausgeführt wird.With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. Hier ein Beispiel für eine Konsolenausgabe:Here's an example of console output:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 148.889ms 404

Die vorherigen Protokolle wurden generiert, indem eine HTTP Get-Anforderung an die Beispiel-App unter http://localhost:5000/api/todo/0 vorgenommen wurde.The preceding logs were generated by making an HTTP Get request to the sample app at http://localhost:5000/api/todo/0.

Nachfolgend sehen Sie, wie die gleichen Protokolle im Debugfenster angezeigt werden, wenn Sie die Beispiel-App in Visual Studio ausführen:Here's an example of the same logs as they appear in the Debug window when you run the sample app in Visual Studio:

Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET http://localhost:53104/api/todo/0  
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
TodoApi.Controllers.TodoController:Information: Getting item 0
TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404

Die über die ILogger-Aufrufe aus dem vorherigen Abschnitt erstellten Protokolle beginnen mit „TodoApi“.The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi". Protokolle, die mit Microsoft-Kategorien beginnen, stammen aus ASP.NET Core-Frameworkcode.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core und Anwendungscode verwenden dieselbe Protokollierungs-API und dieselben Protokollierungsanbieter.ASP.NET Core and application code are using the same logging API and providers.

In den übrigen Abschnitten dieses Artikels werden einige Details und Optionen für die Protokollierung erläutert.The remainder of this article explains some details and options for logging.

NuGet-PaketeNuGet packages

Die Schnittstellen ILogger und ILoggerFactory befinden sich in Microsoft.Extensions.Logging.Abstractions, ihre Standardimplementierungen sind in Microsoft.Extensions.Logging enthalten.The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

ProtokollkategorieLog category

Wenn ein ILogger-Objekt erstellt wird, wird eine Kategorie für dieses Objekt angegeben.When an ILogger object is created, a category is specified for it. Diese Kategorie ist in jeder Protokollmeldung enthalten, die von dieser Instanz von ILogger erstellt wird.That category is included with each log message created by that instance of ILogger. Die Kategorie kann eine beliebige Zeichenfolge sein, aber die Konvention besteht in der Verwendung des Klassennamens, z.B. „TodoApi.Controllers.TodoController“.The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

Verwenden Sie ILogger<T> zum Abrufen einer ILogger-Instanz, die den vollqualifizierten Typnamen von T als Kategorie verwendet:Use ILogger<T> to get an ILogger instance that uses the fully qualified type name of T as the category:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }

Um die Kategorie explizit anzugeben, rufen Sie ILoggerFactory.CreateLogger auf:To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }

ILogger<T> entspricht dem Aufruf von CreateLogger mit dem vollqualifizierten Typnamen T.ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

ProtokolliergradLog level

Jedes Protokoll gibt einen LogLevel-Wert an.Every log specifies a LogLevel value. Der Protokolliergrad gibt den Schweregrad oder die Wichtigkeit an.The log level indicates the severity or importance. Sie können beispielsweise ein Information-Protokoll schreiben, wenn eine Methode normal endet, und ein Warning-Protokoll, wenn eine Methode den Statuscode 404 Not Found zurückgibt.For example, you might write an Information log when a method ends normally and a Warning log when a method returns a 404 Not Found status code.

Der folgende Code erstellt Information- und Warning-Protokolle:The following code creates Information and Warning logs:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

Im Code oben sind die Parameter MyLogEvents.GetItem und MyLogEvents.GetItemNotFound die Protokollereignis-ID.In the preceding code, the MyLogEvents.GetItem and MyLogEvents.GetItemNotFound parameters are the Log event ID. Der zweite Parameter ist eine Meldungsvorlage mit Platzhaltern für Argumentwerte, die von den verbleibenden Methodenparametern bereitgestellt werden.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Die Methodenparameter werden im Abschnitt „Protokollmeldungsvorlage“ in diesem Artikel erläutert.The method parameters are explained in the Log message template section in this article.

Protokollmethoden, die den Protokolliergrad im Methodennamen enthalten (z.B. LogInformation und LogWarning), sind Erweiterungsmethoden für ILogger.Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. Diese Methoden rufen eine Log-Methode auf, die einen LogLevel-Parameter annimmt.These methods call a Log method that takes a LogLevel parameter. Sie können anstelle eines Aufrufs dieser Erweiterungsmethoden die Log-Methode direkt aufrufen, aber die Syntax ist relativ kompliziert.You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. Weitere Informationen finden Sie unter ILogger und im Quellcode für Protokollierungserweiterungen.For more information, see ILogger and the logger extensions source code.

ASP.NET Core definiert die folgenden Protokolliergrade. Die Reihenfolge reicht vom geringsten bis zum höchsten Schweregrad.ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • Trace = 0Trace = 0

    Protokolliert Informationen, die in der Regel nur für das Debuggen nützlich sind.For information that's typically valuable only for debugging. Diese Meldungen können sensible Anwendungsdaten enthalten und sollten daher nicht in einer Produktionsumgebung aktiviert werden.These messages may contain sensitive application data and so shouldn't be enabled in a production environment. Standardmäßig deaktiviert.Disabled by default.

  • Debug = 1Debug = 1

    Protokolliert Informationen, die bei der Entwicklung und beim Debuggen hilfreich sein können.For information that may be useful in development and debugging. Beispiel: Entering method Configure with flag set to true. Aktivieren Sie Protokolle mit dem Protokolliergrad Debug aufgrund des hohen Protokollaufkommens nur zur Problembehandlung in der Produktion.Example: Entering method Configure with flag set to true. Enable Debug level logs in production only when troubleshooting, due to the high volume of logs.

  • Information = 2Information = 2

    Zur Nachverfolgung des allgemeinen Ablaufs der App.For tracking the general flow of the app. Diese Protokolle haben typischerweise einen langfristigen Nutzen.These logs typically have some long-term value. Ein Beispiel: Request received for path /api/todoExample: Request received for path /api/todo

  • Warning = 3Warning = 3

    Für ungewöhnliche oder unerwartete Ereignisse im App-Verlauf.For abnormal or unexpected events in the app flow. Dazu können Fehler oder andere Bedingungen gehören, die zwar nicht zum Beenden der App führen, aber eventuell untersucht werden müssen.These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Behandelte Ausnahmen sind eine typische Verwendung für den Protokolliergrad Warning.Handled exceptions are a common place to use the Warning log level. Ein Beispiel: FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • Error = 4Error = 4

    Für Fehler und Ausnahmen, die nicht behandelt werden können.For errors and exceptions that cannot be handled. Diese Meldungen weisen auf einen Fehler in der aktuellen Aktivität oder im aktuellen Vorgang (z.B. in der aktuellen HTTP-Anforderung) und nicht auf einen anwendungsweiten Fehler hin.These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. Beispielprotokollmeldung: Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • Critical = 5Critical = 5

    Für Fehler, die sofortige Aufmerksamkeit erfordern.For failures that require immediate attention. Beispiel: Szenarios mit Datenverlust, Speichermangel.Examples: data loss scenarios, out of disk space.

Verwenden Sie den Protokolliergrad, um die Menge an Protokollausgabedaten zu steuern, die in ein bestimmtes Speichermedium geschrieben oder an ein Anzeigefenster ausgegeben werden.Use the log level to control how much log output is written to a particular storage medium or display window. Zum Beispiel:For example:

  • In einer ProduktionsumgebungIn production:
    • Das Protokollieren von Trace über die Information-Ebenen verursacht viele detaillierte Protokollmeldungen.Logging at the Trace through Information levels produces a high-volume of detailed log messages. Protokollieren Sie Trace über Nachrichten auf Information-Ebene in einem kostengünstigen Speicher mit hohem Volumen, um die Kosten zu überwachen und die Grenzwerte des Datenspeichers nicht zu überschreiten.To control costs and not exceed data storage limits, log Trace through Information level messages to a high-volume, low-cost data store.
    • Das Protokollieren von Warning über die Critical-Ebenen verursacht weniger und kürzere Protokollmeldungen.Logging at Warning through Critical levels typically produces fewer, smaller log messages. Daher müssen Sie sich über Kosten- und Speichergrenzwerte keine Sorgen machen und sind bei der Auswahl des Datenspeichers flexibler.Therefore, costs and storage limits usually aren't a concern, which results in greater flexibility of data store choice.
  • Entwicklungsphase:During development:
    • Protokollieren Sie Warning über Critical-Meldungen an der Konsole.Log Warning through Critical messages to the console.
    • Fügen Sie bei der Fehlerbehebung Trace über Information-Meldungen hinzu.Add Trace through Information messages when troubleshooting.

Im Abschnitt Protokollfilterung weiter unten in diesem Artikel wird erläutert, wie Sie steuern, welche Protokolliergrade ein Anbieter verarbeitet.The Log filtering section later in this article explains how to control which log levels a provider handles.

ASP.NET Core schreibt Protokolle für Frameworkereignisse.ASP.NET Core writes logs for framework events. Die zuvor in diesem Artikel gezeigten Protokollbeispiele enthielten Protokolle unterhalb des Protokolliergrads Information, deshalb wurden keine Protokolle des Protokolliergrads Debug oder Trace erstellt.The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Hier ist ein Beispiel für Konsolenprotokolle, die durch Ausführen der Beispiel-App generiert werden, die so konfiguriert ist, dass sie Debug-Protokolle anzeigt:Here's an example of console logs produced by running the sample app configured to show Debug logs:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
      Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result Microsoft.AspNetCore.Mvc.NotFoundResult.
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
      Connection id "0HL6L7NEFF2QD" completed keep alive response.
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 2.7286ms 404

Protokollereignis-IDLog event ID

Jedes Protokoll kann eine Ereignis-ID angeben.Each log can specify an event ID. Die Beispiel-App verwendet hierzu eine lokal definierte LoggingEvents-Klasse:The sample app does this by using a locally defined LoggingEvents class:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public class LoggingEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems = 1001;
    public const int GetItem = 1002;
    public const int InsertItem = 1003;
    public const int UpdateItem = 1004;
    public const int DeleteItem = 1005;

    public const int GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}

Eine Ereignis-ID ordnet eine Gruppe von Ereignissen zu.An event ID associates a set of events. Beispielsweise können alle Protokolle, die sich auf die Anzeige einer Liste von Elementen auf einer Seite beziehen, 1001 sein.For example, all logs related to displaying a list of items on a page might be 1001.

Der Protokollierungsanbieter kann die Ereignis-ID in einem ID-Feld, in der Protokollierungsmeldung oder gar nicht speichern.The logging provider may store the event ID in an ID field, in the logging message, or not at all. Der Debuganbieter zeigt keine Ereignis-IDs an.The Debug provider doesn't show event IDs. Der Konsolenanbieter zeigt Ereignis-IDs in Klammern hinter der Kategorie an:The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoController[1002]
      Getting item invalidid
warn: TodoApi.Controllers.TodoController[4000]
      GetById(invalidid) NOT FOUND

ProtokollmeldungsvorlageLog message template

Jedes Protokoll gibt eine Meldungsvorlage an.Each log specifies a message template. Die Meldungsvorlage kann Platzhalter enthalten, für die Argumente bereitgestellt werden.The message template can contain placeholders for which arguments are provided. Verwenden Sie Namen für die Platzhalter, keine Zahlen.Use names for the placeholders, not numbers.

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

Die Reihenfolge der Platzhalter – nicht ihre Namen – bestimmt, welche Parameter verwendet werden, um ihre Werte zur Verfügung zu stellen.The order of placeholders, not their names, determines which parameters are used to provide their values. Beachten Sie im folgenden Code, dass die Parameternamen in der Meldungsvorlage nicht in der richtigen Reihenfolge vorhanden sind:In the following code, notice that the parameter names are out of sequence in the message template:

string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

Dieser Code erstellt eine Protokollierungsmeldung mit den Parameterwerten in der richtigen Reihenfolge:This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

Das Protokollierungsframework funktioniert auf diese Weise, damit Protokollierungsanbieter semantische Protokollierung, die auch als strukturierte Protokollierung bezeichnet wird, implementieren können.The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. Die Argumente selbst (nicht nur die formatierte Meldungsvorlage) werden an das Protokollierungssystem übergeben.The arguments themselves are passed to the logging system, not just the formatted message template. Diese Informationen ermöglichen es Protokollierungsanbietern, die Parameterwerte als Felder zu speichern.This information enables logging providers to store the parameter values as fields. Nehmen wir zum Beispiel an, dass Aufrufe von Protokollierungsmethoden folgendermaßen aussehen:For example, suppose logger method calls look like this:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Wenn Sie die Protokolle an Azure Table Storage senden, kann jede Azure Table-Entität die Eigenschaften ID und RequestTime aufweisen. Dies vereinfacht die Abfrage von Protokolldaten.If you're sending the logs to Azure Table Storage, each Azure Table entity can have ID and RequestTime properties, which simplifies queries on log data. Eine Abfrage kann alle Protokolle in einem bestimmten RequestTime-Bereich finden, ohne die Uhrzeit aus den Textmeldungen zu analysieren.A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

Protokollieren von AusnahmenLogging exceptions

Die Protokollierungsmethoden umfassen Überladungen, die das Übergeben von Ausnahmen ermöglichen, wie im folgenden Beispiel gezeigt:The logger methods have overloads that let you pass in an exception, as in the following example:

catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({Id}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);

Die verschiedenen Anbieter verarbeiten die Ausnahmeinformationen auf unterschiedliche Weise.Different providers handle the exception information in different ways. Hier sehen Sie ein Beispiel einer Debuganbieterausgabe aus dem obigen Codebeispiel.Here's an example of Debug provider output from the code shown above.

TodoApiSample.Controllers.TodoController: Warning: GetById(55) NOT FOUND

System.Exception: Item not found exception.
   at TodoApiSample.Controllers.TodoController.GetById(String id) in C:\TodoApiSample\Controllers\TodoController.cs:line 226

ProtokollfilterungLog filtering

Sie können einen Mindestprotokolliergrad für einen bestimmten Anbieter und eine bestimmte Kategorie oder für alle Anbieter oder alle Kategorien festlegen.You can specify a minimum log level for a specific provider and category or for all providers or all categories. Alle Protokolle unter dem Mindestgrad werden nicht an diesen Anbieter weitergeleitet, sodass sie nicht angezeigt oder gespeichert werden.Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

Wenn Sie alle Protokolle unterdrücken möchten, geben Sie LogLevel.None als Mindestprotokolliergrad an.To suppress all logs, specify LogLevel.None as the minimum log level. Der ganzzahlige Wert von LogLevel.None lautet 6 und liegt über LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Erstellen von Filterregeln in der KonfigurationCreate filter rules in configuration

Der Projektvorlagencode ruft CreateDefaultBuilder auf, um die Protokollierung für die Konsolen-, Debug- und EventSource-Anbieter (ASP.NET Core 2.2 oder höher) einzurichten.The project template code calls CreateDefaultBuilder to set up logging for the Console, Debug, and EventSource (ASP.NET Core 2.2 or later) providers. Die CreateDefaultBuilder-Methode richtet die Protokollierung ein, um nach der Konfiguration in einem Logging-Abschnitt zu suchen; dies wird weiter oben in diesem Artikel erläutert.The CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as explained earlier in this article.

Die Konfigurationsdaten geben die Mindestprotokolliergrade nach Anbieter und Kategorie an, wie im folgenden Beispiel gezeigt:The configuration data specifies minimum log levels by provider and category, as in the following example:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": false,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Diese JSON-Konfiguration erstellt sechs Filterregeln: eine für den Debuganbieter, vier für den Konsolenanbieter und eine für alle Anbieter.This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. Eine einzelne Regel wird für jeden Anbieter ausgewählt, wenn ein ILogger-Objekt erstellt wird.A single rule is chosen for each provider when an ILogger object is created.

Filterregeln im CodeFilter rules in code

Das folgende Beispiel zeigt, wie Filterregeln im Code registriert werden:The following example shows how to register filter rules in code:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging =>
        logging.AddFilter("System", LogLevel.Debug)
               .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace));

Das zweite AddFilter gibt den Debuganbieter durch Verwendung des zugehörigen Typnamens an.The second AddFilter specifies the Debug provider by using its type name. Das erste AddFilter gilt für alle Anbieter, weil kein Anbietertyp angegeben wird.The first AddFilter applies to all providers because it doesn't specify a provider type.

Anwendung von FilterregelnHow filtering rules are applied

Die Konfigurationsdaten und der in den vorangegangenen Beispielen gezeigte AddFilter-Code erzeugen die in der folgenden Tabelle gezeigten Regeln.The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. Die ersten sechs Regeln stammen aus dem Konfigurationsbeispiel, die letzten zwei Filter stammen aus dem Codebeispiel.The first six come from the configuration example and the last two come from the code example.

AnzahlNumber AnbieterProvider Kategorien beginnend mit...Categories that begin with ... MindestprotokolliergradMinimum log level
11 DebugDebug Alle KategorienAll categories InformationInformation
22 KonsoleConsole Microsoft.AspNetCore.Mvc.Razor.InternalMicrosoft.AspNetCore.Mvc.Razor.Internal WarnungWarning
33 KonsoleConsole Microsoft.AspNetCore.Mvc.Razor.RazorMicrosoft.AspNetCore.Mvc.Razor.Razor DebugDebug
44 KonsoleConsole Microsoft.AspNetCore.Mvc.RazorMicrosoft.AspNetCore.Mvc.Razor FehlerError
55 KonsoleConsole Alle KategorienAll categories InformationInformation
66 Alle AnbieterAll providers Alle KategorienAll categories DebugDebug
77 Alle AnbieterAll providers SystemSystem DebugDebug
88 DebugDebug MicrosoftMicrosoft AblaufverfolgungTrace

Wenn ein ILogger-Objekt erstellt wird, wählt das ILoggerFactory-Objekt eine einzige Regel pro Anbieter aus, die auf diese Protokollierung angewendet wird.When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Alle von einer ILogger-Instanz geschriebenen Meldungen werden auf Grundlage der ausgewählten Regeln gefiltert.All messages written by an ILogger instance are filtered based on the selected rules. Aus den verfügbaren Regeln wird die für jeden Anbieter und jedes Kategoriepaar spezifischste Regel ausgewählt.The most specific rule possible for each provider and category pair is selected from the available rules.

Beim Erstellen von ILogger für eine vorgegebene Kategorie wird für jeden Anbieter der folgende Algorithmus verwendet:The following algorithm is used for each provider when an ILogger is created for a given category:

  • Es werden alle Regeln ausgewählt, die dem Anbieter oder dem zugehörigen Alias entsprechen.Select all rules that match the provider or its alias. Wenn keine Übereinstimmung gefunden wird, werden alle Regeln mit einem leeren Anbieter ausgewählt.If no match is found, select all rules with an empty provider.
  • Aus dem Ergebnis des vorherigen Schritts werden die Regeln mit dem längsten übereinstimmenden Kategoriepräfix ausgewählt.From the result of the preceding step, select rules with longest matching category prefix. Wenn keine Übereinstimmung gefunden wird, werden alle Regeln ohne Angabe einer Kategorie ausgewählt.If no match is found, select all rules that don't specify a category.
  • Wenn mehrere Regeln ausgewählt sind, wird die letzte Regel verwendet.If multiple rules are selected, take the last one.
  • Wenn keine Regel ausgewählt ist, wird MinimumLevel verwendet.If no rules are selected, use MinimumLevel.

Angenommen, Sie erstellen mit der oben aufgeführten Liste mit Regeln ein ILogger-Objekt für die Kategorie „Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine“:With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • Für den Debuganbieter gelten die Regeln 1, 6 und 8.For the Debug provider, rules 1, 6, and 8 apply. Regel 8 ist die spezifischste Regel, deshalb wird diese Regel ausgewählt.Rule 8 is most specific, so that's the one selected.
  • Für den Konsolenanbieter gelten die Regeln 3, 4, 5 und 6.For the Console provider, rules 3, 4, 5, and 6 apply. Regel 3 ist die spezifischste Regel.Rule 3 is most specific.

Die sich ergebende ILogger-Instanz sendet Protokolle mit dem Protokolliergrad Trace und höher an den Debuganbieter.The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Protokolle mit dem Protokolliergrad Debug und höher werden an den Konsolenanbieter gesendet.Logs of Debug level and above are sent to the Console provider.

AnbieteraliaseProvider aliases

Jeder Anbieter definiert einen Alias, der in der Konfiguration anstelle des vollqualifizierten Typnamens verwendet werden kann.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Verwenden Sie für die integrierten Anbieter die folgenden Aliase:For the built-in providers, use the following aliases:

  • KonsoleConsole
  • DebugDebug
  • EventSourceEventSource
  • EventLogEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

StandardmindestprotokolliergradDefault minimum level

Es gibt eine Einstellung für den Mindestprotokolliergrad, die nur dann wirksam wird, wenn für einen bestimmten Anbieter und eine bestimmte Kategorie keine Regeln aus Konfiguration oder Code gelten.There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. Im folgenden Beispiel wird das Festlegen des Mindestprotokolliergrads veranschaulicht:The following example shows how to set the minimum level:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));

Wenn Sie den Mindestprotokolliergrad nicht explizit festlegen, lautet der Standardwert Information, d.h. Protokolle der Ebene Trace und Debug werden ignoriert.If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

FilterfunktionenFilter functions

Eine Filterfunktion wird für alle Anbieter und Kategorien aufgerufen, denen keine Regeln durch Konfiguration oder Code zugewiesen sind.A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. Code in der Funktion verfügt über Zugriff auf den Anbietertyp, die Kategorie und den Protokolliergrad.Code in the function has access to the provider type, category, and log level. Zum Beispiel:For example:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logBuilder =>
    {
        logBuilder.AddFilter((provider, category, logLevel) =>
        {
            if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
                category == "TodoApiSample.Controllers.TodoController")
            {
                return false;
            }
            return true;
        });
    });

Systemkategorien und -protokolliergradeSystem categories and levels

Dies sind einige Kategorien, die vom ASP.NET Core und Entity Framework Core verwendet werden, mit Hinweisen darauf, welche Protokolle von ihnen zu erwarten sind:Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

KategorieCategory HinweiseNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore Allgemeine ASP.NET Core-Diagnose.General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection Gibt an, welche Schlüssel in Betracht gezogen, gefunden und verwendet wurden.Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering Hosts sind zulässig.Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting Gibt an, wie lange es bis zum Abschluss von HTTP-Anforderungen gedauert hat und zu welcher Zeit sie gestartet wurden.How long HTTP requests took to complete and what time they started. Gibt an, welche Hostingstartassemblys geladen wurden.Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc MVC und Razor-DiagnoseMVC and Razor diagnostics. Modellbindung, Filterausführung, Ansichtskompilierung, Aktionsauswahl.Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing Gibt Routenabgleichsinformationen an.Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server Start-, Beendigungs- und Keep-Alive-Antworten der Verbindung.Connection start, stop, and keep alive responses. HTTPS-Zertifikatinformationen.HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles Die bereitgestellten Dateien.Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Allgemeine Entity Framework Core-Diagnose.General Entity Framework Core diagnostics. Datenbankaktivität und -konfiguration, Änderungserkennung, Migrationen.Database activity and configuration, change detection, migrations.

ProtokollbereicheLog scopes

Ein Bereich kann einen Satz logischer Vorgänge gruppieren.A scope can group a set of logical operations. Diese Gruppierung kann verwendet werden, um an jedes Protokoll, das als Teil einer Gruppe erstellt wird, die gleichen Daten anzufügen.This grouping can be used to attach the same data to each log that's created as part of a set. So kann beispielsweise jedes Protokoll, das im Rahmen der Verarbeitung einer Transaktion erstellt wird, die Transaktions-ID enthalten.For example, every log created as part of processing a transaction can include the transaction ID.

Ein Bereich ist ein IDisposable-Typ, der von der BeginScope-Methode zurückgegeben und so lange beibehalten wird, bis er verworfen wird.A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Verwenden Sie einen Bereich, indem Sie Protokollierungsaufrufe mit einem using-Block umschließen, der als Wrapper verwendet wird:Use a scope by wrapping logger calls in a using block:

public IActionResult GetById(string id)
{
    TodoItem item;
    using (_logger.BeginScope("Message attached to logs created in the using block"))
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        item = _todoRepository.Find(id);
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
    }
    return new ObjectResult(item);
}

Der folgende Code aktiviert Bereiche für den Konsolenanbieter:The following code enables scopes for the console provider:

Program.cs:Program.cs:

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

Hinweis

Um die bereichsbasierte Protokollierung zu aktivieren, muss die Konsolenprotokollierungsoption IncludeScopes konfiguriert werden.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Weitere Informationen zur Konfiguration finden Sie im Abschnitt Konfiguration.For information on configuration, see the Configuration section.

Jede Protokollmeldung enthält die bereichsbezogenen Informationen:Each log message includes the scoped information:

info: TodoApiSample.Controllers.TodoController[1002]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      GetById(0) NOT FOUND

Integrierte ProtokollierungsanbieterBuilt-in logging providers

ASP.NET Core wird mit den folgenden Anbietern bereitgestellt:ASP.NET Core ships the following providers:

Weitere Informationen zu „stdout“ und zur Debugprotokollierung mit dem ASP.NET Core-Modul finden Sie unter Problembehandlung bei ASP.NET Core in Azure App Service und IIS und ASP.NET Core-Modul.For information on stdout and debug logging with the ASP.NET Core Module, see Problembehandlung bei ASP.NET Core in Azure App Service und IIS and ASP.NET Core-Modul.

Der KonsolenanbieterConsole provider

Das Anbieterpaket Microsoft.Extensions.Logging.Console sendet eine Protokollausgabe an die Konsole.The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();

Um die Ausgabe der Konsolenprotokollierung anzuzeigen, öffnen Sie eine Eingabeaufforderung im Projektordner und führen den folgenden Befehl aus:To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Der DebuganbieterDebug provider

Beim Anbieterpaket Microsoft.Extensions.Logging.Debug erfolgt die Protokollausgabe unter Verwendung der Klasse System.Diagnostics.Debug (Debug.WriteLine-Methodenaufrufe).The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

Unter Linux werden Protokolle dieses Anbieters in /var/log/message geschrieben.On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();

EreignisquellenanbieterEvent Source provider

Das Microsoft.Extensions.Logging.EventSource-Anbieterpaket schreibt in eine plattformübergreifende Ereignisquelle mit dem Namen Microsoft-Extensions-Logging.The Microsoft.Extensions.Logging.EventSource provider package writes to an Event Source cross-platform with the name Microsoft-Extensions-Logging. Unter Windows verwendet der Anbieter die Ereignisablaufverfolgung für Windows (ETW).On Windows, the provider uses ETW.

logging.AddEventSourceLogger();

Der Ereignisquellenanbieter wird automatisch hinzugefügt, wenn CreateDefaultBuilder zum Erstellen des Hosts aufgerufen wird.The Event Source provider is added automatically when CreateDefaultBuilder is called to build the host.

Verwenden Sie das PerfView-Hilfsprogramm zum Sammeln und Anzeigen von Protokollen.Use the PerfView utility to collect and view logs. Es gibt andere Tools zur Anzeige von ETW-Protokollen, aber PerfView bietet die besten Ergebnisse bei der Arbeit mit ETW-Ereignissen, die von ASP.NET Core ausgegeben werden.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET Core.

Um PerfView für das Erfassen von Ereignissen zu konfigurieren, die von diesem Anbieter protokolliert wurden, fügen Sie die Zeichenfolge *Microsoft-Extensions-Logging zur Liste Zusätzliche Anbieter hinzu.To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (Vergessen Sie nicht das Sternchen am Anfang der Zeichenfolge.)(Don't miss the asterisk at the start of the string.)

Zusätzliche PerfView-Anbieter

Der Windows-EventLog-AnbieterWindows EventLog provider

Das Anbieterpaket Microsoft.Extensions.Logging.EventLog sendet eine Protokollausgabe in das Windows-Ereignisprotokoll.The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();

Mithilfe von AddEventLog-Überladungen können Sie EventLogSettings übergeben.AddEventLog overloads let you pass in EventLogSettings. Wenn null oder nicht angegeben, werden die folgenden Standardeinstellungen verwendet:If null or not specified, the following default settings are used:

  • LogName: „Anwendung“LogName: "Application"
  • SourceName: „.NET Runtime“SourceName: ".NET Runtime"
  • MachineName: Der Name des lokalen Computers wird verwendet.MachineName: The local machine name is used.

Ereignisse werden für die Warnstufe und höher protokolliert.Events are logged for Warning level and higher. Im folgenden Beispiel wird der Standardprotokolliergrad auf LogLevel.Information festgelegt:The following example sets the Event Log default log level to LogLevel.Information:

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

Der TraceSource-AnbieterTraceSource provider

Das Anbieterpaket Microsoft.Extensions.Logging.TraceSource verwendet die TraceSource-Bibliotheken und -Anbieter.The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);

Mithilfe von AddTraceSource-Überladungen können Sie eine Quelloption und einen Listener für die Ablaufverfolgung übergeben.AddTraceSource overloads let you pass in a source switch and a trace listener.

Um diesen Anbieter zu verwenden, muss eine App unter .NET Framework (anstelle von .NET Core) ausgeführt werden.To use this provider, an app has to run on the .NET Framework (rather than .NET Core). Der Anbieter kann Nachrichten an eine Vielzahl von Listenern weiterleiten, z.B. an den in der Beispiel-App verwendeten TextWriterTraceListener.The provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

Der Azure App Service-AnbieterAzure App Service provider

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.The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

logging.AddAzureWebAppDiagnostics();

Dieses Anbieterpaket ist nicht im Microsoft.AspNetCore.App-Metapaket enthalten.The provider package isn't included in the Microsoft.AspNetCore.App metapackage. Wenn Sie Anwendungen für .NET Framework entwickeln oder auf das Microsoft.AspNetCore.App-Metapaket verweisen, fügen Sie das Anbieterpaket dem Projekt hinzu.When targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project.

Eine AddAzureWebAppDiagnostics-Überladung ermöglicht das Übergeben von AzureAppServicesDiagnosticsSettings.An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. Das settings-Objekt kann Standardeinstellungen überschreiben, z.B. die Protokollierungsausgabevorlage, den Blobnamen und die maximale Dateigröße.The settings object can override default settings, such as the logging output template, blob name, and file size limit. (Die Ausgabevorlage ist eine Nachrichtenvorlage, die auf alle Protokolle zusätzlich zu dem angewendet wird, was mit einem ILogger-Methodenaufruf bereitgestellt wird.)(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

Wenn Sie eine Bereitstellung in einer App Service-App durchführen, berücksichtigt die Anwendung die Einstellungen im Abschnitt App Service logs (App Service-Protokolle) auf der Seite App Services im Azure-Portal.When you deploy to an App Service app, the application honors the settings in the App Service logs section of the App Service page of the 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.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Anwendungsprotokoll (Dateisystem)Application Logging (Filesystem)
  • Anwendungsprotokoll (Blob)Application Logging (Blob)

Der Standardspeicherort für Protokolldateien ist der Ordner D:\home\LogFiles\Application, und der standardmäßige Dateiname lautet diagnostics-yyyymmdd.txt.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. Die Dateigröße ist standardmäßig auf 10 MB beschränkt, und die maximal zulässige Anzahl beibehaltener Dateien lautet 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Der Standardblobname lautet {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Der Anbieter funktioniert nur, wenn das Projekt in der Azure-Umgebung ausgeführt wird.The provider only works when the project runs in the Azure environment. Bei einer lokalen Ausführung zeigt er keine Auswirkungen. Der Anbieter schreibt keine Protokolle in lokale Dateien oder den lokalen Entwicklungsspeicher für BLOBs.It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Azure-ProtokollstreamingAzure log streaming

Azure-Protokollstreaming ermöglicht Ihnen eine Echtzeitanzeige der Protokollaktivität für:Azure log streaming lets you view log activity in real time from:

  • App-ServerThe app server
  • WebserverThe web server
  • Ablaufverfolgung für AnforderungsfehlerFailed request tracing

So konfigurieren Sie das Azure-ProtokollstreamingTo configure Azure log streaming:

  • Navigieren Sie von der Portalseite Ihrer App zur Seite App Service-Protokolle.Navigate to the App Service logs page from your app's portal page.
  • Legen Sie Anwendungsprotokollierung (Dateisystem) auf Ein fest.Set Application Logging (Filesystem) to On.
  • Wählen Sie die Protokollierungsebene.Choose the log Level. Diese Einstellung gilt nur für das Azure-Protokollstreaming, nicht für andere Protokollierungsanbieter in der App.This setting only applies to Azure log streaming, not other logging providers in the app.

Navigieren Sie zur Seite Log Stream (Protokollstream), um App-Meldungen anzuzeigen.Navigate to the Log Stream page to view app messages. Diese werden von der App über die ILogger-Schnittstelle protokolliert.They're logged by the app through the ILogger interface.

Ablaufverfolgungsprotokollierung für Azure Application InsightsAzure Application Insights trace logging

Das Microsoft.Extensions.Logging.ApplicationInsights-Anbieterpaket schreibt Protokolle in Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to 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.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Wenn Sie diesen Anbieter verwenden, können Sie Ihre Protokolle mithilfe der Application Insights-Tools abfragen und analysieren.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

Der Protokollierungsanbieter ist als Abhängigkeit von Microsoft.ApplicationInsights.AspNetCore enthalten, d.h. als das Paket, das alle verfügbaren Telemetriedaten für ASP.NET Core bereitstellt.The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. Wenn Sie dieses Paket verwenden, ist nicht erforderlich, das Anbieterpaket zu installieren.If you use this package, you don't have to install the provider package.

Verwenden Sie nicht das Microsoft.ApplicationInsights.Web-Paket, das für ASP.NET 4.x bestimmt ist.Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

Weitere Informationen finden Sie in den folgenden Ressourcen:For more information, see the following resources:

Protokollierungsanbieter von DrittanbieternThird-party logging providers

Protokollierungsframeworks von Drittanbietern aufgeführt, die mit ASP.NET Core funktionieren:Third-party logging frameworks that work with ASP.NET Core:

Einige Drittanbieterframeworks können eine semantische Protokollierung (auch als strukturierte Protokollierung bezeichnet) ausführen.Some third-party frameworks can perform semantic logging, also known as structured logging.

Die Verwendung eines Frameworks von Drittanbietern ist ähnlich wie die Verwendung eines integrierten Anbieters:Using a third-party framework is similar to using one of the built-in providers:

  1. Fügen Sie Ihrem Paket ein NuGet-Paket hinzu.Add a NuGet package to your project.
  2. Rufen Sie eine ILoggerFactory-Erweiterungsmethode auf, die vom Protokollierungsframework bereitgestellt wird.Call an ILoggerFactory extension method provided by the logging framework.

Weitere Informationen finden Sie in der Dokumentation zum jeweiligen Anbieter.For more information, see each provider's documentation. Protokollierungsanbieter von Drittanbietern werden von Microsoft nicht unterstützt.Third-party logging providers aren't supported by Microsoft.

Zusätzliche RessourcenAdditional resources