Rejestrowanie w programie ASP.NET CoreLogging in ASP.NET Core

Przez Steve Smith i Tom DykstraBy Steve Smith and Tom Dykstra

Platforma ASP.NET Core obsługuje interfejs API rejestrowania, która współdziała z różnych dostawców rejestrowania wbudowanych oraz innych firm.ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. W tym artykule przedstawiono sposób korzystania z interfejsu API rejestrowania za pomocą wbudowanych dostawców.This article shows how to use the logging API with built-in providers.

Wyświetlanie lub pobieranie przykładowego kodu (sposobu pobierania)View or download sample code (how to download)

Dodawanie dostawcyAdd providers

Dostawcy logowania Wyświetla lub są przechowywane dzienniki.A logging provider displays or stores logs. Na przykład konsola dostawca Wyświetla dzienniki konsoli i dostawcy usługi Azure Application Insights przechowuje je w usłudze 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. Dzienniki mogą być wysyłane do wielu miejsc docelowych, dodając wielu dostawców.Logs can be sent to multiple destinations by adding multiple providers.

Aby dodać dostawcę, należy wywołać dostawcy Add{provider name} metody rozszerzenia w Program.cs: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) =>
        {
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

Wywołania szablonu projektu domyślnego CreateDefaultBuilder metodę rozszerzenia, który dodaje następujących dostawców rejestrowania:The default project template calls the CreateDefaultBuilder extension method, which adds the following logging providers:

  • KonsolaConsole
  • DebugowanieDebug
  • EventSource (począwszy od programu ASP.NET Core 2.2)EventSource (starting in ASP.NET Core 2.2)
public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .Build();

Jeśli używasz CreateDefaultBuilder, domyślnych dostawców można zastąpić własnymi wartościami.If you use CreateDefaultBuilder, you can replace the default providers with your own choices. Wywołaj ClearProviders, i dostawców, o których chcesz dodać.Call ClearProviders, and add the providers you want.

public static void Main(string[] args)
{
    var host = BuildWebHost(args);

    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 IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .Build();

Można użyć dostawcy, instalowanie pakietu NuGet i wywołanie metody rozszerzenia dostawcy w wystąpieniu ILoggerFactory:To use a provider, install its NuGet package and call the provider's extension method on an instance of ILoggerFactory:

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole()
        .AddDebug();

Platforma ASP.NET Core wstrzykiwanie zależności (DI) zapewnia ILoggerFactory wystąpienia.ASP.NET Core dependency injection (DI) provides the ILoggerFactory instance. AddConsole i AddDebug metody rozszerzenia są zdefiniowane w Microsoft.Extensions.Logging.Console i Microsoft.Extensions.Logging.Debug pakietów.The AddConsole and AddDebug extension methods are defined in the Microsoft.Extensions.Logging.Console and Microsoft.Extensions.Logging.Debug packages. Każda metoda rozszerzenia wywołuje ILoggerFactory.AddProvider jest metoda w wystąpieniu dostawcy.Each extension method calls the ILoggerFactory.AddProvider method, passing in an instance of the provider.

Uwaga

Przykładową aplikację dodaje rejestrowania dostawców w Startup.Configure metody.The sample app adds logging providers in the Startup.Configure method. Aby uzyskać dane wyjściowe dziennika z kodu, który jest wykonywany wcześniej, należy dodać rejestrowania dostawców w Startup konstruktora klasy.To obtain log output from code that executes earlier, add logging providers in the Startup class constructor.

Dowiedz się więcej o wbudowane funkcje rejestrowania dostawców i rejestrowania innych dostawców w dalszej części artykułu.Learn more about built-in logging providers and third-party logging providers later in the article.

Twórz dziennikiCreate logs

Pobierz ILogger<TCategoryName> obiekt z DI.Get an ILogger<TCategoryName> object from DI.

Poniższy przykład kontrolera tworzy Information i Warning dzienniki.The following controller example creates Information and Warning logs. Kategorii jest TodoApiSample.Controllers.TodoController (w pełni kwalifikowaną nazwę klasy z TodoController w przykładowej aplikacji):The category is TodoApiSample.Controllers.TodoController (the fully qualified class name of TodoController in the sample app):

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

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }
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);
}

W poniższym przykładzie stron Razor utworzy dzienników za pomocą Information jako poziom i TodoApiSample.Pages.AboutModel jako kategorii:The following Razor Pages example creates logs with Information as the level and TodoApiSample.Pages.AboutModel as the category:

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }
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);
}

Poprzedni przykład tworzy dzienniki za pomocą Information i Warning jako poziom i TodoController klasy kategorii.The preceding example creates logs with Information and Warning as the level and TodoController class as the category.

Dziennik poziom wskazuje ważność rejestrowane zdarzenia.The Log level indicates the severity of the logged event. Dziennik kategorii jest ciągiem, który jest skojarzony z każdym dzienniku.The log category is a string that is associated with each log. ILogger<T> Wystąpienie tworzy dzienniki, które mają w pełni kwalifikowaną nazwę typu T kategorię.The ILogger<T> instance creates logs that have the fully qualified name of type T as the category. Poziomy i kategorie omówiona bardziej szczegółowo w dalszej części tego artykułu.Levels and categories are explained in more detail later in this article.

Twórz dzienniki przy uruchamianiuCreate logs in Startup

Zapisywanie dzienników Startup klasy, należy umieścić ILogger parametru w sygnatury konstruktora: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();

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

Twórz dzienniki w programieCreate logs in Program

Zapisywanie dzienników Program klasy, Uzyskaj ILogger wystąpienia DI:To write logs in the Program class, get an ILogger instance from DI:

public static void Main(string[] args)
{
    var host = BuildWebHost(args);

    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 IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .Build();

Nie metody asynchronicznej rejestratoraNo asynchronous logger methods

Rejestrowanie powinno być tak szybko, że nie jest wart spadek wydajności kodu asynchronicznego.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Jeśli magazyn danych rejestrowania jest powolne, nie zapisanie w nim bezpośrednio.If your logging data store is slow, don't write to it directly. Należy wziąć pod uwagę początkowo zapisywanie komunikatów dziennika do szybkiego magazynu, a następnie przenieść je do magazynu powolne później.Consider writing the log messages to a fast store initially, then move them to the slow store later. Na przykład Zaloguj się do kolejki komunikatów, która ma odczytu utrwalana w magazynie powolne przez inny proces.For example, log to a message queue that's read and persisted to slow storage by another process.

KonfiguracjaConfiguration

Rejestrowanie dostawcy konfiguracji jest dostarczane przez przynajmniej jednego dostawcy konfiguracji:Logging provider configuration is provided by one or more configuration providers:

  • Formaty plików (INI, JSON i XML).File formats (INI, JSON, and XML).
  • Argumenty wiersza polecenia.Command-line arguments.
  • Zmienne środowiskowe.Environment variables.
  • Obiekty .NET w pamięci.In-memory .NET objects.
  • Niezaszyfrowane Menedżera klucz tajny magazynu.The unencrypted Secret Manager storage.
  • Użytkownik zaszyfrowanych przechowywanych informacji, takich jak usługi Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Dostawcy niestandardowi (zainstalowane lub utworzone).Custom providers (installed or created).

Na przykład konfiguracja rejestrowania są często dostarczane przez Logging części plików ustawień aplikacji.For example, logging configuration is commonly provided by the Logging section of app settings files. W poniższym przykładzie pokazano zawartość typowej appsettings. Development.JSON pliku:The following example shows the contents of a typical appsettings.Development.json file:

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

Logging Właściwość może mieć LogLevel dziennika właściwości dostawcy (konsoli znajduje się) i innych źródeł.The Logging property can have LogLevel and log provider properties (Console is shown).

LogLevel Właściwości Logging Określa minimalny poziom logowania dla wybranych kategorii.The LogLevel property under Logging specifies the minimum level to log for selected categories. W tym przykładzie System i Microsoft kategorie dziennika na Information poziom, a wszystkie pozostałe rejestrowania Debug poziom.In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Inne właściwości w obszarze Logging Określ rejestrowania dostawców.Other properties under Logging specify logging providers. W przykładzie występuje dla dostawcy konsoli.The example is for the Console provider. Jeśli dostawca obsługuje dziennika zakresy, IncludeScopes wskazuje, czy są włączone.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Właściwość dostawcy (takich jak Console w przykładzie) mogą także określić LogLevel właściwości.A provider property (such as Console in the example) may also specify a LogLevel property. LogLevel w obszarze dostawcy określa poziomy dziennika dla tego dostawcy.LogLevel under a provider specifies levels to log for that provider.

Jeśli nie określono poziomy w Logging.{providername}.LogLevel, że zastępują one nic w Logging.LogLevel.If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel.

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

LogLevel klucze reprezentują nazwy dziennika.LogLevel keys represent log names. Default Klucz ma zastosowanie do dzienników, które nie zostały jawnie wymienione.The Default key applies to logs not explicitly listed. Reprezentuje wartość poziom dziennika stosowane do danego dziennika.The value represents the log level applied to the given log.

Aby uzyskać informacje dotyczące implementowania dostawcy konfiguracji, zobacz Konfiguracja w programie ASP.NET Core.For information on implementing configuration providers, see Konfiguracja w programie ASP.NET Core.

Przykładowe dane wyjściowe z rejestrowaniaSample logging output

Za pomocą przykładowego kodu pokazano w poprzedniej sekcji dzienniki są wyświetlane w konsoli, gdy aplikacja jest uruchamiana z poziomu wiersza polecenia.With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. Oto przykład danych wyjściowych konsoli: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

Poprzedni dzienniki wygenerowane przez wysłał żądanie HTTP Get do przykładowej aplikacji pod http://localhost:5000/api/todo/0.The preceding logs were generated by making an HTTP Get request to the sample app at http://localhost:5000/api/todo/0.

Oto przykład tego samego dzienników, w jakiej występują w oknie Debugowanie Uruchom przykładową aplikację w programie Visual Studio: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

Dzienniki, które są tworzone przez ILogger wywołania pokazano w poprzedniej sekcji zaczyna się od "TodoApi.Controllers.TodoController".The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi.Controllers.TodoController". Dzienniki, które zaczynają się od "Microsoft" kategorie pochodzą z kodu struktury programu ASP.NET Core.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. Platforma ASP.NET Core i kodu aplikacji korzystają z tego samego interfejsu API rejestrowania i dostawców.ASP.NET Core and application code are using the same logging API and providers.

W dalszej części tego artykułu opisano niektóre szczegóły i opcje rejestrowania.The remainder of this article explains some details and options for logging.

Pakiety NuGetNuGet packages

ILogger i ILoggerFactory interfejsy są w Microsoft.Extensions.Logging.Abstractions, i znajdują się w domyślnej implementacji dla nich Microsoft.Extensions.Logging.The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

Kategoria dziennikaLog category

Gdy ILogger obiekt zostanie utworzony, kategorii określono dla niej.When an ILogger object is created, a category is specified for it. Tej kategorii jest uwzględnione w każdej wiadomości dziennika utworzone przez to wystąpienie Ilogger.That category is included with each log message created by that instance of Ilogger. Kategoria może być dowolnym ciągiem, ale Konwencji jest użycie nazwy klasy, takie jak "TodoApi.Controllers.TodoController".The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

Użyj ILogger<T> można pobrać ILogger wystąpienie, które korzysta z w pełni kwalifikowana nazwa typu z T kategorię: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;
    }
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

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

Aby jawnie określić kategorię, należy wywołać ILoggerFactory.CreateLogger: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");
    }
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> jest równoważne z wywoływaniem CreateLogger z w pełni kwalifikowana nazwa typu z T.ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Poziom dziennikaLog level

Każdy dziennik Określa LogLevel wartość.Every log specifies a LogLevel value. Poziom dziennika wskazuje ważność lub ważność.The log level indicates the severity or importance. Na przykład można napisać Information logowania, jeśli metoda zakończy się normalnie, a jeśli tak, to a Warning Zaloguj się, gdy metoda zwróci wartość 404 Nie znaleziono kod stanu.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.

Poniższy kod tworzy Information i Warning dzienników: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);
}
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);
}

W poprzednim kodzie pierwszy parametr jest identyfikator zdarzenia dziennika.In the preceding code, the first parameter is the Log event ID. Drugi parametr jest szablon wiadomości z symboli zastępczych dla wartości argumentów dostarczone przez pozostałe parametry metody.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Parametry metody są wyjaśnione w komunikatu sekcji szablonu w dalszej części tego artykułu.The method parameters are explained in the message template section later in this article.

Metody, które obejmują poziom w nazwie metody logowania (na przykład LogInformation i LogWarning) są metody rozszerzenia dla ILogger.Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. Wywoływanie tych metod Log metody, która przyjmuje LogLevel parametru.These methods call a Log method that takes a LogLevel parameter. Możesz wywołać Log bezpośrednio zamiast jednej z tych metod rozszerzenia, ale składnia jest stosunkowo skomplikowane.You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. Aby uzyskać więcej informacji, zobacz ILogger i kod źródłowy rozszerzenia rejestratora.For more information, see ILogger and the logger extensions source code.

Platforma ASP.NET Core definiuje następujące poziomy dziennika, w tym miejscu uporządkowane od najniższej do najwyższej ważności.ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • Śledzenie = 0Trace = 0

    Aby uzyskać informacje, które są zazwyczaj przydatne tylko w przypadku debugowania.For information that's typically valuable only for debugging. Te komunikaty mogą zawierać dane poufne aplikacji i dlatego nie można włączyć w środowisku produkcyjnym.These messages may contain sensitive application data and so shouldn't be enabled in a production environment. Domyślnie wyłączone.Disabled by default.

  • Debugowanie = 1Debug = 1

    Aby uzyskać informacje, które mogą być użyteczne podczas programowania i debugowania.For information that may be useful in development and debugging. Przykład: Entering method Configure with flag set to true. Włącz Debug poziom dzienniki w środowisku produkcyjnym, tylko wtedy, gdy rozwiązywania problemów, z powodu dużej liczby dzienników.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.

  • Informacje o = 2Information = 2

    Do śledzenia ogólny przebieg aplikacji.For tracking the general flow of the app. Te dzienniki są zazwyczaj mają niektóre wartości długoterminowe.These logs typically have some long-term value. Przykład: Request received for path /api/todoExample: Request received for path /api/todo

  • Ostrzeżenie = 3Warning = 3

    Nietypowe lub nieoczekiwanych zdarzeń w usłudze flow aplikacji.For abnormal or unexpected events in the app flow. Mogą one zawierać błędy lub inne warunki, które nie powodują aplikacji zatrzymać, ale może być konieczne należy zbadać.These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Obsługiwane wyjątki są spójne użyj Warning poziom dziennika.Handled exceptions are a common place to use the Warning log level. Przykład: FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • Błąd = 4Error = 4

    Błędy i wyjątki, które nie mogą być obsługiwane.For errors and exceptions that cannot be handled. Te komunikaty wskazują wystąpił błąd podczas bieżącego działania lub operacji (takie jak bieżące żądanie HTTP), nie wystąpił błąd całej aplikacji.These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. Przykładowy komunikat dziennika: Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • Krytyczne = 5Critical = 5

    Dla błędów, które wymagają natychmiastowej uwagi.For failures that require immediate attention. Przykłady: utratą danych, brak miejsca na dysku.Examples: data loss scenarios, out of disk space.

Umożliwia kontrolowanie, ile dane wyjściowe dziennika są zapisywane na nośniku określonego poziomu dziennika lub wyświetlić okno.Use the log level to control how much log output is written to a particular storage medium or display window. Na przykład:For example:

  • W środowisku produkcyjnym, należy wysłać Trace za pośrednictwem Information poziomu do woluminu magazynu danych.In production, send Trace through Information level to a volume data store. Wyślij Warning za pośrednictwem Critical danych wartość przechowywania.Send Warning through Critical to a value data store.
  • Podczas tworzenia aplikacji, Wyślij Warning za pośrednictwem Critical do konsoli i Dodaj Trace za pośrednictwem Information podczas rozwiązywania problemów.During development, send Warning through Critical to the console, and add Trace through Information when troubleshooting.

Filtrowanie dziennika sekcję w dalszej części tego artykułu opisano sposób kontrolowania poziomy dziennika, który dostawca obsługuje.The Log filtering section later in this article explains how to control which log levels a provider handles.

Platforma ASP.NET Core zapisuje dzienniki zdarzeń framework.ASP.NET Core writes logs for framework events. Przykłady dzienników wcześniej w tym artykule wykluczone dzienniki poniżej Information poziomie, więc nie Debug lub Trace poziom Dzienniki zostały utworzone.The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Oto przykład dzienniki konsoli produkowanych przez przykładową aplikację skonfigurowana do wyświetlania Debug dzienników: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

Identyfikator zdarzenia logowaniaLog event ID

Można określić w każdym dzienniku identyfikator zdarzenia.Each log can specify an event ID. Przykładowa aplikacja robi to przy użyciu zdefiniowanej lokalnie LoggingEvents klasy: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;
}
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;
}

Identyfikator zdarzenia kojarzy zestaw zdarzeń.An event ID associates a set of events. Na przykład wszystkie dzienniki związane z wyświetlanie listy elementów na stronie może być 1001.For example, all logs related to displaying a list of items on a page might be 1001.

Dostawcy logowania mogą być przechowywane identyfikator zdarzenia w polu Identyfikator w komunikacie rejestrowania lub wcale.The logging provider may store the event ID in an ID field, in the logging message, or not at all. Dostawca debugowania nie Wyświetla identyfikatory zdarzeń.The Debug provider doesn't show event IDs. Konsola dostawca przedstawia identyfikatory zdarzeń w nawiasach kwadratowych po kategorii: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

Szablon wiadomości dziennikaLog message template

Każdy dziennik Określa szablon wiadomości.Each log specifies a message template. Szablon wiadomości mogą zawierać symbole zastępcze, dla których są podane argumenty.The message template can contain placeholders for which arguments are provided. Użyj nazw symboli zastępczych, nie liczby.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);
}
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);
}

Kolejność symboli zastępczych, nie ich nazwy, określa parametry, które służą do zapewniania ich wartości.The order of placeholders, not their names, determines which parameters are used to provide their values. W poniższym kodzie Zauważ, że nazwy parametrów są poza kolejnością w szablonie wiadomości: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);

Ten kod tworzy komunikat dziennika przy użyciu wartości parametrów w sekwencji:This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

Struktury rejestrowania działa w ten sposób, aby zaimplementować rejestrowania dostawców semantycznego rejestrowania, nazywana również rejestrowaniem strukturalnym.The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. Same argumenty są przekazywane do systemu rejestrowania, a nie tylko szablon sformatowany komunikat.The arguments themselves are passed to the logging system, not just the formatted message template. Te informacje umożliwiają dostawcom rejestrowania do przechowywania wartości parametrów jako pola.This information enables logging providers to store the parameter values as fields. Załóżmy na przykład, rejestratora metody wywołania się następująco:For example, suppose logger method calls look like this:

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

Jeśli dzienniki jest wysyłana do usługi Azure Table Storage, każda jednostka usługi Azure Table może mieć ID i RequestTime właściwości, które upraszcza zapytań dotyczących danych dziennika.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. Zapytania można znaleźć wszystkie dzienniki w ramach określonego RequestTime zakresu bez analizowania limit czasu wiadomości SMS.A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

Rejestrowania wyjątkówLogging exceptions

Metody rejestratora mają przeciążenia, które umożliwiają przekazywanie wyjątek, jak w poniższym przykładzie: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);
catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);

Różnych dostawców obsługiwać informacje o wyjątku na różne sposoby.Different providers handle the exception information in different ways. Oto przykład danych wyjściowych debugowania dostawcy w kodzie pokazanym powyżej.Here's an example of Debug provider output from the code shown above.

TodoApi.Controllers.TodoController:Warning: GetById(036dd898-fb01-47e8-9a65-f92eb73cf924) NOT FOUND

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

Filtrowanie dziennikaLog filtering

Można określić minimalny poziom rejestrowania dla określonego dostawcy i kategorii lub dla wszystkich dostawców lub wszystkich kategorii.You can specify a minimum log level for a specific provider and category or for all providers or all categories. Żadnych dzienników poniżej minimalnego poziomu nie są przekazywane do tego dostawcy, dzięki czemu nie uzyskać wyświetlane lub przechowywane.Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

Aby pominąć wszystkie dzienniki, określ LogLevel.None jako minimalny poziom rejestrowania.To suppress all logs, specify LogLevel.None as the minimum log level. Wartość całkowitą LogLevel.None to 6, która jest wyższa niż LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Tworzenie reguły filtrów w konfiguracjiCreate filter rules in configuration

Kod wywołuje szablon projektu CreateDefaultBuilder skonfigurować rejestrowanie dla dostawców konsoli i debugowania.The project template code calls CreateDefaultBuilder to set up logging for the Console and Debug providers. CreateDefaultBuilder Metoda konfiguruje również rejestrowania do wyszukania konfiguracji w Logging sekcji przy użyciu kodu, podobnie do poniższego:The CreateDefaultBuilder method also sets up logging to look for configuration in a Logging section, using code like the following:

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) =>
        {
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

Dane konfiguracji Określa poziomy minimalna dziennika przez dostawcę i kategorii, jak w poniższym przykładzie: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"
    }
  }
}

Ten kod JSON tworzy sześć reguły filtru: jeden dla dostawcy debugowania, cztery dla dostawcy konsoli i jeden dla wszystkich dostawców.This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. Wybrano jedną regułę dla każdego dostawcy podczas ILogger obiekt zostanie utworzony.A single rule is chosen for each provider when an ILogger object is created.

Reguły filtrowania w kodzieFilter rules in code

Poniższy przykład pokazuje, jak zarejestrować reguły filtrów w kodzie: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))
    .Build();

Drugi AddFilter określa dostawcę debugowania przy użyciu jego nazwy.The second AddFilter specifies the Debug provider by using its type name. Pierwszy AddFilter ma zastosowanie do wszystkich dostawców, ponieważ nie określa typ dostawcy.The first AddFilter applies to all providers because it doesn't specify a provider type.

Jak reguły filtrowania zostaną zastosowane.How filtering rules are applied

Dane konfiguracji i AddFilter kod przedstawiony w powyższych przykładach Tworzenie reguły pokazano w poniższej tabeli.The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. Pierwsze sześć pochodzą przykład konfiguracji i ostatnie dwa pochodzą w przykładzie kodu.The first six come from the configuration example and the last two come from the code example.

Wartość liczbowaNumber DostawcaProvider Kategorie, które zaczynają się od...Categories that begin with ... Minimalny poziom rejestrowaniaMinimum log level
11 DebugowanieDebug Wszystkie kategorieAll categories InformacjeInformation
22 KonsolaConsole Microsoft.AspNetCore.Mvc.Razor.InternalMicrosoft.AspNetCore.Mvc.Razor.Internal OstrzeżenieWarning
33 KonsolaConsole Microsoft.AspNetCore.Mvc.Razor.RazorMicrosoft.AspNetCore.Mvc.Razor.Razor DebugowanieDebug
44 KonsolaConsole Microsoft.AspNetCore.Mvc.RazorMicrosoft.AspNetCore.Mvc.Razor BłądError
55 KonsolaConsole Wszystkie kategorieAll categories InformacjeInformation
66 Wszyscy dostawcyAll providers Wszystkie kategorieAll categories DebugowanieDebug
77 Wszyscy dostawcyAll providers SystemSystem DebugowanieDebug
88 DebugowanieDebug MicrosoftMicrosoft ŚledzeniaTrace

Gdy ILogger obiekt zostanie utworzony, ILoggerFactory obiektu wybiera jedną regułę na dostawcy, aby zastosować do tego rejestratora.When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Wszystkie komunikaty napisane przez ILogger wystąpienia są filtrowane w zależności od wybranej reguły.All messages written by an ILogger instance are filtered based on the selected rules. Najbardziej określonej reguły dla każdego dostawcy i pary kategoria możliwe jest wybrana w zaufanym dostępne reguły.The most specific rule possible for each provider and category pair is selected from the available rules.

Następujące algorytm jest używany dla każdego dostawcy podczas ILogger jest tworzona dla danej kategorii:The following algorithm is used for each provider when an ILogger is created for a given category:

  • Wybierz wszystkie reguły, które odpowiadają przez dostawcę lub jego alias.Select all rules that match the provider or its alias. Jeśli nie zostanie znalezione dopasowanie, zaznacz wszystkie reguły przy użyciu dostawcy puste.If no match is found, select all rules with an empty provider.
  • W wyniku poprzedniego kroku wybierz reguły z najdłużej dopasowania prefiksu kategorii.From the result of the preceding step, select rules with longest matching category prefix. Jeśli nie zostanie znalezione dopasowanie, zaznacz wszystkie reguły, które nie określają kategorii.If no match is found, select all rules that don't specify a category.
  • Jeśli wybrano wiele reguł, ostatniego jeden.If multiple rules are selected, take the last one.
  • Jeśli nie zaznaczono żadnych reguł, użyj MinimumLevel.If no rules are selected, use MinimumLevel.

Przy użyciu poprzednich listę reguł, załóżmy, że możesz utworzyć ILogger obiektu dla kategorii "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • W przypadku dostawcy debugowania mają zastosowanie reguły 1, 6 i 8.For the Debug provider, rules 1, 6, and 8 apply. Reguła 8 jest najbardziej specyficzną, więc to jest zaznaczony.Rule 8 is most specific, so that's the one selected.
  • W przypadku dostawcy konsoli mają zastosowanie reguły, 3, 4, 5 i 6.For the Console provider, rules 3, 4, 5, and 6 apply. Reguła 3 jest bardziej konkretny od pozostałych.Rule 3 is most specific.

Wynikowy ILogger wystąpienia wysyła dzienniki Trace poziom i nowsze wersje do debugowania dostawcy.The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Dzienniki programu Debug poziomu i nowszych są wysyłane do dostawcy konsoli.Logs of Debug level and above are sent to the Console provider.

Aliasy dostawcyProvider aliases

Każdy dostawca definiuje alias które mogą być używane w konfiguracji zamiast w pełni kwalifikowana nazwa typu.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. W przypadku dostawców wbudowanych należy stosować następujące aliasy:For the built-in providers, use the following aliases:

  • KonsolaConsole
  • DebugowanieDebug
  • Dziennik zdarzeńEventLog
  • AzureAppServicesAzureAppServices
  • TraceSourceTraceSource
  • EventSourceEventSource

Minimalny poziom domyślnyDefault minimum level

Istnieje minimalne ustawienie poziomie staje się skuteczny tylko wtedy, gdy nie z konfiguracji czy kodu reguły dla danego dostawcy i kategorii.There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. Poniższy przykład pokazuje, jak ustawić minimalny poziom:The following example shows how to set the minimum level:

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

Jeśli nie zostanie jawnie ustawiona minimalny poziom, wartością domyślną jest Information, co oznacza, że Trace i Debug dzienniki są ignorowane.If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

Funkcje filtrowaniaFilter functions

Funkcja filtru jest wywoływana dla wszystkich dostawców i kategorie, które nie mają zasady przypisane do nich przez konfiguracji czy kodu.A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. Kod w funkcji ma dostęp do typu Dostawca, kategoria i poziom dziennika.Code in the function has access to the provider type, category, and log level. Na przykład: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;
        });
    })
    .Build();

Niektórzy dostawcy rejestrowania umożliwiają określenie, kiedy zapisany na nośniku lub ignorowane dzienniki na podstawie poziomu dziennika i kategorii.Some logging providers let you specify when logs should be written to a storage medium or ignored based on log level and category.

AddConsole i AddDebug metody rozszerzenia, zapewnienia przeciążenia, które akceptują kryteria filtrowania.The AddConsole and AddDebug extension methods provide overloads that accept filtering criteria. Następujący przykładowy kod powoduje, że Konsola dostawca ignorowanie dzienniki poniżej Warning poziomu, podczas gdy dostawca debugowania ignoruje dzienniki tworzonych w ramach.The following sample code causes the console provider to ignore logs below Warning level, while the Debug provider ignores logs that the framework creates.

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole(LogLevel.Warning)
        .AddDebug((category, logLevel) => (category.Contains("TodoApi") && logLevel >= LogLevel.Trace));

AddEventLog Metoda ma przeciążenia, które przyjmuje EventLogSettings wystąpienia, co może zawierać funkcji filtrowania w jego Filter właściwości.The AddEventLog method has an overload that takes an EventLogSettings instance, which may contain a filtering function in its Filter property. Dostawca TraceSource nie zapewnia żadnego z tych przeciążeń, ponieważ jej poziom rejestrowania i inne parametry są oparte na SourceSwitch i TraceListener używa.The TraceSource provider doesn't provide any of those overloads, since its logging level and other parameters are based on the SourceSwitch and TraceListener it uses.

Aby ustawić reguły filtrowania dla wszystkich dostawców, które są zarejestrowane w usłudze ILoggerFactory wystąpienia, należy użyć WithFilter — metoda rozszerzenia.To set filtering rules for all providers that are registered with an ILoggerFactory instance, use the WithFilter extension method. Poniższy przykład ogranicza framework dzienniki (kategoria zaczyna się od "Microsoft" lub "System") ostrzeżeń podczas logowania się na poziomie debugowania dla dzienników tworzona przez kod aplikacji.The example below limits framework logs (category begins with "Microsoft" or "System") to warnings while logging at debug level for logs created by application code.

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .WithFilter(new FilterLoggerSettings
        {
            { "Microsoft", LogLevel.Warning },
            { "System", LogLevel.Warning },
            { "ToDoApi", LogLevel.Debug }
        })
        .AddConsole()
        .AddDebug();

Aby zapobiec sytuacji, w której wszelkie dzienniki zapisywana, podaj LogLevel.None jako minimalny poziom rejestrowania.To prevent any logs from being written, specify LogLevel.None as the minimum log level. Wartość całkowitą LogLevel.None to 6, która jest wyższa niż LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

WithFilter Metody rozszerzenia są dostarczane przez Microsoft.Extensions.Logging.Filter pakietu NuGet.The WithFilter extension method is provided by the Microsoft.Extensions.Logging.Filter NuGet package. Metoda ta zwraca nowy ILoggerFactory zarejestrowano wystąpienia, która będzie filtrować komunikaty dziennika, przekazywane do wszystkich dostawców rejestratora.The method returns a new ILoggerFactory instance that will filter the log messages passed to all logger providers registered with it. Nie wpływa na inne ILoggerFactory wystąpienia, w tym oryginalny ILoggerFactory wystąpienia.It doesn't affect any other ILoggerFactory instances, including the original ILoggerFactory instance.

Kategorie systemu i poziomySystem categories and levels

Poniżej przedstawiono niektóre kategorie używane przez platformy ASP.NET Core i Entity Framework Core, z uwagi na temat co dzienniki można oczekiwać od nich:Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

KategoriaCategory UwagiNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore Diagnostyka ogólnego ASP.NET Core.General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection Klucze, które zostały uznane za znaleziono i używane.Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering Hosty dozwolone.Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting Ile żądań HTTP potrzebny do ukończenia, a także czas rozpoczęcia pracy.How long HTTP requests took to complete and what time they started. Zestawy startowe, które hostingu zostały załadowane.Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc Diagnostyka MVC i Razor.MVC and Razor diagnostics. Powiązanie modelu, wykonywanie filtru, kompilacja widoku wybór akcji.Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing Trasę odpowiednią dla informacji.Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server Rozpoczęcie połączenia zatrzymać i zachować aktywności odpowiedzi.Connection start, stop, and keep alive responses. Informacje o certyfikacie protokołu HTTPS.HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles Obsługiwane pliki.Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Ogólne Diagnostyka platformy Entity Framework Core.General Entity Framework Core diagnostics. Działanie i konfiguracji wykrywania zmian migracje baz danych.Database activity and configuration, change detection, migrations.

Zakresy dziennikaLog scopes

A zakres można grupować zestaw operacji logicznej.A scope can group a set of logical operations. Ta metoda grupowania może służyć do dołączenia do tych samych danych do każdego dziennika, który jest tworzony jako część zestawu.This grouping can be used to attach the same data to each log that's created as part of a set. Na przykład każdy dziennik utworzony jako część przetwarzania transakcji może zawierać identyfikator transakcji.For example, every log created as part of processing a transaction can include the transaction ID.

Zakres jest IDisposable typu, który jest zwracany przez BeginScope metody i trwa do momentu jego usunięcia.A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Użyj zakresu opakowując wywołania rejestratora w using bloku: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);
}

Poniższy kod umożliwia zakresy dla dostawcy konsoli: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();
})

Uwaga

Konfigurowanie IncludeScopes opcja rejestratora konsoli jest wymagana, aby włączyć rejestrowanie zakresu.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Aby uzyskać informacji na temat konfigurowania, zobacz konfiguracji sekcji.For information on configuration, see the Configuration section.

Program.cs:Program.cs:

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

Uwaga

Konfigurowanie IncludeScopes opcja rejestratora konsoli jest wymagana, aby włączyć rejestrowanie zakresu.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Startup.cs:Startup.cs:

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole(includeScopes: true)
        .AddDebug();

Każdy komunikat dziennika zawiera informacje o określonym zakresie:Each log message includes the scoped information:

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

Wbudowane funkcje rejestrowania dostawcówBuilt-in logging providers

ASP.NET Core jest dostarczana w następujących dostawców:ASP.NET Core ships the following providers:

Opcje dla rejestrowania na platformie Azure zostały omówione w dalszej części tego artykułu.Options for Logging in Azure are covered later in this article.

Informacje dotyczące rejestrowania strumienia wyjściowego stdout, zobacz Rozwiązywanie problemów z platformą ASP.NET Core w usługach IIS i Rozwiązywanie problemów z platformą ASP.NET Core w usłudze Azure App Service.For information about stdout logging, see Rozwiązywanie problemów z platformą ASP.NET Core w usługach IIS and Rozwiązywanie problemów z platformą ASP.NET Core w usłudze Azure App Service.

Konsola dostawcyConsole provider

Microsoft.Extensions.Logging.Console pakiet dostawcy wysyła dane wyjściowe dziennika do konsoli.The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();
loggerFactory.AddConsole();

Przeciążenia AddConsole pozwalają przekazać minimalny poziom rejestrowania, funkcję filtru i atrybut typu wartość logiczna, która wskazuje, czy zakresy są obsługiwane.AddConsole overloads let you pass in a minimum log level, a filter function, and a boolean that indicates whether scopes are supported. Innym rozwiązaniem jest przekazywanie IConfiguration obiektu, który można określić zakresy pomocy technicznej i poziomów rejestrowania.Another option is to pass in an IConfiguration object, which can specify scopes support and logging levels.

Dostawca konsola ma znaczący wpływ na wydajność i zwykle nie jest przeznaczone do użycia w środowisku produkcyjnym.The console provider has a significant impact on performance and is generally not appropriate for use in production.

Podczas tworzenia nowego projektu w programie Visual Studio, AddConsole metoda wygląda następująco:When you create a new project in Visual Studio, the AddConsole method looks like this:

loggerFactory.AddConsole(Configuration.GetSection("Logging"));

Ten kod, który odwołuje się do Logging części appSettings.json pliku:This code refers to the Logging section of the appSettings.json file:

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

Ustawienia pokazano limit framework dzienniki, aby ostrzeżenia zezwalając aplikacji do logowania na poziomie debugowania, jak wyjaśniono w filtrowanie dziennika sekcji.The settings shown limit framework logs to warnings while allowing the app to log at debug level, as explained in the Log filtering section. Aby uzyskać więcej informacji, zobacz konfiguracji.For more information, see Configuration.

Aby wyświetlić rejestrowania danych wyjściowych konsoli, otwórz wiersz polecenia w folderze projektu, a następnie uruchom następujące polecenie:To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Debugowanie dostawcyDebug provider

Microsoft.Extensions.Logging.Debug pakiet dostawcy zapisuje dane wyjściowe dziennika za pomocą system.Diagnostics.Debug — klasy (Debug.WriteLine wywołania metody).The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

W systemie Linux, tego dostawcy zapisuje dzienniki na /var/log/message.On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();
loggerFactory.AddDebug();

Przeciążenia AddDebug pozwalają przekazać minimalny poziom rejestrowania lub funkcję filtru.AddDebug overloads let you pass in a minimum log level or a filter function.

Dostawca źródła zdarzeńEventSource provider

W przypadku aplikacji przeznaczonych dla platformy ASP.NET Core 1.1.0 lub nowszym, Microsoft.Extensions.Logging.EventSource zaimplementować pakiet dostawcy śledzenia zdarzeń.For apps that target ASP.NET Core 1.1.0 or later, the Microsoft.Extensions.Logging.EventSource provider package can implement event tracing. W Windows, używa ETW.On Windows, it uses ETW. Dostawca jest dla wielu platform, ale nie są dostępne żadne zdarzenie gromadzenia i wyświetlania narzędzia jeszcze dla systemu Linux lub macOS.The provider is cross-platform, but there are no event collection and display tools yet for Linux or macOS.

logging.AddEventSourceLogger();
loggerFactory.AddEventSourceLogger();

Dobrym sposobem na zbieranie i wyświetlanie dzienników jest użycie narzędzia PerfView.A good way to collect and view logs is to use the PerfView utility. Istnieją inne narzędzia umożliwiające wyświetlanie dzienników zdarzeń systemu Windows, ale narzędzia PerfView zapewnia najlepsze środowisko do pracy z zdarzenia ETW emitowane przez platformę ASP.NET.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET.

Aby skonfigurować narzędzia PerfView do zbierania zdarzeń rejestrowanych przez tego dostawcę, Dodaj parametry *Microsoft-Extensions-Logging do dodatkowych dostawców listy.To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (Nie przegap gwiazdki na początku ciągu).(Don't miss the asterisk at the start of the string.)

Narzędzia Perfview dodatkowych dostawców

Dostawca dziennika zdarzeń WindowsWindows EventLog provider

Microsoft.Extensions.Logging.EventLog pakiet dostawcy wysyła dane wyjściowe dziennika w dzienniku zdarzeń Windows.The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();
loggerFactory.AddEventLog();

Przeciążenia AddEventLog umożliwiają przekazanej EventLogSettings lub minimalny poziom rejestrowania.AddEventLog overloads let you pass in EventLogSettings or a minimum log level.

TraceSource dostawcyTraceSource provider

Microsoft.Extensions.Logging.TraceSource używa dostawcy pakietu TraceSource bibliotek i dostawców.The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);
loggerFactory.AddTraceSource(sourceSwitchName);

Przeciążenia AddTraceSource pozwalają przekazać przełącznik źródła i odbiornika śledzenia.AddTraceSource overloads let you pass in a source switch and a trace listener.

Aby użyć tego dostawcy, aplikacja ma do uruchamiania na .NET Framework (a nie .NET Core).To use this provider, an app has to run on the .NET Framework (rather than .NET Core). Dostawca komunikaty można kierować do różnych odbiorników, takie jak TextWriterTraceListener używane w przykładowej aplikacji.The provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

Poniższy przykład umożliwia skonfigurowanie TraceSource dostawcy, która rejestruje Warning i wyższych komunikaty w oknie konsoli.The following example configures a TraceSource provider that logs Warning and higher messages to the console window.

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddDebug();

    // add Trace Source logging
    var testSwitch = new SourceSwitch("sourceSwitch", "Logging Sample");
    testSwitch.Level = SourceLevels.Warning;
    loggerFactory.AddTraceSource(testSwitch,
        new TextWriterTraceListener(writer: Console.Out));

Rejestrowanie na platformie AzureLogging in Azure

Aby uzyskać informacji na temat rejestrowania na platformie Azure zobacz następujące sekcje:For information about logging in Azure, see the following sections:

Dostawca usługi Azure App ServiceAzure App Service provider

Microsoft.Extensions.Logging.AzureAppServices pakiet dostawcy zapisuje dzienniki w plikach tekstowych w systemie plików aplikacji w usłudze Azure App Service i do magazynu obiektów blob na koncie usługi Azure Storage.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. Pakiet dostawcy jest dostępna dla aplikacji przeznaczonych dla platformy .NET Core 1.1 lub nowszej.The provider package is available for apps targeting .NET Core 1.1 or later.

Jeśli przeznaczony dla platformy .NET Core, pamiętaj o następujących kwestiach:If targeting .NET Core, note the following points:

  • Nie jawnie wywołać AddAzureWebAppDiagnostics.Don't explicitly call AddAzureWebAppDiagnostics. Dostawca automatycznie staje się dostępny do aplikacji, gdy aplikacja jest wdrożona w usłudze Azure App Service.The provider is automatically made available to the app when the app is deployed to Azure App Service.

Jeśli przeznaczonych dla platformy .NET Framework lub odwołuje się do Microsoft.AspNetCore.App meta Microsoft.aspnetcore.all, Dodaj pakiet dostawcy do projektu.If targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project. Wywoływanie AddAzureWebAppDiagnostics na ILoggerFactory wystąpienie:Invoke AddAzureWebAppDiagnostics on an ILoggerFactory instance:

logging.AddAzureWebAppDiagnostics();
loggerFactory.AddAzureWebAppDiagnostics();

AddAzureWebAppDiagnostics Przeciążenia umożliwia przekazywanie w AzureAppServicesDiagnosticsSettings.An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. Obiekt ustawień można zastąpić domyślne ustawienia, takie jak rejestrowanie danych wyjściowych szablonu, nazwa obiektu blob i limit rozmiaru pliku.The settings object can override default settings, such as the logging output template, blob name, and file size limit. (Danych wyjściowych szablonu jest szablon wiadomości, która jest stosowana do wszystkich dzienników oprócz co to jest dostarczana z ILogger wywołania metody.)(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

Podczas wdrażania aplikacji usługi App Service aplikacja honoruje ustawienia w dzienniki diagnostyczne części usługi App Service strony w witrynie Azure Portal.When you deploy to an App Service app, the application honors the settings in the Diagnostic Logs section of the App Service page of the Azure portal. Jeśli te ustawienia zostaną zaktualizowane, zmiany zaczynają obowiązywać natychmiast bez konieczności ponownego uruchomienia lub ponownego wdrażania aplikacji.When these settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

Ustawienia rejestrowania platformy Azure

Domyślną lokalizacją dla plików dziennika jest D:\macierzystego\LogFiles\aplikacji folder i nazwę pliku domyślny jest yyyymmdd.txt diagnostyki.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. Domyślnego limitu rozmiaru pliku to 10 MB, a maksymalną domyślną liczbę plików, które przechowywane jest 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Domyślna nazwa obiektu blob to {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. Aby uzyskać więcej informacji na temat zachowania domyślnego, zobacz AzureAppServicesDiagnosticsSettings.For more information about default behavior, see AzureAppServicesDiagnosticsSettings.

Dostawca działa tylko w przypadku, gdy projekt jest uruchamiany w środowisku platformy Azure.The provider only works when the project runs in the Azure environment. Nie ma wpływu, gdy projekt jest uruchamiany lokalnie—nie zapisywać pliki lokalne lub lokalnym magazynem projektowym dla obiektów blob.It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Przesyłanie strumieniowe dzienników platformy AzureAzure log streaming

Przesyłanie strumieniowe dzienników platformy Azure umożliwia wyświetlanie dzienników aktywności w czasie rzeczywistym z:Azure log streaming lets you view log activity in real time from:

  • Serwer aplikacjiThe app server
  • Serwer sieci webThe web server
  • Śledzenie żądań zakończonych niepowodzeniemFailed request tracing

Aby skonfigurować, przesyłanie strumieniowe dzienników platformy Azure:To configure Azure log streaming:

  • Przejdź do dzienniki diagnostyczne strony na stronie portalu swojej aplikacji.Navigate to the Diagnostics Logs page from your app's portal page.
  • Ustaw rejestrowanie aplikacji (system plików) do na.Set Application Logging (Filesystem) to On.

Strona portalu dzienniki diagnostyczne platformy Azure

Przejdź do przesyłanie strumieniowe dzienników strony, aby wyświetlić komunikaty aplikacji.Navigate to the Log Streaming page to view app messages. Logowanie przeprowadzono za pomocą aplikacji za pośrednictwem ILogger interfejsu.They're logged by the app through the ILogger interface.

Przesyłanie strumieniowe dzienników aplikacji z portalu Azure

Rejestrowanie śledzenia w usłudze Azure Application InsightsAzure Application Insights trace logging

Zestaw SDK usługi Application Insights można zbierać i zgłaszać dzienniki generowane przez infrastrukturę rejestrowania platformy ASP.NET Core.The Application Insights SDK can collect and report logs generated by the ASP.NET Core logging infrastructure. Aby uzyskać więcej informacji, zobacz następujące zasoby:For more information, see the following resources:

Rejestrowanie innych dostawcówThird-party logging providers

Struktury rejestrowania innych firm, które działają z platformą ASP.NET Core:Third-party logging frameworks that work with ASP.NET Core:

Niektóre środowiska innych producentów mogą wykonywać semantycznego rejestrowania, nazywana również rejestrowaniem strukturalnym.Some third-party frameworks can perform semantic logging, also known as structured logging.

Za pomocą środowiska innych producentów są podobne do przy użyciu jednej z wbudowanych dostawców:Using a third-party framework is similar to using one of the built-in providers:

  1. Dodaj pakiet NuGet do projektu.Add a NuGet package to your project.
  2. Wywołaj ILoggerFactory.Call an ILoggerFactory.

Aby uzyskać więcej informacji można znaleźć w temacie każdy dostawca dokumentacji.For more information, see each provider's documentation. Rejestrowanie innych firm nie są obsługiwani przez firmę Microsoft.Third-party logging providers aren't supported by Microsoft.

Dodatkowe zasobyAdditional resources