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

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.

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. 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. Codebeispiele ohne Host finden sich in diesen Abschnitten des Artikels.Non-host code examples are shown in those sections of the article.

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 in einer App hinzuzufügen, die den generischen Host verwendet, rufen Sie die Add{provider name}-Erweiterungsmethode des Anbieters in Program.cs auf:To add a provider in an app that uses Generic Host, call the provider's Add{provider name} extension method in Program.cs:

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

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

LoggerFactory und AddConsole erfordern eine using-Anweisung für Microsoft.Extensions.Logging.LoggerFactory and AddConsole require a using statement for Microsoft.Extensions.Logging.

Die ASP.NET-Standardprojektvorlagen rufen die Methode CreateDefaultBuilder auf, die die folgenden Protokollierungsanbieter hinzufügt:The default ASP.NET Core project templates call CreateDefaultBuilder, which adds the following logging providers:

Sie können die Standardanbieter durch Ihre eigene Auswahl ersetzen.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 IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

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

Im folgenden Beispiel einer Konsolen-App ohne Host wird eine Protokollierung mit LoggingConsoleApp.Program als Kategorie erstellt.The following non-host console app example creates a logger with LoggingConsoleApp.Program as the category.

class Program
{
    static void Main(string[] args)
    {
        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 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);
}
class Program
{
    static void Main(string[] args)
    {
        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 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 Program-KlasseCreate logs in the Program class

Wenn Protokolle in die Program-Klasse einer ASP.NET Core-App geschrieben werden sollen, rufen Sie nach dem Erstellen des Hosts eine ILogger-Instanz aus der Abhängigkeitsinjektion ab:To write logs in the Program class of an ASP.NET Core app, get an ILogger instance from DI after building the host:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(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.");

    IMyService myService = host.Services.GetRequiredService<IMyService>();
    myService.WriteLog("Logged from MyService.");

    host.Run();
}

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

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

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

Wenn Protokolle in die Startup.Configure-Methode einer ASP.NET Core-App geschrieben werden sollen, schließen Sie einen ILogger-Parameter in die Methodensignatur ein:To write logs in the Startup.Configure method of an ASP.NET Core app, include an ILogger parameter in the method signature:

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

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

    app.UseRouting();

    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.

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.

Wenn Sie einen Dienst konfigurieren müssen, der von ILogger<T> abhängt, können Sie dies immer noch mithilfe der Konstruktorinjektion oder durch Bereitstellen einer Factorymethode ausführen.If you need to configure a service that depends on ILogger<T>, you can still do that by using constructor injection or by providing 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, Sie müssen eine Eigenschaft mit einem Dienst aus der Abhängigkeitsinjektion füllen:For example, suppose you need to fill a property with a service from 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 };
    });

    services.AddSingleton<ITodoRepository, TodoRepository>();
}

Der hervorgehobene Code oben ist eine Func, die ausgeführt wird, wenn der Abhängigkeitsinjektion-Container 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 BlazorCreate logs in Blazor

Blazor WebAssemblyBlazor WebAssembly

Konfigurieren Sie Protokollierung in Blazor-WebAssembly-Apps mit der WebAssemblyHostBuilder.Logging-Eigenschaft in Program.Main:Configure logging in Blazor WebAssembly apps with the WebAssemblyHostBuilder.Logging property in Program.Main:

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;

...

var builder = WebAssemblyHostBuilder.CreateDefault(args);

builder.Logging.SetMinimumLevel(LogLevel.Debug);
builder.Logging.AddProvider(new CustomLoggingProvider());

Die Logging-Eigenschaft ist vom Typ ILoggingBuilder, deshalb sind alle auf ILoggingBuilder verfügbaren Erweiterungsmethoden auch auf Logging verfügbar.The Logging property is of type ILoggingBuilder, so all of the extension methods available on ILoggingBuilder are also available on Logging.

Protokollieren in Razor-KomponentenLog in Razor components

Protokollierungen beachten die Startkonfiguration der App.Loggers respect app startup configuration.

Die using-Direktive für Microsoft.Extensions.Logging ist erforderlich, um die IntelliSense-Vervollständigungen für APIs zu unterstützen, zum Beispiel LogWarning und LogError.The using directive for Microsoft.Extensions.Logging is required to support Intellisense completions for APIs, such as LogWarning and LogError.

Im folgenden Beispiel wird die Protokollierung mit einer ILogger-Schnittstelle in Razor-Komponenten veranschaulicht.The following example demonstrates logging with an ILogger in Razor components:

@page "/counter"
@using Microsoft.Extensions.Logging;
@inject ILogger<Counter> logger;

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

Im folgenden Beispiel wird die Protokollierung mit einer ILoggerFactory-Schnittstelle in Razor-Komponenten veranschaulicht.The following example demonstrates logging with an ILoggerFactory in Razor components:

@page "/counter"
@using Microsoft.Extensions.Logging;
@inject ILoggerFactory LoggerFactory

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        var logger = LoggerFactory.CreateLogger<Counter>();
        logger.LogWarning("Someone has clicked me!");

        currentCount++;
    }
}

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.

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.Diagnostics[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 84.26180000000001ms 307
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/api/todo/0
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
      Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller TodoApiSample.Controllers.TodoController (TodoApiSample).
info: TodoApiSample.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 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.Diagnostics: Information: Request starting HTTP/2.0 GET https://localhost:44328/api/todo/0  
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executing endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller TodoApiSample.Controllers.TodoController (TodoApiSample).
TodoApiSample.Controllers.TodoController: Information: Getting item 0
TodoApiSample.Controllers.TodoController: Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult: Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Executed action TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in 34.167ms
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executed endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Hosting.Diagnostics: Information: Request finished in 98.41300000000001ms 404

Die über die ILogger-Aufrufe aus dem vorherigen Abschnitt erstellten Protokolle beginnen mit „TodoApiSample“.The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApiSample". 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 ist der erste Parameter die Protokollereignis-ID.In the preceding code, the first parameter 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“ später in diesem Artikel erläutert.The method parameters are explained in the message template section later 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.Mvc.Infrastructure.ControllerActionInvoker[3]
      Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller TodoApiSample.Controllers.TodoController (TodoApiSample).
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of authorization filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of resource filters (in the following order): Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of action filters (in the following order): Microsoft.AspNetCore.Mvc.Filters.ControllerActionFilter (Order: -2147483648), Microsoft.AspNetCore.Mvc.ModelBinding.UnsupportedContentTypeFilter (Order: -3000)
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of exception filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of result filters (in the following order): Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[22]
      Attempting to bind parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[44]
      Attempting to bind parameter 'id' of type 'System.String' using the name 'id' in request data ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[45]
      Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[23]
      Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[26]
      Attempting to validate the bound parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[27]
      Done attempting to validate the bound parameter 'id' of type 'System.String'.
info: TodoApiSample.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[2]
      Executed action TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in 32.690400000000004ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 176.9103ms 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:

.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:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .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:

.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-Diagnose.MVC 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:

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

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.

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.

Installieren Sie das dotnet-trace-Tool mit dem folgenden Befehl:Install the dotnet trace tooling with the following command:

dotnet tool install --global dotnet-trace

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. 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.

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

  3. 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.

  4. 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).
  5. 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.

  6. Ö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.

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 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 Lokaler ComputerMachineName – local machine

Ereignisse werden für die Warnstufe und höher protokolliert.Events are logged for Warning level and higher. Legen Sie die Protokollierungsebene fest, um Ereignisse, die niedriger als Warning sind, zu protokollieren.To log events lower than Warning, explicitly set the log level. Fügen Sie beispielsweise Folgendes zur appsettings.json-Datei hinzu:For example, add the following to the appsettings.json file:

"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();

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 static void Main(string[] args)
{
    var host = CreateHostBuilder(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 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 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

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.

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 ist der erste Parameter die Protokollereignis-ID.In the preceding code, the first parameter 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“ später in diesem Artikel erläutert.The method parameters are explained in the message template section later 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-Diagnose.MVC 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 Lokaler ComputerMachineName – local machine

Ereignisse werden für die Warnstufe und höher protokolliert.Events are logged for Warning level and higher. Legen Sie die Protokollierungsebene fest, um Ereignisse, die niedriger als Warning sind, zu protokollieren.To log events lower than Warning, explicitly set the log level. Fügen Sie beispielsweise Folgendes zur appsettings.json-Datei hinzu:For example, add the following to the appsettings.json file:

"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