Rejestrowanie na platformie .NET Core i ASP.NET CoreLogging in .NET Core and ASP.NET Core

Kirka Larkin, Juergen Gutsch i Rick AndersonBy Kirk Larkin, Juergen Gutsch and Rick Anderson

Platforma .NET Core obsługuje interfejs API rejestrowania, który współpracuje z różnymi dostawcami rejestrowania wbudowanych i innych firm..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. W tym artykule pokazano, jak używać interfejsu API rejestrowania z wbudowanymi dostawcami.This article shows how to use the logging API with built-in providers.

Większość przykładów kodu pokazanych w tym artykule pochodzą z ASP.NET Core aplikacji.Most of the code examples shown in this article are from ASP.NET Core apps. Części tych fragmentów kodu dotyczące rejestrowania mają zastosowanie do dowolnej aplikacji .NET Core, która korzysta z hosta ogólnego.The logging-specific parts of these code snippets apply to any .NET Core app that uses the Generic Host. Szablony aplikacji sieci Web ASP.NET Core korzystają z hosta ogólnego.The ASP.NET Core web app templates use the Generic Host.

Wyświetl lub pobierz przykładowy kod (jak pobrać)View or download sample code (how to download)

Dostawcy rejestrowaniaLogging providers

Dostawcy rejestrowania przechowują dzienniki, z wyjątkiem Console dostawcy wyświetlającego dzienniki.Logging providers store logs, except for the Console provider which displays logs. Na przykład dostawca usługi Azure Application Insights przechowuje dzienniki w usłudze Azure Application Insights.For example, the Azure Application Insights provider stores logs in Azure Application Insights. Można włączyć wielu dostawców.Multiple providers can be enabled.

Domyślne szablony aplikacji sieci Web ASP.NET Core:The default ASP.NET Core web app templates:

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

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

Poprzedni kod przedstawia Program klasę utworzoną za pomocą szablonów aplikacji sieci web ASP.NET Core.The preceding code shows the Program class created with the ASP.NET Core web app templates. W następnych sekcjach przedstawiono przykłady w oparciu o szablony aplikacji sieci Web ASP.NET Core, które korzystają z hosta ogólnego.The next several sections provide samples based on the ASP.NET Core web app templates, which use the Generic Host. Aplikacje konsolowe inne niż host są omawiane w dalszej części tego dokumentu.Non-host console apps are discussed later in this document.

Aby zastąpić domyślny zestaw dostawców rejestrowania dodany przez Host.CreateDefaultBuilder , należy wywołać ClearProviders i dodać wymaganych dostawców rejestrowania.To override the default set of logging providers added by Host.CreateDefaultBuilder, call ClearProviders and add the required logging providers. Na przykład następujący kod:For example, the following code:

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

Aby uzyskać dodatkowych dostawców, zobacz:For additional providers, see:

Tworzenie dziennikówCreate logs

Aby utworzyć dzienniki, użyj ILogger<TCategoryName> obiektu z iniekcji zależności (di).To create logs, use an ILogger<TCategoryName> object from dependency injection (DI).

Poniższy przykład:The following example:

  • Tworzy rejestrator, ILogger<AboutModel> który używa kategorii dziennika w pełni kwalifikowanej nazwy typu AboutModel .Creates a logger, ILogger<AboutModel>, which uses a log category of the fully qualified name of the type AboutModel. Kategoria dziennika jest ciągiem, który jest skojarzony z każdym dziennikiem.The log category is a string that is associated with each log.
  • Wywołania LogInformation do rejestrowania na Information poziomie.Calls LogInformation to log at the Information level. Poziom dziennika wskazuje ważność rejestrowanego zdarzenia.The Log level indicates the severity of the logged event.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

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

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

Poziomy i Kategorie zostały wyjaśnione bardziej szczegółowo w dalszej części tego dokumentu.Levels and categories are explained in more detail later in this document.

Aby uzyskać informacje na temat Blazor , zobacz Tworzenie dzienników w Blazor i Blazor WebAssembly w tym dokumencie.For information on Blazor, see Create logs in Blazor and Blazor WebAssembly in this document.

Tworzenie dzienników w programie głównych i początkowych przedstawia sposób tworzenia dzienników w Main i Startup .Create logs in Main and Startup shows how to create logs in Main and Startup.

Konfigurowanie rejestrowaniaConfigure logging

Konfiguracja rejestrowania jest zwykle udostępniana w Logging sekcji AppSettings. {Environment} pliki . JSON .Logging configuration is commonly provided by the Logging section of appsettings.{Environment}.json files. Następujące appsettings.Development.js pliku są generowane przez Szablony aplikacji sieci Web ASP.NET Core:The following appsettings.Development.json file is generated by the ASP.NET Core web app templates:

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

W powyższym formacie JSON:In the preceding JSON:

  • "Default"Określono, "Microsoft" , i "Microsoft.Hosting.Lifetime" Kategorie.The "Default", "Microsoft", and "Microsoft.Hosting.Lifetime" categories are specified.
  • "Microsoft"Kategoria dotyczy wszystkich kategorii, które zaczynają się od "Microsoft" .The "Microsoft" category applies to all categories that start with "Microsoft". Na przykład to ustawienie ma zastosowanie do "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategorii.For example, this setting applies to the "Microsoft.AspNetCore.Routing.EndpointMiddleware" category.
  • "Microsoft"Kategoria rejestruje się na poziomie dziennika Warning lub wyższym.The "Microsoft" category logs at log level Warning and higher.
  • "Microsoft.Hosting.Lifetime"Kategoria jest bardziej precyzyjna niż "Microsoft" Kategoria, więc jest "Microsoft.Hosting.Lifetime" rejestrowana w kategorii na poziomie dziennika "informacje" i wyższych.The "Microsoft.Hosting.Lifetime" category is more specific than the "Microsoft" category, so the "Microsoft.Hosting.Lifetime" category logs at log level "Information" and higher.
  • Określony dostawca dziennika nie został określony, dlatego LogLevel dotyczy wszystkich włączonych dostawców rejestrowania z wyjątkiem dziennika zdarzeń systemu Windows.A specific log provider is not specified, so LogLevel applies to all the enabled logging providers except for the Windows EventLog.

LoggingWłaściwość może mieć LogLevel właściwości dostawcy dzienników i.The Logging property can have LogLevel and log provider properties. LogLevelOkreśla minimalny poziom rejestrowania wybranych kategorii.The LogLevel specifies the minimum level to log for selected categories. W poprzednim pliku JSON Information i Warning poziomy dziennika są określone.In the preceding JSON, Information and Warning log levels are specified. LogLevelwskazuje ważność dziennika i zakres od 0 do 6:LogLevel indicates the severity of the log and ranges from 0 to 6:

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

Gdy LogLevel jest określony, funkcja rejestrowania jest włączona dla komunikatów na określonym poziomie i wyższych.When a LogLevel is specified, logging is enabled for messages at the specified level and higher. W poprzednim pliku JSON Default Kategoria jest zarejestrowana dla Information i wyższa.In the preceding JSON, the Default category is logged for Information and higher. Na przykład,,, Information Warning Error i Critical komunikaty są rejestrowane.For example, Information, Warning, Error, and Critical messages are logged. Jeśli nie LogLevel jest określony, rejestrowane są wartości domyślne na Information poziomie.If no LogLevel is specified, logging defaults to the Information level. Aby uzyskać więcej informacji, zobacz poziomy dzienników.For more information, see Log levels.

Właściwość dostawcy może określać LogLevel Właściwość.A provider property can specify a LogLevel property. LogLevelw obszarze dostawca Określa poziomy do rejestrowania dla tego dostawcy i zastępuje ustawienia dziennika niedostawcy.LogLevel under a provider specifies levels to log for that provider, and overrides the non-provider log settings. Rozważmy następujące appsettings.js pliku:Consider the following appsettings.json file:

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

Ustawienia w Logging.{providername}.LogLevel ustawieniach przesłonięcia w programie Logging.LogLevel .Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. W powyższym kodzie JSON Debug domyślny poziom rejestrowania dostawcy jest ustawiany na Information :In the preceding JSON, the Debug provider's default log level is set to Information:

Logging:Debug:LogLevel:Default:Information

Powyższe ustawienie określa Information poziom rejestrowania dla każdej Logging:Debug: kategorii z wyjątkiem Microsoft.Hosting .The preceding setting specifies the Information log level for every Logging:Debug: category except Microsoft.Hosting. Gdy określona kategoria jest wymieniona, określona Kategoria zastępuje domyślną kategorię.When a specific category is listed, the specific category overrides the default category. W powyższym formacie JSON Logging:Debug:LogLevel Kategorie "Microsoft.Hosting" i "Default" zastępują ustawienia wLogging:LogLevelIn the preceding JSON, the Logging:Debug:LogLevel categories "Microsoft.Hosting" and "Default" override the settings in Logging:LogLevel

Minimalny poziom dziennika można określić dla dowolnego z:The minimum log level can be specified for any of:

  • Określeni dostawcy: na przykładLogging:EventSource:LogLevel:Default:InformationSpecific providers: For example, Logging:EventSource:LogLevel:Default:Information
  • Określone kategorie: na przykładLogging:LogLevel:Microsoft:WarningSpecific categories: For example, Logging:LogLevel:Microsoft:Warning
  • Wszyscy dostawcy i wszystkie kategorie:Logging:LogLevel:Default:WarningAll providers and all categories: Logging:LogLevel:Default:Warning

Wszystkie dzienniki poniżej minimalnego poziomu niesą następujące:Any logs below the minimum level are not:

  • Przeszedł do dostawcy.Passed to the provider.
  • Zarejestrowane lub wyświetlone.Logged or displayed.

Aby pominąć wszystkie dzienniki, należy określić wartość LogLevel. None.To suppress all logs, specify LogLevel.None. LogLevel.Nonema wartość 6, która jest większa niż LogLevel.Critical (5).LogLevel.None has a value of 6, which is higher than LogLevel.Critical (5).

Jeśli dostawca obsługuje zakresy rejestrowania, IncludeScopes wskazuje, czy są one włączone.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Aby uzyskać więcej informacji, zobacz zakresy dziennikówFor more information, see log scopes

Następująca appsettings.jsw pliku zawiera wszystkich dostawców włączonych domyślnie:The following appsettings.json file contains all the providers enabled by default:

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

W poprzednim przykładzie:In the preceding sample:

  • Kategorie i poziomy nie są sugerowanymi wartościami.The categories and levels are not suggested values. Przykład podano, aby wyświetlić wszystkich dostawców domyślnych.The sample is provided to show all the default providers.
  • Ustawienia w Logging.{providername}.LogLevel ustawieniach przesłonięcia w programie Logging.LogLevel .Settings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. Na przykład poziom w Debug.LogLevel.Default zastępują poziom w LogLevel.Default .For example, the level in Debug.LogLevel.Default overrides the level in LogLevel.Default.
  • Każdy domyślny alias dostawcy jest używany.Each default provider alias is used. Każdy dostawca definiuje alias , który może być używany w konfiguracji zamiast w pełni kwalifikowanej nazwy typu.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Aliasy wbudowane dostawcy to:The built-in providers aliases are:
    • KonsolaConsole
    • DebugowanieDebug
    • EventSourceEventSource
    • ElemencieEventLog
    • AzureAppServicesFileAzureAppServicesFile
    • AzureAppServicesBlobAzureAppServicesBlob
    • ApplicationInsightsApplicationInsights

Ustawianie poziomu dziennika według wiersza polecenia, zmiennych środowiskowych i innych konfiguracjiSet log level by command line, environment variables, and other configuration

Poziom dziennika może być ustawiony przez dowolnego dostawcę konfiguracji.Log level can be set by any of the configuration providers.

: Separator nie działa ze zmiennymi kluczy hierarchicznych na wszystkich platformach.The : separator doesn't work with environment variable hierarchical keys on all platforms. __, podwójne podkreślenie:__, the double underscore, is:

  • Obsługiwane przez wszystkie platformy.Supported by all platforms. Na przykład : separator nie jest obsługiwany przez bash, ale __ jest.For example, the : separator is not supported by Bash, but __ is.
  • Automatycznie zastąpione przez:Automatically replaced by a :

Następujące polecenia:The following commands:

  • Ustaw klucz środowiska na Logging:LogLevel:Microsoft wartość Information w systemie Windows.Set the environment key Logging:LogLevel:Microsoft to a value of Information on Windows.
  • Przetestuj ustawienia w przypadku korzystania z aplikacji utworzonej za pomocą szablonów aplikacji sieci Web ASP.NET Core.Test the settings when using an app created with the ASP.NET Core web application templates. dotnet runPolecenie musi być uruchamiane w katalogu projektu po użyciu set .The dotnet run command must be run in the project directory after using set.
set Logging__LogLevel__Microsoft=Information
dotnet run

Poprzednie ustawienie środowiska:The preceding environment setting:

  • Jest ustawiana tylko w ramach procesów uruchomionych z poziomu okna polecenia, które zostały ustawione w.Is only set in processes launched from the command window they were set in.
  • Nie są odczytywane przez przeglądarki uruchomione przy użyciu programu Visual Studio.Isn't read by browsers launched with Visual Studio.

Następujące polecenie setx ustawia również klucz środowiska i wartość w systemie Windows.The following setx command also sets the environment key and value on Windows. W przeciwieństwie do set , setx Ustawienia są utrwalane.Unlike set, setx settings are persisted. /MPrzełącznik ustawia zmienną w środowisku systemowym.The /M switch sets the variable in the system environment. Jeśli /M nie jest używany, zmienna środowiskowa użytkownika jest ustawiona.If /M isn't used, a user environment variable is set.

setx Logging__LogLevel__Microsoft=Information /M

Na Azure App Servicewybierz pozycję nowe ustawienie aplikacji na stronie Konfiguracja > ustawienia .On Azure App Service, select New application setting on the Settings > Configuration page. Ustawienia aplikacji Azure App Service są następujące:Azure App Service application settings are:

  • Szyfrowane i przesyłane przez zaszyfrowanego kanału.Encrypted at rest and transmitted over an encrypted channel.
  • Uwidocznione jako zmienne środowiskowe.Exposed as environment variables.

Aby uzyskać więcej informacji, zobacz artykuł Azure Apps: zastępowanie konfiguracji aplikacji przy użyciu witryny Azure Portal.For more information, see Azure Apps: Override app configuration using the Azure Portal.

Aby uzyskać więcej informacji na temat ustawiania ASP.NET Core wartości konfiguracji przy użyciu zmiennych środowiskowych, zobacz zmienne środowiskowe.For more information on setting ASP.NET Core configuration values using environment variables, see environment variables. Aby uzyskać informacje na temat korzystania z innych źródeł konfiguracji, w tym z wiersza polecenia, Azure Key Vault, konfiguracja aplikacji platformy Azure, inne formaty plików i inne, zobacz Konfiguracja w ASP.NET Core .For information on using other configuration sources, including the command line, Azure Key Vault, Azure App Configuration, other file formats, and more, see Konfiguracja w ASP.NET Core.

Jak są stosowane reguły filtrowaniaHow filtering rules are applied

Po ILogger<TCategoryName> utworzeniu obiektu ILoggerFactory obiekt wybiera jedną regułę dla każdego dostawcy, która ma zostać zastosowana do tego rejestratora.When an ILogger<TCategoryName> object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Wszystkie komunikaty zapisywane przez ILogger wystąpienie są filtrowane na podstawie wybranych reguł.All messages written by an ILogger instance are filtered based on the selected rules. Dla każdego dostawcy i pary kategorii jest wybierana najbardziej konkretna reguła z dostępnych reguł.The most specific rule for each provider and category pair is selected from the available rules.

Następujący algorytm jest używany dla każdego dostawcy, gdy ILogger jest tworzony 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 pasują do dostawcy lub jego aliasu.Select all rules that match the provider or its alias. Jeśli nie zostanie znalezione dopasowanie, zaznacz wszystkie reguły z pustym dostawcą.If no match is found, select all rules with an empty provider.
  • W wyniku poprzedniego kroku wybierz pozycję reguły z najdłuższym prefiksem 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ł, zrób to ostatnie .If multiple rules are selected, take the last one.
  • Jeśli nie wybrano żadnych reguł, użyj MinimumLevel .If no rules are selected, use MinimumLevel.

Rejestrowanie danych wyjściowych z przebiegu dotnet i programu Visual StudioLogging output from dotnet run and Visual Studio

Wyświetlane są dzienniki utworzone przy użyciu domyślnych dostawców rejestrowania :Logs created with the default logging providers are displayed:

  • W programie Visual StudioIn Visual Studio
    • W oknie dane wyjściowe debugowania podczas debugowania.In the Debug output window when debugging.
    • W oknie ASP.NET Core serwer sieci Web.In the ASP.NET Core Web Server window.
  • W oknie konsoli, gdy aplikacja jest uruchamiana z dotnet run .In the console window when the app is run with dotnet run.

Dzienniki zaczynające się od kategorii "Microsoft" pochodzą z kodu ASP.NET Core Framework.Logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core i kod aplikacji używają tego samego rejestrowania interfejsu API i dostawców.ASP.NET Core and application code use the same logging API and providers.

Kategoria dziennikaLog category

Po ILogger utworzeniu obiektu zostanie określona Kategoria .When an ILogger object is created, a category is specified. Ta kategoria jest dołączona do każdego komunikatu dziennika utworzonego przez to wystąpienie ILogger .That category is included with each log message created by that instance of ILogger. Ciąg kategorii jest dowolny, ale Konwencja ma używać nazwy klasy.The category string is arbitrary, but the convention is to use the class name. Przykładowo może to być nazwa w kontrolerze "TodoApi.Controllers.TodoController" .For example, in a controller the name might be "TodoApi.Controllers.TodoController". ASP.NET Core aplikacje sieci Web używają ILogger<T> do automatycznego pobrania ILogger wystąpienia, które używa w pełni kwalifikowanej nazwy typu T jako kategorii:The ASP.NET Core web apps use ILogger<T> to automatically get an ILogger instance that uses the fully qualified type name of T as the category:

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

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

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

Aby jawnie określić kategorię, wywołaj ILoggerFactory.CreateLogger :To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

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

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

ILogger<T>jest odpowiednikiem wywołania CreateLogger z w pełni kwalifikowaną nazwą typu T .ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Poziom dziennikaLog level

W poniższej tabeli wymieniono LogLevel wartości, wygodną Log{LogLevel} metodę rozszerzenia oraz Sugerowane użycie:The following table lists the LogLevel values, the convenience Log{LogLevel} extension method, and the suggested usage:

LogLevelLogLevel WartośćValue MetodaMethod OpisDescription
ŚladTrace 00 LogTrace Zawierają najwięcej szczegółowych komunikatów.Contain the most detailed messages. Te komunikaty mogą zawierać poufne dane aplikacji.These messages may contain sensitive app data. Te komunikaty są domyślnie wyłączone i nie powinny być włączone w środowisku produkcyjnym.These messages are disabled by default and should not be enabled in production.
DebugowanieDebug 11 LogDebug Na potrzeby debugowania i programowania.For debugging and development. W środowisku produkcyjnym należy używać ostrożnie z powodu dużego wolumenu.Use with caution in production due to the high volume.
InformacjeInformation 22 LogInformation Śledzi ogólny przepływ aplikacji.Tracks the general flow of the app. Może mieć wartość długoterminową.May have long-term value.
OstrzeżenieWarning 33 LogWarning Dla nietypowych lub nieoczekiwanych zdarzeń.For abnormal or unexpected events. Zwykle zawiera błędy lub warunki, które nie powodują błędu aplikacji.Typically includes errors or conditions that don't cause the app to fail.
BłądError 44 LogError W przypadku błędów i wyjątków, których nie można obsłużyć.For errors and exceptions that cannot be handled. Te komunikaty wskazują na niepowodzenie podczas bieżącej operacji lub żądania, a nie awarię całej aplikacji.These messages indicate a failure in the current operation or request, not an app-wide failure.
KrytyczneCritical 55 LogCritical Dla niepowodzeń, które wymagają natychmiastowej uwagi.For failures that require immediate attention. Przykłady: scenariusze utraty danych, brak miejsca na dysku.Examples: data loss scenarios, out of disk space.
BrakNone 66 Określa, że Kategoria rejestrowania nie powinna zapisywać żadnych komunikatów.Specifies that a logging category should not write any messages.

W poprzedniej tabeli LogLevel znajduje się na liście od najniższej do najwyższej wagi.In the previous table, the LogLevel is listed from lowest to highest severity.

Pierwszy parametr metody log LogLevel wskazuje ważność dziennika.The Log method's first parameter, LogLevel, indicates the severity of the log. Zamiast wywoływania Log(LogLevel, ...) , większość deweloperów wywołuje metody rozszerzenia dziennika {LogLevel} .Rather than calling Log(LogLevel, ...), most developers call the Log{LogLevel} extension methods. Log{LogLevel}Metody rozszerzające wywołują metodę log i określają wartość LogLevel.The Log{LogLevel} extension methods call the Log method and specify the LogLevel. Na przykład następujące dwa wywołania rejestrowania są funkcjonalnie równoważne i generują ten sam dziennik:For example, the following two logging calls are functionally equivalent and produce the same log:

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

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

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItemjest IDENTYFIKATORem zdarzenia.MyLogEvents.TestItem is the event ID. MyLogEventsjest częścią przykładowej aplikacji i jest wyświetlana w sekcji Identyfikator zdarzenia dziennika .MyLogEvents is part of the sample app and is displayed in the Log event ID section.

MyDisplayRouteInfo i ToCtxString są dostarczane przez pakiet NuGet Rick.Docs. Samples. RouteInfo .MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. Metody wyświetlają Controller Informacje o trasie.The methods display Controller route information.

Poniższy kod tworzy Information i Warning rejestruje:The following code creates Information and Warning logs:

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

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

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

    return ItemToDTO(todoItem);
}

W poprzednim kodzie pierwszy Log{LogLevel} parametr, MyLogEvents.GetItem , jest Identyfikator zdarzenia dziennika.In the preceding code, the first Log{LogLevel} parameter,MyLogEvents.GetItem, is the Log event ID. Drugi parametr jest szablonem wiadomości z symbolami zastępczymi dla wartości argumentów dostarczonych 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 zostały wyjaśnione w sekcji szablon komunikatu w dalszej części tego dokumentu.The method parameters are explained in the message template section later in this document.

Wywołaj odpowiednią Log{LogLevel} metodę, aby kontrolować, ile danych wyjściowych dziennika jest zapisywana w określonym nośniku magazynowania.Call the appropriate Log{LogLevel} method to control how much log output is written to a particular storage medium. Na przykład:For example:

  • W środowisku produkcyjnym:In production:
    • Rejestrowanie na poziomie Trace lub Information powoduje utworzenie dużej ilości szczegółowych komunikatów dziennika.Logging at the Trace or Information levels produces a high-volume of detailed log messages. Aby kontrolować koszty i nie przekraczać limitów magazynowania danych Trace , Information komunikaty dzienników i na poziomie magazynu o dużej ilości danych.To control costs and not exceed data storage limits, log Trace and Information level messages to a high-volume, low-cost data store. Rozważ ograniczenie Trace i Information do określonych kategorii.Consider limiting Trace and Information to specific categories.
    • Rejestrowanie przy Warning użyciu Critical poziomów powinno generować kilka komunikatów dziennika.Logging at Warning through Critical levels should produce few log messages.
      • Koszty i limity magazynu zazwyczaj nie są przedmiotem obaw.Costs and storage limits usually aren't a concern.
      • Niektóre dzienniki zapewniają większą elastyczność w zakresie wyboru magazynu danych.Few logs allow more flexibility in data store choices.
  • W programie Development:In development:
    • Ustaw wartość Warning.Set to Warning.
    • Dodawanie Trace lub Information komunikaty podczas rozwiązywania problemów.Add Trace or Information messages when troubleshooting. Aby ograniczyć ilość danych wyjściowych, ustaw Trace lub Information tylko dla kategorii poddawanych badaniu.To limit output, set Trace or Information only for the categories under investigation.

ASP.NET Core zapisuje dzienniki dla zdarzeń struktury.ASP.NET Core writes logs for framework events. Rozważmy na przykład dane wyjściowe dziennika dla:For example, consider the log output for:

  • RazorAplikacja ze stronami utworzona przy użyciu szablonów ASP.NET Core.A Razor Pages app created with the ASP.NET Core templates.
  • Rejestrowanie ustawione naLogging:Console:LogLevel:Microsoft:InformationLogging set to Logging:Console:LogLevel:Microsoft:Information
  • Nawigacja do strony prywatność:Navigation to the Privacy page:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

Następujące zestawy JSON Logging:Console:LogLevel:Microsoft:Information :The following JSON sets Logging:Console:LogLevel:Microsoft:Information:

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

Identyfikator zdarzenia dziennikaLog event ID

Każdy dziennik może określać Identyfikator zdarzenia.Each log can specify an event ID. Przykładowa aplikacja używa MyLogEvents klasy do definiowania identyfikatorów zdarzeń:The sample app uses the MyLogEvents class to define event IDs:

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

    public const int TestItem      = 3000;

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

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

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

    return ItemToDTO(todoItem);
}

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

Dostawca rejestrowania może przechowywać identyfikator zdarzenia w polu identyfikatora, 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 pokazuje identyfikatorów zdarzeń.The Debug provider doesn't show event IDs. Dostawca konsoli pokazuje identyfikatory zdarzeń w nawiasach po kategorii:The console provider shows event IDs in brackets after the category:

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

Niektórzy dostawcy rejestrowania przechowują identyfikator zdarzenia w polu, co umożliwia filtrowanie identyfikatorów.Some logging providers store the event ID in a field, which allows for filtering on the ID.

Szablon komunikatu dziennikaLog message template

Każdy interfejs API dziennika używa szablonu wiadomości.Each log API uses a message template. Szablon wiadomości może zawierać symbole zastępcze, dla których podano argumenty.The message template can contain placeholders for which arguments are provided. Użyj nazw dla symboli zastępczych, a nie liczby.Use names for the placeholders, not numbers.

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

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

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

    return ItemToDTO(todoItem);
}

Kolejność symboli zastępczych, nie ich nazw, określa, które parametry są używane do dostarczania ich wartości.The order of placeholders, not their names, determines which parameters are used to provide their values. W poniższym kodzie nazwy parametrów są spoza sekwencji w szablonie wiadomości:In the following code, the parameter names are out of sequence in the message template:

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

Poprzedni kod tworzy komunikat dziennika z wartościami parametrów w kolejności:The preceding code creates a log message with the parameter values in sequence:

Parameter values: param1, param2

Takie podejście umożliwia dostawcom rejestrowania implementowanie semantyki lub rejestrowania strukturalnego.This approach allows logging providers to implement semantic or structured logging. Same argumenty są przesyłane do systemu rejestrowania, a nie tylko dla sformatowanego szablonu wiadomości.The arguments themselves are passed to the logging system, not just the formatted message template. Umożliwia to dostawcom rejestrowania przechowywanie wartości parametrów jako pól.This enables logging providers to store the parameter values as fields. Rozważmy na przykład następujące metody rejestratora:For example, consider the following logger method:

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

Na przykład podczas rejestrowania w usłudze Azure Table Storage:For example, when logging to Azure Table Storage:

  • Każda jednostka tabeli platformy Azure może ID mieć RequestTime właściwości i.Each Azure Table entity can have ID and RequestTime properties.
  • Tabele z właściwościami upraszczają zapytania dotyczące zarejestrowanych danych.Tables with properties simplify queries on logged data. Na przykład zapytanie może znaleźć wszystkie dzienniki w określonym RequestTime zakresie bez konieczności analizowania limitu czasu wiadomości tekstowej.For example, a query can find all logs within a particular RequestTime range without having to parse the time out of the text message.

Wyjątki dziennikaLog exceptions

Metody rejestratora mają przeciążenia przyjmujące parametr wyjątku:The logger methods have overloads that take an exception parameter:

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

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

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo i ToCtxString są dostarczane przez pakiet NuGet Rick.Docs. Samples. RouteInfo .MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. Metody wyświetlają Controller Informacje o trasie.The methods display Controller route information.

Rejestrowanie wyjątków jest specyficzne dla dostawcy.Exception logging is provider-specific.

Domyślny poziom dziennikaDefault log level

Jeśli domyślny poziom rejestrowania nie jest ustawiony, domyślna wartość poziomu dziennika to Information .If the default log level is not set, the default log level value is Information.

Rozważmy na przykład następującą aplikację sieci Web:For example, consider the following web app:

  • Utworzono za pomocą szablonów aplikacji sieci Web ASP.NET.Created with the ASP.NET web app templates.
  • appsettings.json i appsettings.Development.jspo usunięciu lub zmianie nazwy.appsettings.json and appsettings.Development.json deleted or renamed.

Po powyższej instalacji przechodzenie do strony prywatność lub Strona główna powoduje utworzenie wielu Trace , Debug i Information komunikatów z Microsoft nazwą kategorii.With the preceding setup, navigating to the privacy or home page produces many Trace, Debug, and Information messages with Microsoft in the category name.

Poniższy kod ustawia domyślny poziom rejestrowania, jeśli domyślny poziom rejestrowania nie jest ustawiony w konfiguracji:The following code sets the default log level when the default log level is not set in configuration:

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

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

Ogólnie rzecz biorąc, poziomy dziennika należy określić w obszarze Konfiguracja i nie kod.Generally, log levels should be specified in configuration and not code.

Funkcja filtrowaniaFilter function

Funkcja filtru jest wywoływana dla wszystkich dostawców i kategorii, które nie mają przypisanych do nich reguł przez konfigurację lub kod:A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code:

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

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

Poprzedni kod wyświetla dzienniki konsoli, gdy kategoria zawiera Controller lub Microsoft i poziom dziennika jest Information lub wyższy.The preceding code displays console logs when the category contains Controller or Microsoft and the log level is Information or higher.

Ogólnie rzecz biorąc, poziomy dziennika należy określić w obszarze Konfiguracja i nie kod.Generally, log levels should be specified in configuration and not code.

Kategorie ASP.NET Core i EF CoreASP.NET Core and EF Core categories

Poniższa tabela zawiera niektóre kategorie używane przez ASP.NET Core i Entity Framework Core z uwagami dotyczącymi dzienników:The following table contains some categories used by ASP.NET Core and Entity Framework Core, with notes about the logs:

KategoriaCategory UwagiNotes
Microsoft. AspNetCoreMicrosoft.AspNetCore Ogólna Diagnostyka ASP.NET Core.General ASP.NET Core diagnostics.
Microsoft. AspNetCore. dataprotectionMicrosoft.AspNetCore.DataProtection Które klucze zostały wzięte pod uwagę, znaleziono i użyte.Which keys were considered, found, and used.
Microsoft. AspNetCore. HostFilteringMicrosoft.AspNetCore.HostFiltering Dozwolone hosty.Hosts allowed.
Microsoft. AspNetCore. hostingMicrosoft.AspNetCore.Hosting Jak długo trwa wykonywanie żądań HTTP i czas ich uruchomienia.How long HTTP requests took to complete and what time they started. Które hostowanie zestawów uruchamiania zostało załadowane.Which hosting startup assemblies were loaded.
Microsoft. AspNetCore. MVCMicrosoft.AspNetCore.Mvc MVC i Razor Diagnostyka.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 Informacje o trasie.Route matching information.
Microsoft. AspNetCore. ServerMicrosoft.AspNetCore.Server Reagowanie na uruchamianie, zatrzymywanie i utrzymywanie aktywności.Connection start, stop, and keep alive responses. Informacje o certyfikacie HTTPS.HTTPS certificate information.
Microsoft. AspNetCore. StaticFilesMicrosoft.AspNetCore.StaticFiles Obsługiwane pliki.Files served.
Microsoft. EntityFrameworkCoreMicrosoft.EntityFrameworkCore Ogólna Diagnostyka Entity Framework Core.General Entity Framework Core diagnostics. Aktywność i Konfiguracja bazy danych, wykrywanie zmian, migracje.Database activity and configuration, change detection, migrations.

Aby wyświetlić więcej kategorii w oknie konsoli, należy ustawić appsettings.Development.jsna następujące elementy:To view more categories in the console window, set appsettings.Development.json to the following:

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

Zakresy dziennikaLog scopes

Zakres może grupować zestaw operacji logicznych.A scope can group a set of logical operations. Takie grupowanie może służyć do dołączania tych samych danych do każdego dziennika, który został utworzony 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 w ramach przetwarzania transakcji może zawierać identyfikator transakcji.For example, every log created as part of processing a transaction can include the transaction ID.

Zakres:A scope:

Następujące dostawcy obsługują zakresy:The following providers support scopes:

Użyj zakresu przez Zawijanie wywołań rejestratora w using bloku:Use a scope by wrapping logger calls in a using block:

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

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

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

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

    return ItemToDTO(todoItem);
}

Poniższy kod JSON włącza zakresy dla dostawcy konsoli:The following JSON enables scopes for the console provider:

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

Poniższy kod włącza zakresy dla dostawcy konsoli:The following code enables scopes for the console provider:

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

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

Ogólnie rzecz biorąc, rejestrowanie powinno być określone w konfiguracji, a nie w kodzie.Generally, logging should be specified in configuration and not code.

Wbudowani dostawcy rejestrowaniaBuilt-in logging providers

ASP.NET Core obejmuje następujących dostawców rejestrowania:ASP.NET Core includes the following logging providers:

Aby uzyskać informacje dotyczące stdout rejestrowania i debugowania przy użyciu modułu ASP.NET Core, zobacz Rozwiązywanie problemów ASP.NET Core na Azure App Service i usługach IIS i Moduł ASP.NET Core .For information on stdout and debug logging with the ASP.NET Core Module, see Rozwiązywanie problemów ASP.NET Core na Azure App Service i usługach IIS and Moduł ASP.NET Core.

KonsolaConsole

ConsoleDostawca rejestruje dane wyjściowe w konsoli programu.The Console provider logs output to the console. Aby uzyskać więcej informacji na temat wyświetlania Console dzienników w programie Development, zobacz Rejestrowanie danych wyjściowych z uruchamiania programu dotnet i programu Visual Studio.For more information on viewing Console logs in development, see Logging output from dotnet run and Visual Studio.

DebugowanieDebug

DebugDostawca zapisuje dane wyjściowe dziennika za pomocą klasy System. Diagnostics. Debug .The Debug provider writes log output by using the System.Diagnostics.Debug class. Wywołania do System.Diagnostics.Debug.WriteLine zapisu dla Debug dostawcy.Calls to System.Diagnostics.Debug.WriteLine write to the Debug provider.

W systemie Linux Debug Lokalizacja dziennika dostawcy jest zależna od dystrybucji i może być jedną z następujących czynności:On Linux, the Debug provider log location is distribution-dependent and may be one of the following:

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

Źródło zdarzeńEvent Source

EventSourceDostawca zapisuje do międzyplatformowego źródła zdarzeń o nazwie Microsoft-Extensions-Logging .The EventSource provider writes to a cross-platform event source with the name Microsoft-Extensions-Logging. W systemie Windows Dostawca używa funkcji ETW.On Windows, the provider uses ETW.

narzędzia śledzenia dotnetdotnet trace tooling

Narzędzie do śledzenia dotnet to międzyplatformowe narzędzie globalne interfejsu wiersza polecenia, które umożliwia zbieranie śladów programu .NET Core uruchomionego procesu.The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process. Narzędzie zbiera Microsoft.Extensions.Logging.EventSource dane dostawcy za pomocą LoggingEventSource .The tool collects Microsoft.Extensions.Logging.EventSource provider data using a LoggingEventSource.

Aby uzyskać instrukcje dotyczące instalacji, zobacz dotnet-Trace .See dotnet-trace for installation instructions.

Użyj narzędzi śledzenia dotnet, aby zebrać ślad z aplikacji:Use the dotnet trace tooling to collect a trace from an app:

  1. Uruchom aplikację za pomocą dotnet run polecenia.Run the app with the dotnet run command.

  2. Określ identyfikator procesu (PID) aplikacji .NET Core:Determine the process identifier (PID) of the .NET Core app:

    Znajdź identyfikator PID procesu, który ma taką samą nazwę jak zestaw aplikacji.Find the PID for the process that has the same name as the app's assembly.

  3. Wykonaj dotnet trace polecenie.Execute the dotnet trace command.

    Ogólna składnia poleceń: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}\"
    

    W przypadku korzystania z powłoki poleceń programu PowerShell należy ująć --providers wartość w apostrofy ( ' ):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}\"'
    

    Na platformach innych niż Windows Dodaj opcję, -f speedscope Aby zmienić format wyjściowego pliku śledzenia na speedscope .On non-Windows platforms, add the -f speedscope option to change the format of the output trace file to speedscope.

    Słowo kluczoweKeyword OpisDescription
    11 Rejestruj meta zdarzenia dotyczące LoggingEventSource .Log meta events about the LoggingEventSource. Nie rejestruje zdarzeń z ILogger ).Doesn't log events from ILogger).
    22 Włącza zdarzenie, Message gdy ILogger.Log() jest wywoływana.Turns on the Message event when ILogger.Log() is called. Zawiera informacje w sposób programistyczny (nie sformatowany).Provides information in a programmatic (not formatted) way.
    44 Włącza zdarzenie, FormatMessage gdy ILogger.Log() jest wywoływana.Turns on the FormatMessage event when ILogger.Log() is called. Udostępnia sformatowaną wersję ciągu informacji.Provides the formatted string version of the information.
    88 Włącza zdarzenie, MessageJson gdy ILogger.Log() jest wywoływana.Turns on the MessageJson event when ILogger.Log() is called. Zawiera reprezentację argumentów w formacie JSON.Provides a JSON representation of the arguments.
    Poziom zdarzeniaEvent Level OpisDescription
    00 LogAlways
    11 Critical
    22 Error
    33 Warning
    44 Informational
    55 Verbose

    FilterSpecswpisy dla {Logger Category} i {Event Level} przedstawiają dodatkowe warunki filtrowania dzienników.FilterSpecs entries for {Logger Category} and {Event Level} represent additional log filtering conditions. Oddzielaj FilterSpecs wpisy średnikami ( ; ).Separate FilterSpecs entries with a semicolon (;).

    Przykład użycia powłoki poleceń systemu Windows (Brak pojedynczego cudzysłowu wokół --providers wartości):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\"
    

    Poprzednie polecenie aktywuje:The preceding command activates:

    • Rejestrator źródła zdarzeń do tworzenia sformatowanych ciągów ( 4 ) dla błędów ( 2 ).The Event Source logger to produce formatted strings (4) for errors (2).
    • Microsoft.AspNetCore.HostingRejestrowanie na Informational poziomie rejestrowania ( 4 ).Microsoft.AspNetCore.Hosting logging at the Informational logging level (4).
  4. Zatrzymaj narzędzia śledzenia dotnet, naciskając klawisz ENTER lub CTRL + C.Stop the dotnet trace tooling by pressing the Enter key or Ctrl+C.

    Ślad jest zapisywany z nazwą Trace. webtrace w folderze, w którym dotnet trace jest wykonywane polecenie.The trace is saved with the name trace.nettrace in the folder where the dotnet trace command is executed.

  5. Otwórz ślad z Narzędzia PerfView.Open the trace with Perfview. Otwórz plik Trace. webtrace i zbadaj zdarzenia śledzenia.Open the trace.nettrace file and explore the trace events.

Jeśli aplikacja nie kompiluje hosta za pomocą programu CreateDefaultBuilder , Dodaj dostawcę źródła zdarzeń do konfiguracji rejestrowania aplikacji.If the app doesn't build the host with CreateDefaultBuilder, add the Event Source provider to the app's logging configuration.

Aby uzyskać więcej informacji, zobacz:For more information, see:

Narzędzia PerfViewPerfview

Użyj Narzędzia Narzędzia PerfView do zbierania i wyświetlania dzienników.Use the PerfView utility to collect and view logs. Istnieją inne narzędzia do wyświetlania dzienników ETW, ale narzędzia PerfView zapewnia najlepsze środowisko pracy z zdarzeniami ETW emitowanymi przez ASP.NET Core.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.

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

Dziennik zdarzeń systemu WindowsWindows EventLog

EventLogDostawca wysyła dane wyjściowe dziennika do dziennika zdarzeń systemu Windows.The EventLog provider sends log output to the Windows Event Log. W przeciwieństwie do innych dostawców EventLog dostawca nie dziedziczy not domyślnych ustawień nienależących do dostawcy.Unlike the other providers, the EventLog provider does not inherit the default non-provider settings. Jeśli EventLog nie określono ustawień dziennika, domyślnie ustawiana jest wartość LogLevel. Warning.If EventLog log settings aren't specified, they default to LogLevel.Warning.

Aby rejestrować zdarzenia mniejsze niż LogLevel.Warning , jawnie ustaw poziom dziennika.To log events lower than LogLevel.Warning, explicitly set the log level. Poniższy przykład ustawia domyślny poziom dziennika dziennika zdarzeń LogLevel.Information :The following example sets the Event Log default log level to LogLevel.Information:

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

Przeciążania addeventlog można przekazać EventLogSettings .AddEventLog overloads can pass in EventLogSettings. Jeśli null lub nie zostanie określony, są używane następujące ustawienia domyślne:If null or not specified, the following default settings are used:

  • LogName: "Aplikacja"LogName: "Application"
  • SourceName: "Środowisko uruchomieniowe platformy .NET"SourceName: ".NET Runtime"
  • MachineName: Nazwa komputera lokalnego jest używana.MachineName: The local machine name is used.

Poniższy kod zmienia SourceName wartość domyślną na ".NET Runtime" MyLogs :The following code changes the SourceName from the default value of ".NET Runtime" to MyLogs:

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

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

Azure App ServiceAzure App Service

Pakiet Microsoft. Extensions. Logging. AzureAppServices Provider zapisuje dzienniki w plikach tekstowych w systemie plików aplikacji Azure App Service i w usłudze BLOB Storage 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 nie jest uwzględniony w udostępnionej infrastrukturze.The provider package isn't included in the shared framework. Aby użyć dostawcy, Dodaj pakiet dostawcy do projektu.To use the provider, add the provider package to the project.

Aby skonfigurować ustawienia dostawcy, użyj AzureFileLoggerOptions i AzureBlobLoggerOptions , jak pokazano w następującym przykładzie:To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

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

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

Po wdrożeniu do Azure App Service aplikacja korzysta z ustawień w sekcji dzienniki App Service na stronie App Service Azure Portal.When deployed to Azure App Service, the app uses the settings in the App Service logs section of the App Service page of the Azure portal. Po zaktualizowaniu następujących ustawień zmiany zaczynają obowiązywać natychmiast, bez konieczności ponownego uruchomienia lub ponownej wdrożenia aplikacji.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Rejestrowanie aplikacji (system plików)Application Logging (Filesystem)
  • Rejestrowanie aplikacji (BLOB)Application Logging (Blob)

Domyślną lokalizacją plików dziennika jest folder D: \ Home \ \ LogFiles , a domyślna nazwa pliku to 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. Domyślny limit rozmiaru pliku wynosi 10 MB, a domyślna maksymalna liczba zachowywanych plików to 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Domyślną nazwą obiektu BLOB jest {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.

Ten dostawca rejestruje się tylko wtedy, gdy projekt jest uruchomiony w środowisku platformy Azure.This provider only logs when the project runs in the Azure environment.

Przesyłanie strumieniowe dzienników AzureAzure log streaming

Przesyłanie strumieniowe w usłudze Azure log obsługuje wyświetlanie dziennika w czasie rzeczywistym z:Azure log streaming supports viewing log activity in real time from:

  • Serwer aplikacjiThe app server
  • Serwer sieci WebThe web server
  • Śledzenie nieudanych żądańFailed request tracing

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

  • Przejdź do strony dzienników App Service ze strony portalu aplikacji.Navigate to the App Service logs page from the app's portal page.
  • Ustaw Rejestrowanie aplikacji (system plików) na włączone.Set Application Logging (Filesystem) to On.
  • Wybierz poziomdziennika.Choose the log Level. To ustawienie dotyczy tylko przesyłania strumieniowego dzienników Azure.This setting only applies to Azure log streaming.

Przejdź do strony strumień dziennika , aby wyświetlić dzienniki.Navigate to the Log Stream page to view logs. Zarejestrowane komunikaty są rejestrowane przy użyciu ILogger interfejsu.The logged messages are logged with the ILogger interface.

Azure Application InsightsAzure Application Insights

Pakiet Microsoft. Extensions. Logging. ApplicationInsights Provider zapisuje dzienniki na platformie Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights to usługa, która monitoruje aplikację internetową i udostępnia narzędzia do wykonywania zapytań i analizowania danych telemetrycznych.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Jeśli używasz tego dostawcy, możesz wysyłać zapytania i analizować dzienniki przy użyciu narzędzi Application Insights.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

Dostawca rejestrowania jest dołączony jako zależność Microsoft. ApplicationInsights. AspNetCore, który jest pakietem, który zapewnia wszystkie dostępne dane telemetryczne dla ASP.NET Core.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. Jeśli używasz tego pakietu, nie musisz instalować pakietu dostawcy.If you use this package, you don't have to install the provider package.

Pakiet Microsoft. ApplicationInsights. Web jest przeznaczony dla ASP.NET 4. x, a nie ASP.NET Core.The Microsoft.ApplicationInsights.Web package is for ASP.NET 4.x, not ASP.NET Core.

Więcej informacji można znaleźć w następujących zasobach:For more information, see the following resources:

Dostawcy rejestrowania innych firmThird-party logging providers

Platformy rejestrowania innych firm, które współpracują z ASP.NET Core:Third-party logging frameworks that work with ASP.NET Core:

Niektóre struktury innych firm mogą wykonywać Rejestrowanie semantyczne, znane także jako rejestrowanie strukturalne.Some third-party frameworks can perform semantic logging, also known as structured logging.

Korzystanie z struktury innej firmy jest podobne do korzystania z jednego 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ływanie ILoggerFactory metody rozszerzenia dostarczonej przez strukturę rejestrowania.Call an ILoggerFactory extension method provided by the logging framework.

Aby uzyskać więcej informacji, zobacz dokumentację każdego dostawcy.For more information, see each provider's documentation. Dostawcy rejestrowania innych firm nie są obsługiwani przez firmę Microsoft.Third-party logging providers aren't supported by Microsoft.

Aplikacja konsolowa niebędąca hostemNon-host console app

Przykład korzystania z hosta ogólnego w aplikacji konsolowej innej niż sieci Web można znaleźć w pliku program.cs zadania w tle ( Zadania w tle z usługami hostowanymi w 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 (Zadania w tle z usługami hostowanymi w ASP.NET Core).

Rejestrowanie kodu dla aplikacji bez hosta ogólnego różni się w sposób, w jaki są dodawane dostawcy i są tworzone rejestratory.Logging code for apps without Generic Host differs in the way providers are added and loggers are created.

Dostawcy rejestrowaniaLogging providers

W aplikacji konsolowej innej niż host Wywołaj Add{provider name} metodę rozszerzenia dostawcy podczas tworzenia LoggerFactory :In a non-host console app, call the provider's Add{provider name} extension method while creating a LoggerFactory:

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

Tworzenie dziennikówCreate logs

Aby utworzyć dzienniki, użyj ILogger<TCategoryName> obiektu.To create logs, use an ILogger<TCategoryName> object. Użyj, LoggerFactory Aby utworzyć ILogger .Use the LoggerFactory to create an ILogger.

Poniższy przykład tworzy Rejestrator przy użyciu LoggingConsoleApp.Program jako kategorii.The following example creates a logger with LoggingConsoleApp.Program as the category.

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

W następujących przykładowych ASP.NET podstawowych, Rejestrator jest używany do tworzenia dzienników Information jako poziom.In the following ASP.NET CORE examples, the logger is used to create logs with Information as the level. Poziom dziennika wskazuje ważność rejestrowanego zdarzenia.The Log level indicates the severity of the logged event.

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

Poziomy i Kategorie zostały omówione bardziej szczegółowo w tym dokumencie.Levels and categories are explained in more detail in this document.

Rejestruj podczas konstruowania hostaLog during host construction

Rejestrowanie podczas konstruowania hosta nie jest bezpośrednio obsługiwane.Logging during host construction isn't directly supported. Można jednak użyć osobnego rejestratora.However, a separate logger can be used. W poniższym przykładzie jest używany Rejestrator Serilog do logowania CreateHostBuilder .In the following example, a Serilog logger is used to log in CreateHostBuilder. AddSerilogużywa konfiguracji statycznej określonej w Log.Logger :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();
        }
    }
}

Konfigurowanie usługi, która zależy od ILoggerConfigure a service that depends on ILogger

Wstrzykiwanie konstruktora rejestratora do Startup działa we wcześniejszych wersjach ASP.NET Core, ponieważ dla hosta sieci Web jest tworzony oddzielny kontener di.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. Aby uzyskać informacje o tym, dlaczego dla hosta generycznego jest tworzony tylko jeden kontener, zobacz zawiadomienie o rozdzieleniu zmian.For information about why only one container is created for the Generic Host, see the breaking change announcement.

Aby skonfigurować usługę, która jest zależna od ILogger<T> programu, należy użyć iniekcji konstruktora lub dostarczyć metody fabryki.To configure a service that depends on ILogger<T>, use constructor injection or provide a factory method. Podejście metody fabryki jest zalecane tylko wtedy, gdy nie ma żadnych innych opcji.The factory method approach is recommended only if there is no other option. Rozważmy na przykład usługę, która wymaga ILogger<T> wystąpienia przez di:For example, consider a service that needs an ILogger<T> instance provided by DI:

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

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

Poprzedni wyróżniony kod jest obiektem, który jest uruchamiany po raz pierwszy, musi utworzyć wystąpienie MyService .The preceding highlighted code is a Func that runs the first time the DI container needs to construct an instance of MyService. W ten sposób można uzyskać dostęp do dowolnych zarejestrowanych usług.You can access any of the registered services in this way.

Tworzenie dzienników w głównejCreate logs in Main

Następujący kod jest zarejestrowana Main przez pobranie ILogger wystąpienia z programu di po skompilowaniu hosta:The following code logs in Main by getting an ILogger instance from DI after building the host:

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

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

    host.Run();
}

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

Tworzenie dzienników w programie startowymCreate logs in Startup

Poniższy kod zapisuje dzienniki w Startup.Configure :The following code writes logs in Startup.Configure:

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

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

    app.UseRouting();

    app.UseAuthorization();

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

Zapisywanie dzienników przed ukończeniem instalacji programu DI Container w Startup.ConfigureServices metodzie nie jest obsługiwane:Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not supported:

  • Iniekcja rejestratora do Startup konstruktora nie jest obsługiwana.Logger injection into the Startup constructor is not supported.
  • Iniekcja rejestratora do Startup.ConfigureServices sygnatury metody nie jest obsługiwanaLogger injection into the Startup.ConfigureServices method signature is not supported

Przyczyną tego ograniczenia jest to, że rejestrowanie jest zależne od typu i konfiguracji, która z tego powodu zależy od DI.The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on DI. Kontener DI nie jest ustawiany do momentu ConfigureServices zakończenia.The DI container isn't set up until ConfigureServices finishes.

Aby uzyskać informacje na temat konfigurowania usługi, która zależy od ILogger<T> lub dlaczego wstrzyknięcie konstruktora rejestratora do Startup pracy we wcześniejszych wersjach, zobacz Konfigurowanie usługi, która jest zależna od ILoggerFor information on configuring a service that depends on ILogger<T> or why constructor injection of a logger into Startup worked in earlier versions, see Configure a service that depends on ILogger

Brak metod rejestratora asynchronicznegoNo asynchronous logger methods

Rejestracja powinna być tak szybka, że nie jest to koszt 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 wolny, nie zapisuj go bezpośrednio.If a logging data store is slow, don't write to it directly. Rozważ ręczne zapisanie komunikatów dziennika w szybkim magazynie, a następnie przeniesienie ich do wolnego magazynu później.Consider writing the log messages to a fast store initially, then moving them to the slow store later. Na przykład podczas rejestrowania do SQL Server nie należy tego robić bezpośrednio w Log metodzie, ponieważ Log metody są synchroniczne.For example, when logging to SQL Server, don't do so directly in a Log method, since the Log methods are synchronous. Zamiast tego można synchronicznie dodawać komunikaty dziennika do kolejki w pamięci, a proces roboczy w tle ściągał komunikaty z kolejki, aby wykonać asynchroniczne działanie wypychania danych do SQL Server.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. Aby uzyskać więcej informacji, zobacz ten problem w serwisie GitHub.For more information, see this GitHub issue.

Zmień poziomy dziennika w działającej aplikacjiChange log levels in a running app

Interfejs API rejestrowania nie zawiera scenariusza zmiany poziomów rejestrowania, gdy aplikacja jest uruchomiona.The Logging API doesn't include a scenario to change log levels while an app is running. Niektórzy dostawcy konfiguracji mogą jednak ponownie ładować konfigurację, która zacznie natychmiastowo wpływać na konfigurację rejestrowania.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. Na przykład dostawca konfiguracji plikówponownie ładuje konfigurację rejestrowania.For example, the File Configuration Provider, reloads logging configuration by default. Jeśli konfiguracja zostanie zmieniona w kodzie w czasie, gdy aplikacja jest uruchomiona, aplikacja może wywołać IConfigurationRoot. reload , aby zaktualizować konfigurację rejestrowania aplikacji.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

ILogger i ILoggerFactoryILogger and ILoggerFactory

ILogger<TCategoryName>Interfejsy i ILoggerFactory i implementacje są zawarte w zestaw .NET Core SDK.The ILogger<TCategoryName> and ILoggerFactory interfaces and implementations are included in the .NET Core SDK. Są one również dostępne w następujących pakietach NuGet:They are also available in the following NuGet packages:

Zastosuj reguły filtru dziennika w kodzieApply log filter rules in code

Preferowanym podejściem do ustawiania reguł filtru dziennika jest użycie konfiguracji.The preferred approach for setting log filter rules is by using Configuration.

Poniższy przykład pokazuje, jak zarejestrować reguły filtru w kodzie:The following example shows how to register filter rules in code:

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

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

logging.AddFilter("System", LogLevel.Debug)Określa System kategorię i poziom dziennika Debug .logging.AddFilter("System", LogLevel.Debug) specifies the System category and log level Debug. Filtr jest stosowany do wszystkich dostawców, ponieważ określony dostawca nie został skonfigurowany.The filter is applied to all providers because a specific provider was not configured.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)określającAddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) specifies:

  • DebugDostawca rejestrowania.The Debug logging provider.
  • Poziom dziennika Information lub wyższy.Log level Information and higher.
  • Wszystkie kategorie zaczynające się od "Microsoft" .All categories starting with "Microsoft".

Tworzenie rejestratora niestandardowegoCreate a custom logger

Aby dodać niestandardowy rejestrator, Dodaj element ILoggerProvider with ILoggerFactory :To add a custom logger, add an ILoggerProvider with ILoggerFactory:

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

ILoggerProviderTworzy co najmniej jedno ILogger wystąpienie.The ILoggerProvider creates one or more ILogger instances. ILoggerWystąpienia są używane przez platformę do rejestrowania informacji.The ILogger instances are used by the framework to log the information.

Przykładowa konfiguracja rejestratora niestandardowegoSample custom logger configuration

Przykład:The sample:

  • Został zaprojektowany jako bardzo podstawowy przykład, który ustawia kolor konsoli dziennika według identyfikatora zdarzenia i poziomu dziennika.Is designed to be a very basic sample that sets the color of the log console by event ID and log level. Rejestratory zazwyczaj nie zmieniają się według identyfikatora zdarzenia i nie są specyficzne dla poziomu dziennika.Loggers generally don't change by event ID and are not specific to log level.
  • Tworzy różne wpisy konsoli kolorów dla każdego poziomu dziennika i identyfikatora zdarzenia przy użyciu następującego typu konfiguracji:Creates different color console entries per log level and event ID using the following configuration type:
public class ColorConsoleLoggerConfiguration
{
    public LogLevel LogLevel { get; set; } = LogLevel.Warning;
    public int EventId { get; set; } = 0;
    public ConsoleColor Color { get; set; } = ConsoleColor.Yellow;
}

Poprzedni kod ustawia poziom domyślny na Warning i kolor Yellow .The preceding code sets the default level to Warning and the color to Yellow. Jeśli wartość EventId jest równa 0, będziemy rejestrować wszystkie zdarzenia.If the EventId is set to 0, we will log all events.

Tworzenie rejestratora niestandardowegoCreate the custom logger

ILoggerNazwa kategorii implementacji jest zwykle źródłem rejestrowania.The ILogger implementation category name is typically the logging source. Na przykład typ, w którym jest tworzony Rejestrator:For example, the type where the logger is created:

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

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

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

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

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

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

Powyższy kod ma następujące działanie:The preceding code:

  • Tworzy wystąpienie rejestratora na nazwę kategorii.Creates a logger instance per category name.
  • Sprawdza logLevel == _config.LogLevel IsEnabled , czy każdy z nich logLevel ma unikatowy rejestrator.Checks logLevel == _config.LogLevel in IsEnabled, so each logLevel has a unique logger. Ogólnie rzecz biorąc, rejestratory powinny również być włączone dla wszystkich wyższych poziomów dzienników:Generally, loggers should also be enabled for all higher log levels:
public bool IsEnabled(LogLevel logLevel)
{
    return logLevel >= _config.LogLevel;
}

Tworzenie niestandardowego LoggerProviderCreate the custom LoggerProvider

LoggerProviderJest klasą, która tworzy wystąpienia rejestratora.The LoggerProvider is the class that creates the logger instances. Być może nie jest to konieczne do utworzenia wystąpienia rejestratora dla kategorii, ale jest to zrozumiałe dla niektórych rejestratorów, takich jak NLog lub log4net.Maybe it is not needed to create a logger instance per category, but this makes sense for some Loggers, like NLog or log4net. W tym celu można również wybrać różne docelowe dane wyjściowe rejestrowania według kategorii, jeśli jest to konieczne:Doing this you are also able to choose different logging output targets per category if needed:

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

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

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

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

W powyższym kodzie CreateLogger tworzy pojedyncze wystąpienie dla ColorConsoleLogger nazwy kategorii i zapisuje je w ConcurrentDictionary<TKey,TValue> ;In the preceding code, CreateLogger creates a single instance of the ColorConsoleLogger per category name and stores it in the ConcurrentDictionary<TKey,TValue>;

Użycie i rejestracja rejestratora niestandardowegoUsage and registration of the custom logger

Zarejestruj rejestrator w Startup.Configure :Register the logger in the Startup.Configure:

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

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

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

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

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

    app.UseRouting();

    app.UseAuthorization();

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

Dla poprzedniego kodu, należy podać co najmniej jedną metodę rozszerzającą dla ILoggerFactory :For the preceding code, provide at least one extension method for the ILoggerFactory:

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

Zasoby dodatkoweAdditional resources

Autorzy Dykstra i Steve SmithBy Tom Dykstra and Steve Smith

Platforma .NET Core obsługuje interfejs API rejestrowania, który współpracuje z różnymi dostawcami rejestrowania wbudowanych i innych firm..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. W tym artykule pokazano, jak używać interfejsu API rejestrowania z wbudowanymi dostawcami.This article shows how to use the logging API with built-in providers.

Wyświetl lub pobierz przykładowy kod (jak pobrać)View or download sample code (how to download)

Dodaj dostawcówAdd providers

Dostawca rejestrowania wyświetla lub przechowuje dzienniki.A logging provider displays or stores logs. Na przykład dostawca konsoli wyświetla dzienniki w konsoli programu, a Dostawca usługi Azure Application Insights przechowuje je na platformie 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 przez dodanie wielu dostawców.Logs can be sent to multiple destinations by adding multiple providers.

Aby dodać dostawcę, wywołaj Add{provider name} metodę rozszerzenia dostawcy 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) =>
        {
            // Requires `using Microsoft.Extensions.Logging;`
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

Poprzedzający kod wymaga odwołania do Microsoft.Extensions.Logging i Microsoft.Extensions.Configuration .The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration.

Domyślne wywołania szablonu projektu CreateDefaultBuilder , które dodaje następujących dostawców rejestrowania:The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • KonsolaConsole
  • DebugowanieDebug
  • EventSource (rozpoczęcie w 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>();

Jeśli używasz programu CreateDefaultBuilder , możesz zastąpić domyślnych dostawców własnymi opcjami.If you use CreateDefaultBuilder, you can replace the default providers with your own choices. Wywołaj ClearProviders i Dodaj żądanych dostawców.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();
        });

Więcej informacji na temat wbudowanych dostawców rejestrowania i dostawców rejestrowania innych firm znajduje się w dalszej części artykułu.Learn more about built-in logging providers and third-party logging providers later in the article.

Tworzenie dziennikówCreate logs

Aby utworzyć dzienniki, użyj ILogger<TCategoryName> obiektu.To create logs, use an ILogger<TCategoryName> object. W aplikacji sieci Web lub hostowanej usłudze Pobierz ILogger od iniekcji zależności (di).In a web app or hosted service, get an ILogger from dependency injection (DI). W aplikacjach konsolowych innych niż host Użyj programu, LoggerFactory Aby utworzyć ILogger .In non-host console apps, use the LoggerFactory to create an ILogger.

Poniższy ASP.NET Core przykład tworzy Rejestrator przy użyciu TodoApiSample.Pages.AboutModel jako kategorii.The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category. Kategoria dziennika jest ciągiem, który jest skojarzony z każdym dziennikiem.The log category is a string that is associated with each log. ILogger<T>Wystąpienie zapewniane przez program di tworzy dzienniki, które mają w pełni kwalifikowaną nazwę typu T jako kategorię.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;
    }

W poniższych przykładach ASP.NET Core i aplikacji konsoli Rejestrator służy do tworzenia dzienników z użyciem Information jako poziom.In the following ASP.NET Core and console app examples, the logger is used to create logs with Information as the level. Poziom dziennika wskazuje ważność rejestrowanego zdarzenia.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);
}

Poziomy i Kategorie zostały wyjaśnione bardziej szczegółowo w dalszej części tego artykułu.Levels and categories are explained in more detail later in this article.

Tworzenie dzienników w programie startowymCreate logs in Startup

Aby napisać dzienniki w Startup klasie, Dołącz ILogger parametr do 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()
            .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();
    }
}

Tworzenie dzienników w klasie programuCreate logs in the Program class

Aby napisać dzienniki w Program klasie, Pobierz ILogger wystąpienie z elementu di: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();
        });

Rejestrowanie podczas konstruowania hosta nie jest bezpośrednio obsługiwane.Logging during host construction isn't directly supported. Można jednak użyć osobnego rejestratora.However, a separate logger can be used. W poniższym przykładzie jest używany Rejestrator Serilog do logowania CreateWebHostBuilder .In the following example, a Serilog logger is used to log in CreateWebHostBuilder. AddSerilogużywa konfiguracji statycznej określonej w Log.Logger :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();
        }
    }
}

Brak metod rejestratora asynchronicznegoNo asynchronous logger methods

Rejestracja powinna być tak szybka, że nie jest to koszt 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 wolny, nie zapisuj go bezpośrednio.If your logging data store is slow, don't write to it directly. Najpierw Rozważ zapisanie komunikatów dziennika do szybkiego sklepu, a następnie przeniesienie ich do wolnego magazynu później.Consider writing the log messages to a fast store initially, then move them to the slow store later. Na przykład jeśli rejestrujesz się do SQL Server, nie chcesz tego robić bezpośrednio w Log metodzie, ponieważ Log metody są synchroniczne.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. Zamiast tego można synchronicznie dodawać komunikaty dziennika do kolejki w pamięci, a proces roboczy w tle ściągał komunikaty z kolejki, aby wykonać asynchroniczne działanie wypychania danych do SQL Server.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. Aby uzyskać więcej informacji, zobacz ten problem w serwisie GitHub.For more information, see this GitHub issue.

KonfigurowanieConfiguration

Konfiguracja dostawcy rejestrowania jest świadczona przez co najmniej jednego dostawcę 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 platformy .NET w pamięci.In-memory .NET objects.
  • Magazyn niezaszyfrowanego klucza tajnego .The unencrypted Secret Manager storage.
  • Zaszyfrowany magazyn użytkowników, taki jak Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Dostawcy niestandardowi (instalowani lub utworzony).Custom providers (installed or created).

Na przykład konfiguracja rejestrowania jest zwykle dostarczana przez Logging sekcję plików ustawień aplikacji.For example, logging configuration is commonly provided by the Logging section of app settings files. Poniższy przykład pokazuje zawartość typowego appsettings.Development.jsw 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
    }
  }
}

LoggingWłaściwość może mieć LogLevel właściwości dostawcy dzienników i.The Logging property can have LogLevel and log provider properties (Console is shown).

LogLevelWłaściwość w obszarze Logging określa minimalny poziom rejestrowania wybranych kategorii.The LogLevel property under Logging specifies the minimum level to log for selected categories. W przykładzie, System i Microsoft Kategorie są rejestrowane na Information poziomie, a wszystkie inne logowania na Debug poziomie.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 dostawców rejestrowania.Other properties under Logging specify logging providers. Przykład dotyczy dostawcy konsoli.The example is for the Console provider. Jeśli dostawca obsługuje zakresy rejestrowania, IncludeScopes wskazuje, czy są one włączone.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Właściwość dostawcy (taka jak Console w przykładzie) może także określić LogLevel Właściwość.A provider property (such as Console in the example) may also specify a LogLevel property. LogLevelw obszarze dostawca Określa poziomy do rejestrowania dla tego dostawcy.LogLevel under a provider specifies levels to log for that provider.

Jeśli w programie są określone poziomy Logging.{providername}.LogLevel , zastępują one wszystko ustawione w Logging.LogLevel .If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel. Rozważmy na przykład następujące dane JSON:For example, consider the following JSON:

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

W powyższym kodzie JSON Console Ustawienia dostawcy przesłaniają poprzedni poziom dziennika (domyślnie).In the preceding JSON, the Console provider settings overrides the preceding (default) log level.

Interfejs API rejestrowania nie zawiera scenariusza zmiany poziomów rejestrowania, gdy aplikacja jest uruchomiona.The Logging API doesn't include a scenario to change log levels while an app is running. Niektórzy dostawcy konfiguracji mogą jednak ponownie ładować konfigurację, która zacznie natychmiastowo wpływać na konfigurację rejestrowania.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. Na przykład dostawca konfiguracji plików, który jest dodawany przez program CreateDefaultBuilder do odczytu plików ustawień, ponownie ładuje konfigurację rejestrowania domyślnie.For example, the File Configuration Provider, which is added by CreateDefaultBuilder to read settings files, reloads logging configuration by default. Jeśli konfiguracja zostanie zmieniona w kodzie w czasie, gdy aplikacja jest uruchomiona, aplikacja może wywołać IConfigurationRoot. reload , aby zaktualizować konfigurację rejestrowania aplikacji.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

Informacje o implementowaniu dostawców konfiguracji znajdują się w temacie Konfiguracja w ASP.NET Core .For information on implementing configuration providers, see Konfiguracja w ASP.NET Core.

Przykładowe dane wyjściowe rejestrowaniaSample logging output

W przypadku przykładowego kodu podanego w poprzedniej sekcji Dzienniki są wyświetlane w konsoli programu, gdy aplikacja jest uruchamiana z 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

Poprzednie dzienniki zostały wygenerowane przez utworzenie żądania HTTP GET do przykładowej aplikacji w lokalizacji 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 tych samych dzienników, które są wyświetlane w oknie debugowania podczas uruchamiania przykładowej aplikacji 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 utworzone przez ILogger wywołania pokazane w poprzedniej sekcji zaczynają się od "TodoApi".The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi". Dzienniki zaczynające się od kategorii "Microsoft" pochodzą z kodu ASP.NET Core Framework.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core i kod aplikacji używają tego samego rejestrowania interfejsu API i dostawców.ASP.NET Core and application code are using the same logging API and providers.

W pozostałej 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

ILoggerInterfejsy i ILoggerFactory są w Microsoft. Extensions. Logging. Abstractsi domyślne implementacje dla nich są w 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

Po ILogger utworzeniu obiektu jest dla niego określona Kategoria .When an ILogger object is created, a category is specified for it. Ta kategoria jest dołączona do każdego komunikatu dziennika utworzonego 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 Konwencja ma używać nazwy klasy, takiej 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> Aby uzyskać ILogger wystąpienie używające w pełni kwalifikowanej nazwy typu T jako kategorii: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;
    }

Aby jawnie określić kategorię, wywołaj 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");
    }

ILogger<T>jest odpowiednikiem wywołania CreateLogger z w pełni kwalifikowaną nazwą typu 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. Przykładowo można napisać Information Dziennik, gdy metoda jest zwykle zakończona, a dziennik, Warning gdy metoda zwraca 404, nie znaleziono kodu 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 rejestruje: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);
}

W poprzednim kodzie MyLogEvents.GetItem MyLogEvents.GetItemNotFound Parametry i są identyfikatorem zdarzenia dziennika.In the preceding code, the MyLogEvents.GetItem and MyLogEvents.GetItemNotFound parameters are the Log event ID. Drugi parametr jest szablonem wiadomości z symbolami zastępczymi dla wartości argumentów dostarczonych 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 zostały wyjaśnione w sekcji szablon komunikatu dziennika w tym artykule.The method parameters are explained in the Log message template section in this article.

Metody rejestrowania, które obejmują poziom w nazwie metody (na przykład LogInformation i LogWarning ) są metodami rozszerzającymi dla ILogger.Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. Te metody wywołują Log metodę, która pobiera LogLevel parametr.These methods call a Log method that takes a LogLevel parameter. Metodę można wywołać Log bezpośrednio zamiast jednej z tych metod rozszerzających, ale składnia jest stosunkowo skomplikowana.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 rozszerzeń rejestratora.For more information, see ILogger and the logger extensions source code.

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

  • Ślad = 0Trace = 0

    Aby uzyskać informacje, które są zazwyczaj cenne tylko dla debugowania.For information that's typically valuable only for debugging. Komunikaty te mogą zawierać poufne dane aplikacji, dlatego nie powinny być włączone w środowisku produkcyjnym.These messages may contain sensitive application data and so shouldn't be enabled in a production environment. Domyślnie wyłączona.Disabled by default.

  • Debuguj = 1Debug = 1

    Informacje, które mogą być przydatne podczas tworzenia 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 dzienniki poziomów w środowisku produkcyjnym tylko w przypadku rozwiązywania problemów, ze względu na dużą ilość 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 = 2Information = 2

    Do śledzenia ogólnego przepływu aplikacji.For tracking the general flow of the app. Te dzienniki zwykle mają pewną wartość długoterminową.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

    Dla nietypowych lub nieoczekiwanych zdarzeń w przepływie aplikacji.For abnormal or unexpected events in the app flow. Mogą to być błędy lub inne warunki, które nie powodują zatrzymania aplikacji, ale konieczne może być zbadanie.These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Obsłużone wyjątki są typowym miejscem do korzystania z Warning poziomu 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

    W przypadku błędów i wyjątków, których nie można obsłużyć.For errors and exceptions that cannot be handled. Te komunikaty wskazują niepowodzenie w bieżącym działaniu lub operacji (np. bieżące żądanie HTTP), a nie awaria 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 niepowodzeń, które wymagają natychmiastowej uwagi.For failures that require immediate attention. Przykłady: scenariusze utraty danych, brak miejsca na dysku.Examples: data loss scenarios, out of disk space.

Poziom dziennika służy do kontrolowania, ile danych wyjściowych dziennika jest zapisywana w określonym nośniku lub oknie wyświetlania.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:In production:
    • Rejestrowanie na poziomie Trace za pomocą Information poziomów zapewnia wysoką liczbę szczegółowych komunikatów dziennika.Logging at the Trace through Information levels produces a high-volume of detailed log messages. Aby kontrolować koszty i nie przekraczać limitów magazynowania danych, należy rejestrować Trace Information komunikaty na poziomie w magazynach o wysokim poziomie ilości danych.To control costs and not exceed data storage limits, log Trace through Information level messages to a high-volume, low-cost data store.
    • Rejestrowanie na Warning poziomie Critical poziomów zwykle generuje mniejszą liczbę mniejszych komunikatów dzienników.Logging at Warning through Critical levels typically produces fewer, smaller log messages. W związku z tym koszty i limity magazynu zazwyczaj nie są problemem, co skutkuje większą elastycznością wyboru magazynu danych.Therefore, costs and storage limits usually aren't a concern, which results in greater flexibility of data store choice.
  • Podczas tworzenia:During development:
    • Rejestruj Warning Critical komunikaty w konsoli programu.Log Warning through Critical messages to the console.
    • Dodawanie Trace Information komunikatów podczas rozwiązywania problemów.Add Trace through Information messages when troubleshooting.

W sekcji filtrowanie dzienników w dalszej części tego artykułu wyjaśniono, jak kontrolować poziomy dzienników obsługiwane przez dostawcę.The Log filtering section later in this article explains how to control which log levels a provider handles.

ASP.NET Core zapisuje dzienniki dla zdarzeń struktury.ASP.NET Core writes logs for framework events. Przykłady dzienników znajdujące się wcześniej w tym artykule nie wykluczają dzienników poniżej Information , dlatego nie Debug Trace zostały utworzone dzienniki.The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Oto przykład dzienników konsoli utworzonych przez uruchomienie przykładowej aplikacji skonfigurowanej 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 dziennikaLog event ID

Każdy dziennik może określać Identyfikator zdarzenia.Each log can specify an event ID. Aplikacja Przykładowa wykonuje to przy użyciu lokalnie zdefiniowanej 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;
}

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

Dostawca rejestrowania może przechowywać identyfikator zdarzenia w polu identyfikatora, 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 pokazuje identyfikatorów zdarzeń.The Debug provider doesn't show event IDs. Dostawca konsoli pokazuje identyfikatory zdarzeń w nawiasach 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 komunikatu dziennikaLog message template

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

Kolejność symboli zastępczych, nie ich nazw, określa, które parametry są używane do dostarczania ich wartości.The order of placeholders, not their names, determines which parameters are used to provide their values. W poniższym kodzie Zwróć uwagę, ż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 z wartościami parametrów w kolejności:This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

Struktura rejestrowania działa w ten sposób, aby dostawcy rejestrowania mogli zaimplementować Rejestrowanie semantyczne, znane także jako rejestrowanie strukturalne.The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. Same argumenty są przesyłane do systemu rejestrowania, a nie tylko dla sformatowanego szablonu wiadomości.The arguments themselves are passed to the logging system, not just the formatted message template. Te informacje umożliwiają dostawcom rejestrowania przechowywanie wartości parametrów jako pól.This information enables logging providers to store the parameter values as fields. Na przykład załóżmy, że wywołania metod rejestratora wyglądają następująco:For example, suppose logger method calls look like this:

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

W przypadku wysyłania dzienników do usługi Azure Table Storage każda jednostka tabeli platformy Azure może mieć ID właściwości i RequestTime , które upraszczają zapytania dotyczące 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. Zapytanie może znaleźć wszystkie dzienniki w określonym RequestTime zakresie bez analizowania limitu czasu wiadomości tekstowej.A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

Wyjątki rejestrowaniaLogging exceptions

Metody rejestratora mają przeciążenia umożliwiające przekazanie wyjątku, 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);

Różni dostawcy obsługują informacje o wyjątkach na różne sposoby.Different providers handle the exception information in different ways. Oto przykład danych wyjściowych dostawcy debugowania z kodu pokazanego powyżej.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

Filtrowanie dziennikówLog 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. Wszystkie dzienniki poniżej minimalnego poziomu nie są przesyłane do tego dostawcy, więc nie są wyświetlane ani 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 dziennika.To suppress all logs, specify LogLevel.None as the minimum log level. Wartość całkowita LogLevel.None wynosi 6, która jest większa niż LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Utwórz reguły filtru w konfiguracjiCreate filter rules in configuration

Kod szablonu projektu wywołuje CreateDefaultBuilder w celu skonfigurowania rejestrowania dla dostawców konsoli, debugowania i EventSource (ASP.NET Core 2,2 lub nowszych).The project template code calls CreateDefaultBuilder to set up logging for the Console, Debug, and EventSource (ASP.NET Core 2.2 or later) providers. CreateDefaultBuilderMetoda konfiguruje rejestrowanie, aby wyszukać konfigurację w Logging sekcji, jak wyjaśniono wcześniej w tym artykule.The CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as explained earlier in this article.

Dane konfiguracyjne określają minimalne poziomy dziennika według dostawcy 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ł filtrowania: 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. Dla każdego dostawcy wybierana jest pojedyncza reguła, gdy ILogger tworzony jest obiekt.A single rule is chosen for each provider when an ILogger object is created.

Filtrowanie reguł w kodzieFilter rules in code

Poniższy przykład pokazuje, jak zarejestrować reguły filtru 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));

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

Jak są stosowane reguły filtrowaniaHow filtering rules are applied

Dane konfiguracji i AddFilter kod przedstawiony w powyższych przykładach tworzą reguły pokazane 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ść pochodzi z przykładu konfiguracji, a ostatnie dwa pochodzą z przykładu kodu.The first six come from the configuration example and the last two come from the code example.

LiczbaNumber DostawcaProvider Kategorie zaczynające się od...Categories that begin with ... Minimalny poziom rejestrowaniaMinimum log level
11 DebugowanieDebug Wszystkie kategorieAll categories InformacjeInformation
22 KonsolaConsole Microsoft. AspNetCore. MVC. Razor .. WewnętrzMicrosoft.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 ŚladTrace

Po ILogger utworzeniu obiektu ILoggerFactory obiekt wybiera jedną regułę dla każdego dostawcy, która ma zostać zastosowana 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 zapisywane przez ILogger wystąpienie są filtrowane na podstawie wybranych reguł.All messages written by an ILogger instance are filtered based on the selected rules. Najbardziej konkretną regułą można wybrać dla każdego dostawcy i pary kategorii z dostępnych reguł.The most specific rule possible for each provider and category pair is selected from the available rules.

Następujący algorytm jest używany dla każdego dostawcy, gdy ILogger jest tworzony 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 pasują do dostawcy lub jego aliasu.Select all rules that match the provider or its alias. Jeśli nie zostanie znalezione dopasowanie, zaznacz wszystkie reguły z pustym dostawcą.If no match is found, select all rules with an empty provider.
  • W wyniku poprzedniego kroku wybierz pozycję reguły z najdłuższym prefiksem 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ł, zrób to ostatnie .If multiple rules are selected, take the last one.
  • Jeśli nie wybrano żadnych reguł, użyj MinimumLevel .If no rules are selected, use MinimumLevel.

Na powyższej liście reguł Załóżmy, że tworzysz ILogger obiekt dla kategorii "Microsoft. AspNetCore. MVC. Razor . Razor ViewEngine":With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • Dla dostawcy debugowania obowiązują reguły 1, 6 i 8.For the Debug provider, rules 1, 6, and 8 apply. Reguła 8 jest najbardziej specyficzna, więc jest to jedna wybrana.Rule 8 is most specific, so that's the one selected.
  • W przypadku dostawcy konsoli obowiązują reguły 3, 4, 5 i 6.For the Console provider, rules 3, 4, 5, and 6 apply. Reguła 3 jest najbardziej specyficzna.Rule 3 is most specific.

Wystąpienie wyników ILogger wysyła dzienniki Trace poziomu i powyżej do dostawcy debugowania.The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Dzienniki Debug poziomów i powyżej są wysyłane do dostawcy konsoli.Logs of Debug level and above are sent to the Console provider.

Aliasy dostawcówProvider aliases

Każdy dostawca definiuje alias , który może być używany w konfiguracji zamiast w pełni kwalifikowanej nazwy 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 Użyj następujących aliasów:For the built-in providers, use the following aliases:

  • KonsolaConsole
  • DebugowanieDebug
  • EventSourceEventSource
  • ElemencieEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

Domyślny poziom minimalnyDefault minimum level

Istnieje ustawienie minimalnego poziomu, które działa tylko wtedy, gdy nie mają zastosowania żadne reguły z konfiguracji lub kodu 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ć poziom minimalny:The following example shows how to set the minimum level:

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

Jeśli poziom minimalny nie został jawnie ustawiony, wartość domyślna to Information , co oznacza, że Trace dzienniki i Debug 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 kategorii, które nie mają przypisanych do nich reguł przez konfigurację lub kod.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 dostawcy, kategorii i poziomu 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;
        });
    });

Kategorie i poziomy systemuSystem categories and levels

Poniżej przedstawiono niektóre kategorie używane przez ASP.NET Core i Entity Framework Core, z informacjami o dziennikach, od których należy się spodziewać: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 Ogólna Diagnostyka ASP.NET Core.General ASP.NET Core diagnostics.
Microsoft. AspNetCore. dataprotectionMicrosoft.AspNetCore.DataProtection Które klucze zostały wzięte pod uwagę, znaleziono i użyte.Which keys were considered, found, and used.
Microsoft. AspNetCore. HostFilteringMicrosoft.AspNetCore.HostFiltering Dozwolone hosty.Hosts allowed.
Microsoft. AspNetCore. hostingMicrosoft.AspNetCore.Hosting Jak długo trwa wykonywanie żądań HTTP i czas ich uruchomienia.How long HTTP requests took to complete and what time they started. Które hostowanie zestawów uruchamiania zostało załadowane.Which hosting startup assemblies were loaded.
Microsoft. AspNetCore. MVCMicrosoft.AspNetCore.Mvc MVC i Razor Diagnostyka.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 Informacje o trasie.Route matching information.
Microsoft. AspNetCore. ServerMicrosoft.AspNetCore.Server Reagowanie na uruchamianie, zatrzymywanie i utrzymywanie aktywności.Connection start, stop, and keep alive responses. Informacje o certyfikacie HTTPS.HTTPS certificate information.
Microsoft. AspNetCore. StaticFilesMicrosoft.AspNetCore.StaticFiles Obsługiwane pliki.Files served.
Microsoft. EntityFrameworkCoreMicrosoft.EntityFrameworkCore Ogólna Diagnostyka Entity Framework Core.General Entity Framework Core diagnostics. Aktywność i Konfiguracja bazy danych, wykrywanie zmian, migracje.Database activity and configuration, change detection, migrations.

Zakresy dziennikaLog scopes

Zakres może grupować zestaw operacji logicznych.A scope can group a set of logical operations. Takie grupowanie może służyć do dołączania tych samych danych do każdego dziennika, który został utworzony 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 w ramach 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 typem zwracanym przez BeginScope metodę i obowiązuje 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 przez Zawijanie wywołań 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 włącza 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 opcji rejestratora konsoli jest wymagane do włączenia rejestrowania na podstawie zakresu.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Informacje o konfiguracji znajdują się w sekcji Konfiguracja .For information on configuration, see the Configuration section.

Każdy komunikat dziennika zawiera informacje o zakresie: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

Wbudowani dostawcy rejestrowaniaBuilt-in logging providers

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

Aby uzyskać informacje na temat strumienia stdout i rejestrowania debugowania za pomocą modułu ASP.NET Core, zobacz Rozwiązywanie problemów ASP.NET Core na Azure App Service i usługach IIS i Moduł ASP.NET Core .For information on stdout and debug logging with the ASP.NET Core Module, see Rozwiązywanie problemów ASP.NET Core na Azure App Service i usługach IIS and Moduł ASP.NET Core.

Dostawca konsoliConsole provider

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

logging.AddConsole();

Aby wyświetlić dane wyjściowe rejestrowania konsoli, Otwórz wiersz polecenia w folderze projektu i 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

Dostawca debugowaniaDebug provider

Pakiet Microsoft. Extensions. Logging. Debug Provider zapisuje dane wyjściowe dziennika przy użyciu klasy System. Diagnostics. Debug ( Debug.WriteLine wywołania metod).The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

W systemie Linux ten dostawca zapisuje dzienniki do /var/log/Message.On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();

Dostawca źródła zdarzeńEvent Source provider

Pakiet dostawcy Microsoft. Extensions. Logging. EventSource zapisuje na międzyplatformę źródła zdarzeń, używając nazwy Microsoft-Extensions-Logging .The Microsoft.Extensions.Logging.EventSource provider package writes to an Event Source cross-platform with the name Microsoft-Extensions-Logging. W systemie Windows Dostawca używa funkcji ETW.On Windows, the provider uses ETW.

logging.AddEventSourceLogger();

Dostawca źródła zdarzeń zostanie dodany automatycznie, gdy CreateDefaultBuilder jest wywoływana w celu skompilowania hosta.The Event Source provider is added automatically when CreateDefaultBuilder is called to build the host.

Użyj Narzędzia Narzędzia PerfView do zbierania i wyświetlania dzienników.Use the PerfView utility to collect and view logs. Istnieją inne narzędzia do wyświetlania dzienników ETW, ale narzędzia PerfView zapewnia najlepsze środowisko pracy z zdarzeniami ETW emitowanymi przez ASP.NET Core.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.

Aby skonfigurować narzędzia PerfView do zbierania zdarzeń rejestrowanych przez tego dostawcę, Dodaj ciąg *Microsoft-Extensions-Logging do listy dodatkowych dostawców .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 znaków).(Don't miss the asterisk at the start of the string.)

Narzędzia PerfView dodatkowych dostawców

Dostawca dziennika zdarzeń systemu WindowsWindows EventLog provider

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

logging.AddEventLog();

Przeciążenia addeventlog umożliwiają przekazywanie EventLogSettings .AddEventLog overloads let you pass in EventLogSettings. Jeśli null lub nie zostanie określony, są używane następujące ustawienia domyślne:If null or not specified, the following default settings are used:

  • LogName: "Aplikacja"LogName: "Application"
  • SourceName: "Środowisko uruchomieniowe platformy .NET"SourceName: ".NET Runtime"
  • MachineName: Nazwa komputera lokalnego jest używana.MachineName: The local machine name is used.

Zdarzenia są rejestrowane dla poziomu ostrzeżeń i wyższych.Events are logged for Warning level and higher. Poniższy przykład ustawia domyślny poziom dziennika dziennika zdarzeń LogLevel.Information :The following example sets the Event Log default log level to LogLevel.Information:

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

Dostawca TraceSourceTraceSource provider

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

logging.AddTraceSource(sourceSwitchName);

Przeciążenia AddTraceSource umożliwiają przekazywanie danych w przełączniku źródłowym i odbiorniku śledzenia.AddTraceSource overloads let you pass in a source switch and a trace listener.

Aby można było korzystać z tego dostawcy, aplikacja musi działać na .NET Framework (a nie na platformie .NET Core).To use this provider, an app has to run on the .NET Framework (rather than .NET Core). Dostawca może kierować komunikaty do różnych odbiorników, takich 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.

Dostawca Azure App ServiceAzure App Service provider

Pakiet Microsoft. Extensions. Logging. AzureAppServices Provider zapisuje dzienniki w plikach tekstowych w systemie plików aplikacji Azure App Service i w usłudze BLOB Storage 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.

logging.AddAzureWebAppDiagnostics();

Pakiet dostawcy nie jest uwzględniony w pakiecie Microsoft. AspNetCore. app.The provider package isn't included in the Microsoft.AspNetCore.App metapackage. Podczas określania elementu docelowego .NET Framework lub odwoływania się do niego Microsoft.AspNetCore.App , Dodaj pakiet dostawcy do projektu.When targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project.

AddAzureWebAppDiagnosticsPrzeciążenie umożliwia przekazywanie AzureAppServicesDiagnosticsSettings .An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. Obiekt Settings może przesłonić ustawienia domyślne, takie jak szablon danych wyjściowych rejestrowania, 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. (Szablon danych wyjściowych to szablon wiadomości, który jest stosowany do wszystkich dzienników oprócz tego, co jest dostępne w ILogger wywołaniu metody).(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

Po wdrożeniu w aplikacji App Service, aplikacja będzie przestrzegać ustawień w sekcji dzienniki App Service na stronie App Service 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. Po zaktualizowaniu następujących ustawień zmiany zaczynają obowiązywać natychmiast, bez konieczności ponownego uruchomienia lub ponownej wdrożenia aplikacji.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Rejestrowanie aplikacji (system plików)Application Logging (Filesystem)
  • Rejestrowanie aplikacji (BLOB)Application Logging (Blob)

Domyślną lokalizacją plików dziennika jest folder D: \ Home \ \ LogFiles , a domyślna nazwa pliku to 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. Domyślny limit rozmiaru pliku wynosi 10 MB, a domyślna maksymalna liczba zachowywanych plików to 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Domyślną nazwą obiektu BLOB jest {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.

Dostawca działa tylko wtedy, gdy projekt jest uruchomiony w środowisku platformy Azure.The provider only works when the project runs in the Azure environment. Nie ma ono wpływu, gdy projekt jest uruchamiany lokalnie, — nie zapisuje w plikach lokalnych ani w lokalnym magazynie programistycznym 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 AzureAzure log streaming

Usługa przesyłania strumieniowego w usłudze Azure log umożliwia wyświetlanie dziennika 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 nieudanych żądańFailed request tracing

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

  • Przejdź do strony dzienników App Service ze strony portalu aplikacji.Navigate to the App Service logs page from your app's portal page.
  • Ustaw Rejestrowanie aplikacji (system plików) na włączone.Set Application Logging (Filesystem) to On.
  • Wybierz poziomdziennika.Choose the log Level. To ustawienie dotyczy tylko przesyłania strumieniowego dzienników platformy Azure, a nie innych dostawców rejestrowania w aplikacji.This setting only applies to Azure log streaming, not other logging providers in the app.

Przejdź do strony strumień dziennika , aby wyświetlić komunikaty aplikacji.Navigate to the Log Stream page to view app messages. Są one rejestrowane przez aplikację za pomocą ILogger interfejsu.They're logged by the app through the ILogger interface.

Rejestrowanie śledzenia Application Insights platformy AzureAzure Application Insights trace logging

Pakiet Microsoft. Extensions. Logging. ApplicationInsights Provider zapisuje dzienniki na platformie Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights to usługa, która monitoruje aplikację internetową i udostępnia narzędzia do wykonywania zapytań i analizowania danych telemetrycznych.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Jeśli używasz tego dostawcy, możesz wysyłać zapytania i analizować dzienniki przy użyciu narzędzi Application Insights.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

Dostawca rejestrowania jest dołączony jako zależność Microsoft. ApplicationInsights. AspNetCore, który jest pakietem, który zapewnia wszystkie dostępne dane telemetryczne dla ASP.NET Core.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. Jeśli używasz tego pakietu, nie musisz instalować pakietu dostawcy.If you use this package, you don't have to install the provider package.

Nie używaj pakietu Microsoft. ApplicationInsights. Web — , który jest przeznaczony dla ASP.NET 4. x.Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

Więcej informacji można znaleźć w następujących zasobach:For more information, see the following resources:

Dostawcy rejestrowania innych firmThird-party logging providers

Platformy rejestrowania innych firm, które współpracują z ASP.NET Core:Third-party logging frameworks that work with ASP.NET Core:

Niektóre struktury innych firm mogą wykonywać Rejestrowanie semantyczne, znane także jako rejestrowanie strukturalne.Some third-party frameworks can perform semantic logging, also known as structured logging.

Korzystanie z struktury innej firmy jest podobne do korzystania z jednego 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ływanie ILoggerFactory metody rozszerzenia dostarczonej przez strukturę rejestrowania.Call an ILoggerFactory extension method provided by the logging framework.

Aby uzyskać więcej informacji, zobacz dokumentację każdego dostawcy.For more information, see each provider's documentation. Dostawcy rejestrowania innych firm nie są obsługiwani przez firmę Microsoft.Third-party logging providers aren't supported by Microsoft.

Dodatkowe zasobyAdditional resources