.NET Core 與 ASP.NET Core 中的記錄Logging in .NET Core and ASP.NET Core

By Kirk LarkinJuergen GutschRick AndersonBy Kirk Larkin, Juergen Gutsch and Rick Anderson

.NET Core 支援記錄 API,此 API 能與各種內建和第三方記錄提供者搭配使用。.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. 此文章說明如何搭配內建提供者使用 API。This article shows how to use the logging API with built-in providers.

本文中顯示的大部分程式碼範例都來自 ASP.NET Core 應用程式。Most of the code examples shown in this article are from ASP.NET Core apps. 這些程式碼片段的記錄特定部分適用于任何使用泛型主機的 .net Core 應用程式。The logging-specific parts of these code snippets apply to any .NET Core app that uses the Generic Host. ASP.NET Core web 應用程式範本會使用泛型主機。The ASP.NET Core web app templates use the Generic Host.

查看或下載範例程式碼如何下載View or download sample code (how to download)

記錄提供者Logging providers

記錄提供者會儲存記錄檔,但 Console 顯示記錄的提供者除外。Logging providers store logs, except for the Console provider which displays logs. 例如,Azure 應用程式 Insights 提供者會將記錄儲存在 Azure 應用程式的深入解析中。For example, the Azure Application Insights provider stores logs in Azure Application Insights. 可以啟用多個提供者。Multiple providers can be enabled.

預設 ASP.NET Core web 應用程式範本: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>();
            });
}

上述程式碼會顯示 Program 使用 ASP.NET Core web 應用程式範本所建立的類別。The preceding code shows the Program class created with the ASP.NET Core web app templates. 接下來的幾節會根據使用泛型主機的 ASP.NET Core web 應用程式範本來提供範例。The next several sections provide samples based on the ASP.NET Core web app templates, which use the Generic Host. 本檔稍後會討論非主機主控台應用程式Non-host console apps are discussed later in this document.

若要覆寫所新增的預設記錄提供者集合 Host.CreateDefaultBuilder ,請呼叫 ClearProviders 並加入所需的記錄提供者。To override the default set of logging providers added by Host.CreateDefaultBuilder, call ClearProviders and add the required logging providers. 例如,下列程式碼: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>();
        });

如需其他提供者,請參閱:For additional providers, see:

建立記錄Create logs

若要建立記錄,請使用相依性 ILogger<TCategoryName> 插入(DI)中的物件。To create logs, use an ILogger<TCategoryName> object from dependency injection (DI).

下列範例將:The following example:

  • 建立記錄器, ILogger<AboutModel> 它會使用類型之完整名稱的記錄類別 AboutModelCreates a logger, ILogger<AboutModel>, which uses a log category of the fully qualified name of the type AboutModel. 記錄「類別」是與每個記錄關聯的字串。The log category is a string that is associated with each log.
  • LogInformation在層級通話記錄檔 InformationCalls LogInformation to log at the Information level. 記錄「層級」** 指出已記錄事件的嚴重性。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);
    }
}

本檔稍後將更詳細說明層級類別Levels and categories are explained in more detail later in this document.

如需的詳細資訊 Blazor ,請參閱本檔中 Blazor Blazor WebAssembly 的建立記錄檔。For information on Blazor, see Create logs in Blazor and Blazor WebAssembly in this document.

在主要和啟動中建立記錄顯示如何在和中建立記錄 Main StartupCreate logs in Main and Startup shows how to create logs in Main and Startup.

設定記錄Configure logging

記錄設定通常是由 appsettings 的 Logging 區段所appsettings提供。 {Environment}json檔案。Logging configuration is commonly provided by the Logging section of appsettings.{Environment}.json files. 下列appsettings.Development.js檔案是由 ASP.NET Core web 應用程式範本所產生: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"
    }
  }
}

在上述 JSON 中:In the preceding JSON:

  • "Default" "Microsoft" 已指定、和 "Microsoft.Hosting.Lifetime" 類別。The "Default", "Microsoft", and "Microsoft.Hosting.Lifetime" categories are specified.
  • "Microsoft"類別目錄會套用至以開頭的所有類別 "Microsoft"The "Microsoft" category applies to all categories that start with "Microsoft". 例如,此設定會套用至 "Microsoft.AspNetCore.Routing.EndpointMiddleware" 類別。For example, this setting applies to the "Microsoft.AspNetCore.Routing.EndpointMiddleware" category.
  • "Microsoft"記錄層級和更新版本的類別記錄 WarningThe "Microsoft" category logs at log level Warning and higher.
  • "Microsoft.Hosting.Lifetime"類別比類別更明確 "Microsoft" ,因此 "Microsoft.Hosting.Lifetime" 類別目錄記錄的記錄層級為「資訊」和更高。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.
  • 未指定特定的記錄提供者,因此會 LogLevel 套用至所有已啟用的記錄提供者,但不包括Windows EventLogA specific log provider is not specified, so LogLevel applies to all the enabled logging providers except for the Windows EventLog.

Logging屬性可以有 LogLevel 和記錄提供者屬性。The Logging property can have LogLevel and log provider properties. LogLevel 指定要記錄所選分類的最低層級The LogLevel specifies the minimum level to log for selected categories. 在先前的 JSON 中 InformationWarning 會指定和記錄層級。In the preceding JSON, Information and Warning log levels are specified. LogLevel指出記錄檔的嚴重性,範圍從0到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 和 None = 6。Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5, and None = 6.

LogLevel 指定時,會針對指定層級和更新版本中的訊息啟用記錄。When a LogLevel is specified, logging is enabled for messages at the specified level and higher. 在先前的 JSON 中, Default 類別目錄會針對 Information 和更高版本進行記錄。In the preceding JSON, the Default category is logged for Information and higher. 例如, Information Warning 會記錄、、 ErrorCritical 訊息。For example, Information, Warning, Error, and Critical messages are logged. 如果未 LogLevel 指定,則記錄預設為 Information 層級。If no LogLevel is specified, logging defaults to the Information level. 如需詳細資訊,請參閱記錄層級For more information, see Log levels.

提供者屬性可以指定 LogLevel 屬性。A provider property can specify a LogLevel property. LogLevel在提供者底下,指定該提供者的記錄層級,並覆寫非提供者記錄檔設定。LogLevel under a provider specifies levels to log for that provider, and overrides the non-provider log settings. 請考慮下列appsettings.js檔案: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.
      }
    }
  }
}

中的設定會覆 Logging.{providername}.LogLevel 寫中的設定 Logging.LogLevelSettings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. 在上述 JSON 中, Debug 提供者的預設記錄層級會設定為 InformationIn the preceding JSON, the Debug provider's default log level is set to Information:

Logging:Debug:LogLevel:Default:Information

上述設定會 Information 針對每個類別目錄指定不同的記錄層級 Logging:Debug: Microsoft.HostingThe preceding setting specifies the Information log level for every Logging:Debug: category except Microsoft.Hosting. 當列出特定分類時,特定類別會覆寫預設分類。When a specific category is listed, the specific category overrides the default category. 在上述 JSON 中, Logging:Debug:LogLevel 類別和會覆 "Microsoft.Hosting" "Default" 寫中的設定Logging:LogLevelIn the preceding JSON, the Logging:Debug:LogLevel categories "Microsoft.Hosting" and "Default" override the settings in Logging:LogLevel

您可以為下列任一項指定最小記錄層級:The minimum log level can be specified for any of:

  • 特定提供者:例如,Logging:EventSource:LogLevel:Default:InformationSpecific providers: For example, Logging:EventSource:LogLevel:Default:Information
  • 特定類別:例如,Logging:LogLevel:Microsoft:WarningSpecific categories: For example, Logging:LogLevel:Microsoft:Warning
  • 所有提供者和所有類別:Logging:LogLevel:Default:WarningAll providers and all categories: Logging:LogLevel:Default:Warning

低於最低層級的任何記錄都是:Any logs below the minimum level are not:

  • 傳遞至提供者。Passed to the provider.
  • 已記錄或顯示。Logged or displayed.

若要隱藏所有記錄,請指定LogLevelTo suppress all logs, specify LogLevel.None. LogLevel.None的值為6,其高於 LogLevel.Critical (5)。LogLevel.None has a value of 6, which is higher than LogLevel.Critical (5).

如果提供者支援記錄範圍,則 IncludeScopes 指出是否已啟用。If a provider supports log scopes, IncludeScopes indicates whether they're enabled. 如需詳細資訊,請參閱記錄範圍For more information, see log scopes

下列appsettings.json檔案包含預設啟用的所有提供者: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"
      }
    }
  }
}

在上述範例中:In the preceding sample:

  • 類別和層級不是建議的值。The categories and levels are not suggested values. 提供的範例會顯示所有預設的提供者。The sample is provided to show all the default providers.
  • 中的設定會覆 Logging.{providername}.LogLevel 寫中的設定 Logging.LogLevelSettings in Logging.{providername}.LogLevel override settings in Logging.LogLevel. 例如,中的層級會 Debug.LogLevel.Default 覆寫中的層級 LogLevel.DefaultFor example, the level in Debug.LogLevel.Default overrides the level in LogLevel.Default.
  • 會使用每個預設的提供者別名Each default provider alias is used. 每個提供者都會定義「別名」**,可在設定中用來取代完整類型名稱。Each provider defines an alias that can be used in configuration in place of the fully qualified type name. 內建提供者別名如下:The built-in providers aliases are:
    • 主控台Console
    • 偵錯Debug
    • EventSourceEventSource
    • EventLogEventLog
    • AzureAppServicesFileAzureAppServicesFile
    • AzureAppServicesBlobAzureAppServicesBlob
    • ApplicationInsightsApplicationInsights

依命令列、環境變數及其他設定來設定記錄層級Set log level by command line, environment variables, and other configuration

記錄層級可以由任何設定提供者來設定。Log level can be set by any of the configuration providers.

:分隔符號不適用於所有平臺上的環境變數階層式索引鍵。The : separator doesn't work with environment variable hierarchical keys on all platforms. __(雙底線)為:__, the double underscore, is:

  • 所有平臺都支援。Supported by all platforms. 例如, : Bash不支援分隔符號,但 __ 為。For example, the : separator is not supported by Bash, but __ is.
  • 自動取代為 :Automatically replaced by a :

下列命令:The following commands:

  • 將環境索引鍵設定 Logging:LogLevel:MicrosoftInformation Windows 上的值。Set the environment key Logging:LogLevel:Microsoft to a value of Information on Windows.
  • 使用以 ASP.NET Core web 應用程式範本建立的應用程式時,請測試設定。Test the settings when using an app created with the ASP.NET Core web application templates. dotnet run使用之後,必須在專案目錄中執行命令 setThe dotnet run command must be run in the project directory after using set.
set Logging__LogLevel__Microsoft=Information
dotnet run

先前的環境設定:The preceding environment setting:

  • 只會在從其設定所在的命令視窗中啟動的進程中設定。Is only set in processes launched from the command window they were set in.
  • 以 Visual Studio 啟動的瀏覽器不會讀取。Isn't read by browsers launched with Visual Studio.

下列setx命令也會在 Windows 上設定環境金鑰和值。The following setx command also sets the environment key and value on Windows. 不同于 setsetx 設定會保存下來。Unlike set, setx settings are persisted. /M參數會設定系統內容中的變數。The /M switch sets the variable in the system environment. 如果 /M 未使用,則會設定使用者環境變數。If /M isn't used, a user environment variable is set.

setx Logging__LogLevel__Microsoft=Information /M

Azure App Service上,選取 [設定] > 設定] 頁面上的 [新增應用程式設定]。On Azure App Service, select New application setting on the Settings > Configuration page. Azure App Service 的應用程式設定如下:Azure App Service application settings are:

  • 待用加密,並透過加密通道傳輸。Encrypted at rest and transmitted over an encrypted channel.
  • 公開為環境變數。Exposed as environment variables.

如需詳細資訊,請參閱 Azure App:使用 Azure 入口網站覆寫應用程式設定For more information, see Azure Apps: Override app configuration using the Azure Portal.

如需使用環境變數設定 ASP.NET Core 設定值的詳細資訊,請參閱環境變數For more information on setting ASP.NET Core configuration values using environment variables, see environment variables. 如需使用其他設定來源(包括命令列、Azure Key Vault、Azure 應用程式組態、其他檔案格式等等)的詳細資訊,請參閱 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 ASP.NET Core 的設定.

如何套用篩選規則How filtering rules are applied

建立 ILogger<TCategoryName> 物件時,ILoggerFactory 物件會針對每個提供者選取一個規則來套用到該記錄器。When an ILogger<TCategoryName> object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. ILogger 執行個體寫入的所有訊息都會根據選取的規則進行篩選。All messages written by an ILogger instance are filtered based on the selected rules. 會從可用的規則中選取每個提供者和類別目錄配對的最特定規則。The most specific rule for each provider and category pair is selected from the available rules.

當建立指定類別的 ILogger 時,系統會針對每個提供者使用下列演算法:The following algorithm is used for each provider when an ILogger is created for a given category:

  • 選取所有符合提供者或其別名的規則。Select all rules that match the provider or its alias. 如果找不到符合的項目,請選取所有規則搭配空白提供者。If no match is found, select all rules with an empty provider.
  • 從上一個步驟的結果中,選取具有最長相符類別前置字元的規則。From the result of the preceding step, select rules with longest matching category prefix. 如果找不到符合的項目,請選取未指定類別的所有規則。If no match is found, select all rules that don't specify a category.
  • 如果選取多個規則,請使用最後一個。If multiple rules are selected, take the last one.
  • 如果未選取任何規則,請使用 MinimumLevelIf no rules are selected, use MinimumLevel.

記錄來自 dotnet 執行和 Visual Studio 的輸出Logging output from dotnet run and Visual Studio

系統會顯示使用預設記錄提供者所建立的記錄:Logs created with the default logging providers are displayed:

  • 在 Visual Studio 中In Visual Studio
    • 在調試時的 [調試輸出] 視窗中。In the Debug output window when debugging.
    • 在 [ASP.NET Core Web 服務器] 視窗中。In the ASP.NET Core Web Server window.
  • 在以執行應用程式時的主控台視窗中 dotnet runIn the console window when the app is run with dotnet run.

開頭為 "Microsoft" 類別的記錄來自 ASP.NET Core framework 程式碼。Logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core 和應用程式程式碼會使用相同的記錄 API 和提供者。ASP.NET Core and application code use the same logging API and providers.

記錄分類Log category

ILogger建立物件時,會指定分類When an ILogger object is created, a category is specified. 該類別會包含在每個由該 ILogger 執行個體所產生的記錄訊息中。That category is included with each log message created by that instance of ILogger. 類別字串是任意的,但慣例是使用類別名稱。The category string is arbitrary, but the convention is to use the class name. 例如,在控制器中,名稱可能是 "TodoApi.Controllers.TodoController"For example, in a controller the name might be "TodoApi.Controllers.TodoController". ASP.NET Core web 應用程式 ILogger<T> 會使用來自動取得 ILogger 使用的完整類型名稱 T 做為分類的實例: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.");
    }
}

若要明確指定類別,請呼叫 ILoggerFactory.CreateLoggerTo 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> 相當於使用 T的完整類型名稱來呼叫 CreateLoggerILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

記錄層級Log level

下表列出 LogLevel 值、便利性 Log{LogLevel} 擴充方法,以及建議的使用方式:The following table lists the LogLevel values, the convenience Log{LogLevel} extension method, and the suggested usage:

LogLevelLogLevel Value 方法Method 描述Description
追蹤Trace 00 LogTrace 包含最詳細的訊息。Contain the most detailed messages. 這些訊息可能包含敏感性應用程式資料。These messages may contain sensitive app data. 這些訊息預設為停用,且應在生產環境中啟用。These messages are disabled by default and should not be enabled in production.
偵錯Debug 11 LogDebug 用於偵錯工具和開發。For debugging and development. 請在生產環境中小心使用,因為有大量的數量。Use with caution in production due to the high volume.
資訊Information 22 LogInformation 追蹤應用程式的一般流程。Tracks the general flow of the app. 可能具有長期值。May have long-term value.
警告Warning 33 LogWarning 針對異常或非預期的事件。For abnormal or unexpected events. 通常會包含不會導致應用程式失敗的錯誤或狀況。Typically includes errors or conditions that don't cause the app to fail.
錯誤Error 44 LogError 發生無法處理的錯誤和例外狀況。For errors and exceptions that cannot be handled. 這些訊息表示目前的作業或要求失敗,而不是整個應用程式的失敗。These messages indicate a failure in the current operation or request, not an app-wide failure.
嚴重Critical 55 LogCritical 發生需要立即注意的失敗。For failures that require immediate attention. 範例:資料遺失情況、磁碟空間不足。Examples: data loss scenarios, out of disk space.
NoneNone 66 指定記錄類別不應寫入任何訊息。Specifies that a logging category should not write any messages.

在上表中, LogLevel 會從最低到最高的嚴重性列出。In the previous table, the LogLevel is listed from lowest to highest severity.

記錄方法的第一個參數, LogLevel 表示記錄檔的嚴重性。The Log method's first parameter, LogLevel, indicates the severity of the log. Log(LogLevel, ...)大部分的開發人員會呼叫Log {LogLevel}擴充方法,而不是呼叫。Rather than calling Log(LogLevel, ...), most developers call the Log{LogLevel} extension methods. Log{LogLevel}擴充方法會呼叫 Log 方法並指定 LogLevelThe Log{LogLevel} extension methods call the Log method and specify the LogLevel. 例如,下列兩個記錄呼叫的功能相同,且會產生相同的記錄檔:For example, the following two logging calls are functionally equivalent and produce the same log:

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

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

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem這是事件識別碼。MyLogEvents.TestItem is the event ID. MyLogEvents是範例應用程式的一部分,而且會顯示在 [記錄檔事件識別碼] 區段中。MyLogEvents is part of the sample app and is displayed in the Log event ID section.

MyDisplayRouteInfo 和 ToCtxString是由Rick.Doc的RouteInfo NuGet 封裝所提供。MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. 方法會顯示 Controller 路由資訊。The methods display Controller route information.

下列程式碼會建立 InformationWarning 記錄: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);
}

在上述程式碼中,第一個 Log{LogLevel} 參數 MyLogEvents.GetItem記錄事件識別碼In the preceding code, the first Log{LogLevel} parameter,MyLogEvents.GetItem, is the Log event ID. 第二個參數是訊息範本,其中的預留位置會置入其餘方法參數所提供的引數值。The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. 本檔稍後的「訊息範本」一節中會說明方法參數。The method parameters are explained in the message template section later in this document.

呼叫適當的 Log{LogLevel} 方法,以控制要將多少記錄輸出寫入特定的儲存媒體。Call the appropriate Log{LogLevel} method to control how much log output is written to a particular storage medium. 例如:For example:

  • 在生產環境中:In production:
    • TraceInformation 層級記錄會產生大量的詳細記錄訊息。Logging at the Trace or Information levels produces a high-volume of detailed log messages. 若要控制成本,而不超過資料儲存體限制,請記錄 TraceInformation 層級訊息到高容量、低成本的資料存放區。To control costs and not exceed data storage limits, log Trace and Information level messages to a high-volume, low-cost data store. 請考慮 Trace 將和限制 Information 在特定的類別目錄。Consider limiting Trace and Information to specific categories.
    • Warning透過 Critical 層級登入應該會產生幾個記錄訊息。Logging at Warning through Critical levels should produce few log messages.
      • 成本和儲存體限制通常不是問題。Costs and storage limits usually aren't a concern.
      • 少數記錄可讓您更有彈性地選擇資料存放區。Few logs allow more flexibility in data store choices.
  • 開發中:In development:
    • 設定為 WarningSet to Warning.
    • Trace Information 疑難排解時新增或訊息。Add Trace or Information messages when troubleshooting. 若要限制輸出, TraceInformation 針對 [調查] 底下的類別設定或。To limit output, set Trace or Information only for the categories under investigation.

ASP.NET Core 會寫入架構事件的記錄。ASP.NET Core writes logs for framework events. 例如,請考慮的記錄輸出:For example, consider the log output for:

  • Razor使用 ASP.NET Core 範本建立的頁面應用程式。A Razor Pages app created with the ASP.NET Core templates.
  • 記錄設定為Logging:Console:LogLevel:Microsoft:InformationLogging set to Logging:Console:LogLevel:Microsoft:Information
  • 流覽至 [隱私權] 頁面: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

下列 JSON 集合 Logging:Console:LogLevel:Microsoft:InformationThe following JSON sets Logging:Console:LogLevel:Microsoft:Information:

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

記錄事件識別碼Log event ID

每個記錄都可以指定「事件識別碼」**。Each log can specify an event ID. 範例應用程式會使用 MyLogEvents 類別來定義事件識別碼: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);
}

事件識別碼會將一組事件關聯。An event ID associates a set of events. 例如,與在頁面上顯示項目清單相關的所有記錄可能都是 1001。For example, all logs related to displaying a list of items on a page might be 1001.

記錄提供者可能將事件識別碼存放到識別碼欄位、記錄訊息中或完全不存放。The logging provider may store the event ID in an ID field, in the logging message, or not at all. 偵錯提供者不會顯示事件識別碼。The Debug provider doesn't show event IDs. 主控台提供者會在類別後面以括弧顯示事件識別碼: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

有些記錄提供者會將事件識別碼儲存在欄位中,這可讓您篩選識別碼。Some logging providers store the event ID in a field, which allows for filtering on the ID.

記錄訊息範本Log message template

每個記錄 API 都會使用訊息範本。Each log API uses a message template. 訊息範本可以包含有關提供哪個引數的預留位置。The message template can contain placeholders for which arguments are provided. 使用名稱而非數字做為預留位置。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);
}

預留位置的順序 (而不是其名稱) 會決定使用哪些參數來提供其值。The order of placeholders, not their names, determines which parameters are used to provide their values. 在下列程式碼中,參數名稱在訊息範本中不是順序的: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);

上述程式碼會依序建立具有參數值的記錄訊息:The preceding code creates a log message with the parameter values in sequence:

Parameter values: param1, param2

這種方法可讓記錄提供者執行語義或結構化記錄This approach allows logging providers to implement semantic or structured logging. 引數本身會被傳遞到記錄系統,而不只是格式化的訊息範本。The arguments themselves are passed to the logging system, not just the formatted message template. 這可讓記錄提供者將參數值儲存為欄位。This enables logging providers to store the parameter values as fields. 例如,請考慮下列記錄器方法:For example, consider the following logger method:

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

例如,記錄至 Azure 表格儲存體:For example, when logging to Azure Table Storage:

  • 每個 Azure 資料表實體都可以有 IDRequestTime 屬性。Each Azure Table entity can have ID and RequestTime properties.
  • 具有屬性的資料表會簡化記錄資料的查詢。Tables with properties simplify queries on logged data. 例如,查詢可以尋找特定範圍內的所有記錄, RequestTime 而不需要剖析文字訊息的時間。For example, a query can find all logs within a particular RequestTime range without having to parse the time out of the text message.

記錄例外狀況Log exceptions

記錄器方法具有接受例外狀況參數的多載: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 和 ToCtxString是由Rick.Doc的RouteInfo NuGet 封裝所提供。MyDisplayRouteInfo and ToCtxString are provided by the Rick.Docs.Samples.RouteInfo NuGet package. 方法會顯示 Controller 路由資訊。The methods display Controller route information.

例外狀況記錄是提供者特有的。Exception logging is provider-specific.

預設記錄層級Default log level

如果未設定預設記錄層級,則預設的記錄層級值為 InformationIf the default log level is not set, the default log level value is Information.

例如,請考慮下列 web 應用程式:For example, consider the following web app:

  • 使用 ASP.NET web 應用程式範本建立。Created with the ASP.NET web app templates.
  • 已刪除或重新命名時, appsettings.jsonappsettings.Development.jsappsettings.json and appsettings.Development.json deleted or renamed.

在上述設定中,流覽至 [隱私權] 或 [首頁] TraceDebug Information Microsoft 在類別名稱中產生許多、和訊息。With the preceding setup, navigating to the privacy or home page produces many Trace, Debug, and Information messages with Microsoft in the category name.

下列程式碼會設定預設記錄層級未設定在 configuration 中時的預設記錄層級: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>();
            });
}

一般來說,記錄層級應指定于設定中,而不是程式碼。Generally, log levels should be specified in configuration and not code.

Filter 函數Filter function

針對未透過設定或程式碼指派規則的所有提供者和類別,會叫用篩選函數: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>();
            });
}

上述程式碼會在分類包含 ControllerMicrosoft 且記錄層級為 Information 或更高時,顯示主控台記錄。The preceding code displays console logs when the category contains Controller or Microsoft and the log level is Information or higher.

一般來說,記錄層級應指定于設定中,而不是程式碼。Generally, log levels should be specified in configuration and not code.

ASP.NET Core 和 EF Core 分類ASP.NET Core and EF Core categories

下表包含 ASP.NET Core 和 Entity Framework Core 所使用的一些分類,以及記錄檔的相關注意事項:The following table contains some categories used by ASP.NET Core and Entity Framework Core, with notes about the logs:

類別Category 注意Notes
Microsoft.AspNetCoreMicrosoft.AspNetCore 一般 ASP.NET Core 診斷。General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection 已考慮、發現及使用哪些金鑰。Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering 允許主機。Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting HTTP 要求花了多少時間完成,以及其開始時間。How long HTTP requests took to complete and what time they started. 載入了哪些裝載啟動組件。Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc MVC 和 Razor 診斷。MVC and Razor diagnostics. 模型繫結、篩選執行、檢視編譯、動作選取。Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing 路由比對資訊。Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server 連線開始、停止與保持運作回應。Connection start, stop, and keep alive responses. HTTPS 憑證資訊。HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles 提供的檔案。Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore 一般 Entity Framework Core 診斷。General Entity Framework Core diagnostics. 資料庫活動與設定、變更偵測、移轉。Database activity and configuration, change detection, migrations.

若要在主控台視窗中查看更多類別,請將appsettings.Development.js設定為下列內容: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"
    }
  }
}

記錄範圍Log scopes

「範圍」** 可用來將邏輯作業組成群組。A scope can group a set of logical operations. 此分組功能可用來將相同的資料附加到已建立為集合之一部分的每個記錄。This grouping can be used to attach the same data to each log that's created as part of a set. 例如,在處理邀交易時建立的每個記錄都可以包括該交易識別碼。For example, every log created as part of processing a transaction can include the transaction ID.

範圍:A scope:

下列提供者支援範圍:The following providers support scopes:

透過將記錄器呼叫封裝在 using 區塊中以使用範圍: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);
}

下列 JSON 會啟用主控台提供者的範圍: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"
    }
  }
}

下列程式碼會啟用主控台提供者的範圍: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>();
            });
}

一般來說,您應該在設定中指定記錄,而不是在程式碼中指定。Generally, logging should be specified in configuration and not code.

內建記錄提供者Built-in logging providers

ASP.NET Core 包括下列記錄提供者:ASP.NET Core includes the following logging providers:

如需有關 stdout 使用 ASP.NET Core 模組的記錄和偵錯工具的詳細資訊,請參閱 針對 Azure App Service 和 IIS 上的 ASP.NET Core 進行疑難排解ASP.NET Core 模組For information on stdout and debug logging with the ASP.NET Core Module, see 針對 Azure App Service 和 IIS 上的 ASP.NET Core 進行疑難排解 and ASP.NET Core 模組.

主控台Console

Console提供者會將輸出記錄到主控台。The Console provider logs output to the console. 如需有關在開發中查看記錄的詳細資訊 Console ,請參閱dotnet run 和 Visual Studio 的記錄輸出For more information on viewing Console logs in development, see Logging output from dotnet run and Visual Studio.

偵錯Debug

Debug提供者會使用 system.servicemodel 類別來寫入System.Diagnostics.Debug記錄輸出。The Debug provider writes log output by using the System.Diagnostics.Debug class. 呼叫以 System.Diagnostics.Debug.WriteLine 寫入 Debug 提供者。Calls to System.Diagnostics.Debug.WriteLine write to the Debug provider.

在 Linux 上, Debug 提供者記錄檔位置與散發相依,而且可能是下列其中一項: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

事件來源Event Source

EventSource提供者會寫入名為的跨平臺事件來源 Microsoft-Extensions-LoggingThe EventSource provider writes to a cross-platform event source with the name Microsoft-Extensions-Logging. 在 Windows 上,提供者會使用ETWOn Windows, the provider uses ETW.

dotnet 追蹤工具dotnet trace tooling

Dotnet 追蹤工具是一種跨平臺 CLI 全域工具,可讓您收集執行中進程的 .net Core 追蹤。The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process. 此工具會 Microsoft.Extensions.Logging.EventSource 使用來收集提供者資料 LoggingEventSourceThe tool collects Microsoft.Extensions.Logging.EventSource provider data using a LoggingEventSource.

如需安裝指示,請參閱dotnet-traceSee dotnet-trace for installation instructions.

使用 dotnet 追蹤工具,從應用程式收集追蹤:Use the dotnet trace tooling to collect a trace from an app:

  1. 使用命令執行應用程式 dotnet runRun the app with the dotnet run command.

  2. 判斷 .NET Core 應用程式的處理序識別碼(PID):Determine the process identifier (PID) of the .NET Core app:

    尋找與應用程式元件同名之進程的 PID。Find the PID for the process that has the same name as the app's assembly.

  3. 執行 dotnet trace 命令。Execute the dotnet trace command.

    一般命令語法: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}\"
    

    使用 PowerShell 命令 shell 時,將 --providers 值以單引號括住( ' ):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}\"'
    

    在非 Windows 平臺上,新增 -f speedscope 選項以將輸出追蹤檔案的格式變更為 speedscopeOn non-Windows platforms, add the -f speedscope option to change the format of the output trace file to speedscope.

    關鍵字Keyword 描述Description
    11 記錄有關的中繼事件 LoggingEventSourceLog meta events about the LoggingEventSource. 不會記錄來自的事件 ILogger )。Doesn't log events from ILogger).
    22 Message當呼叫時,開啟事件 ILogger.Log()Turns on the Message event when ILogger.Log() is called. 以程式設計方式(未格式化)提供資訊。Provides information in a programmatic (not formatted) way.
    44 FormatMessage當呼叫時,開啟事件 ILogger.Log()Turns on the FormatMessage event when ILogger.Log() is called. 提供資訊的格式化字串版本。Provides the formatted string version of the information.
    88 MessageJson當呼叫時,開啟事件 ILogger.Log()Turns on the MessageJson event when ILogger.Log() is called. 提供引數的 JSON 標記法。Provides a JSON representation of the arguments.
    事件層級Event Level 描述Description
    00 LogAlways
    11 Critical
    22 Error
    33 Warning
    44 Informational
    55 Verbose

    FilterSpecs和的 {Logger Category} 專案 {Event Level} 代表其他記錄篩選準則。FilterSpecs entries for {Logger Category} and {Event Level} represent additional log filtering conditions. FilterSpecs以分號()分隔專案 ;Separate FilterSpecs entries with a semicolon (;).

    使用 Windows 命令 shell 的範例(值前後沒有單引號 --providers ):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\"
    

    上述命令會啟用:The preceding command activates:

    • 事件來源記錄器,用來產生 4 錯誤()的格式化字串() 2The Event Source logger to produce formatted strings (4) for errors (2).
    • Microsoft.AspNetCore.HostingInformational 記錄層級進行記錄( 4 )。Microsoft.AspNetCore.Hosting logging at the Informational logging level (4).
  4. 按 Enter 鍵或 Ctrl + C 來停止 dotnet 追蹤工具。Stop the dotnet trace tooling by pressing the Enter key or Ctrl+C.

    追蹤會以名稱nettrace儲存在命令執行所在的資料夾中 dotnet traceThe trace is saved with the name trace.nettrace in the folder where the dotnet trace command is executed.

  5. 使用Perfview開啟追蹤。Open the trace with Perfview. 開啟nettrace檔案,並流覽追蹤事件。Open the trace.nettrace file and explore the trace events.

如果應用程式未使用建立主機 CreateDefaultBuilder ,請將事件來源提供者新增至應用程式的記錄設定。If the app doesn't build the host with CreateDefaultBuilder, add the Event Source provider to the app's logging configuration.

如需詳細資訊,請參閱For more information, see:

PerfviewPerfview

使用PerfView 公用程式來收集及查看記錄。Use the PerfView utility to collect and view logs. 此外還有一些其他工具可檢視 ETW 記錄,但 PerfView 提供處理 ASP.NET Core 所發出 ETW 事件的最佳體驗。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.

若要設定 PerfView 以收集此提供者所記錄的事件,請將字串 *Microsoft-Extensions-Logging 新增至 [其他提供者]**** 清單To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. 請不要錯過 * 字串開頭的。Don't miss the * at the start of the string.

Windows EventLogWindows EventLog

EventLog提供者會將記錄輸出傳送至 Windows 事件記錄檔。The EventLog provider sends log output to the Windows Event Log. 與其他提供者不同的是, EventLog 提供者會繼承預設的非提供者設定。Unlike the other providers, the EventLog provider does not inherit the default non-provider settings. 如果 EventLog 未指定記錄檔設定,它們會預設為 LogLevel。If EventLog log settings aren't specified, they default to LogLevel.Warning.

若要記錄低於 LogLevel.Warning 的事件,請明確設定記錄層級。To log events lower than LogLevel.Warning, explicitly set the log level. 下列範例會將事件記錄檔的預設記錄層級設定為 LogLevel.InformationThe following example sets the Event Log default log level to LogLevel.Information:

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

AddEventLog多載可以傳入 EventLogSettingsAddEventLog overloads can pass in EventLogSettings. null 未指定,則會使用下列預設設定:If null or not specified, the following default settings are used:

  • LogName:「應用程式」LogName: "Application"
  • SourceName: ".NET Runtime"SourceName: ".NET Runtime"
  • MachineName:使用本機電腦名稱稱。MachineName: The local machine name is used.

下列程式碼會將的 SourceName 預設值變更 ".NET Runtime"MyLogsThe 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

Microsoft.Extensions.Logging.AzureAppServices 提供者套件會將記錄寫入至 Azure App Service 應用程式檔案系統中的文字檔,並寫入至 Azure 儲存體帳戶中的 Blob 儲存體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.

該提供者套件並未包含在共用架構中。The provider package isn't included in the shared framework. 若要使用提供者,請將提供者套件新增至專案。To use the provider, add the provider package to the project.

如果要進行提供者設定,請使用 AzureFileLoggerOptionsAzureBlobLoggerOptions,如以下範例中所示: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>();
                });
    }
}

當部署到 Azure App Service 時,應用程式會使用 Azure 入口網站 [ App Service ] 頁面的 [ App Service 記錄] 區段中的設定。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. 當下列設定更新時,變更會立即生效,而不需要重新啟動或重新部署應用程式。When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • 應用程式記錄 (檔案系統)Application Logging (Filesystem)
  • 應用程式記錄 (Blob)Application Logging (Blob)

記錄檔的預設位置為 D:\home\LogFiles\Application 資料夾,而預設檔案名稱為 diagnostics-yyyymmdd.txtThe default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. 預設檔案大小限制為 10 MB,而預設保留的檔案數目上限為 2。The default file size limit is 10 MB, and the default maximum number of files retained is 2. 預設 Blob 名稱為 {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txtThe default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

此提供者只會在專案于 Azure 環境中執行時記錄。This provider only logs when the project runs in the Azure environment.

Azure 記錄資料流Azure log streaming

Azure 記錄串流支援從下列時間即時查看記錄活動:Azure log streaming supports viewing log activity in real time from:

  • 應用程式伺服器The app server
  • 網頁伺服器The web server
  • 失敗的要求追蹤Failed request tracing

若要設定 Azure 記錄資料流:To configure Azure log streaming:

  • 從應用程式的入口網站頁面流覽至 [ App Service 記錄] 頁面。Navigate to the App Service logs page from the app's portal page.
  • 將 [應用程式記錄 (檔案系統)]**** 設定為 [開啟]****。Set Application Logging (Filesystem) to On.
  • 選擇記錄 [層級]****。Choose the log Level. 此設定僅適用于 Azure 記錄串流。This setting only applies to Azure log streaming.

流覽至 [記錄資料流程] 頁面以查看記錄。Navigate to the Log Stream page to view logs. 記錄的訊息會以介面記錄 ILoggerThe logged messages are logged with the ILogger interface.

Azure Application InsightsAzure Application Insights

ApplicationInsights提供者套件會將記錄寫入Azure 應用程式深入解析。The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights 是可監視 Web 應用程式的服務,並提供可用來查詢及分析遙測資料的工具。Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. 如果您使用此提供者,就可以使用 Application Insights 工具來查詢及分析記錄。If you use this provider, you can query and analyze your logs by using the Application Insights tools.

記錄提供者會以 Microsoft.ApplicationInsights.AspNetCore (英文) 的相依性形式隨附,這是針對 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. 如果您使用此套件,就不需安裝提供者套件。If you use this package, you don't have to install the provider package.

ApplicationInsights套件適用于 ASP.NET 4.x,而不是 ASP.NET Core。The Microsoft.ApplicationInsights.Web package is for ASP.NET 4.x, not ASP.NET Core.

如需詳細資訊,請參閱下列資源:For more information, see the following resources:

協力廠商記錄提供者Third-party logging providers

可搭配 ASP.NET Core 使用的協力廠商記錄架構:Third-party logging frameworks that work with ASP.NET Core:

某些協力廠商架構可以執行語意記錄 (也稱為結構化記錄) (英文)。Some third-party frameworks can perform semantic logging, also known as structured logging.

使用協力廠商架構類似於使用內建的提供者之一:Using a third-party framework is similar to using one of the built-in providers:

  1. 將 NuGet 套件新增至專案。Add a NuGet package to your project.
  2. 呼叫 ILoggerFactory 記錄架構所提供的擴充方法。Call an ILoggerFactory extension method provided by the logging framework.

如需詳細資訊,請參閱每個提供者的文件。For more information, see each provider's documentation. Microsoft 不支援第三方記錄提供者。Third-party logging providers aren't supported by Microsoft.

非主機主控台應用程式Non-host console app

如需如何在非 web 主控台應用程式中使用泛型主機的範例,請參閱背景工作範例應用程式Program.cs檔案( 在 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 (在 ASP.NET Core 中使用託管服務的背景工作).

不含一般主機的應用程式記錄程式碼,會因新增提供者建立記錄器的方式而有所不同。Logging code for apps without Generic Host differs in the way providers are added and loggers are created.

記錄提供者Logging providers

在非主機主控台應用程式中,於建立 LoggerFactory 時呼叫提供者的 Add{provider name} 擴充方法: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");
    }
}

建立記錄Create logs

若要建立記錄,請使用 ILogger<TCategoryName> 物件。To create logs, use an ILogger<TCategoryName> object. 使用 LoggerFactory 來建立 ILoggerUse the LoggerFactory to create an ILogger.

下列範例會使用 LoggingConsoleApp.Program 做為類別目錄來建立記錄器。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");
    }
}

在下列 ASP.NET 核心範例中,記錄器是用來建立記錄,並以 Information 做為層級。In the following ASP.NET CORE examples, the logger is used to create logs with Information as the level. 記錄「層級」** 指出已記錄事件的嚴重性。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");
    }
}

本檔會更詳細地說明層級類別Levels and categories are explained in more detail in this document.

在主機結構中記錄Log during host construction

不直接支援在主機結構期間進行記錄。Logging during host construction isn't directly supported. 不過,您可以使用個別的記錄器。However, a separate logger can be used. 在下列範例中,會使用 Serilog 記錄器來記錄 CreateHostBuilder。 In the following example, a Serilog logger is used to log in CreateHostBuilder. AddSerilog會使用中指定的靜態設定 Log.LoggerAddSerilog 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();
        }
    }
}

設定相依于 ILogger 的服務Configure a service that depends on ILogger

記錄器的建構函式插入 Startup 適用於舊版 ASP.NET Core,因為會為 Web 主機建立個別的 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. 如需為何只為一般主機建立一個容器的資訊,請參閱重大變更公告For information about why only one container is created for the Generic Host, see the breaking change announcement.

若要設定相依于的服務 ILogger<T> ,請使用「處理常式」插入或提供 factory 方法。To configure a service that depends on ILogger<T>, use constructor injection or provide a factory method. 只有在沒有其他選項時,才建議使用 Factory 方法。The factory method approach is recommended only if there is no other option. 例如,假設有一個服務需要 DI 所 ILogger<T> 提供的實例: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 };
    });
}

上述反白顯示的程式碼是在第一次使用 DI 容器來建立實例時,所執行的Func MyServiceThe preceding highlighted code is a Func that runs the first time the DI container needs to construct an instance of MyService. 您可以用此方式存取任何已註冊的服務。You can access any of the registered services in this way.

在 Main 中建立記錄Create logs in Main

下列程式碼會在 Main ILogger 建立主機之後,從 DI 取得實例來登入: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>();
        });

在啟動中建立記錄Create logs in Startup

下列程式碼會寫入中的記錄 Startup.ConfigureThe 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();
    });
}

在以 Startup.ConfigureServices 方法完成 DI 容器設定之前,不支援寫入記錄檔:Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not supported:

  • 不支援將記錄器插入 Startup 建構函式。Logger injection into the Startup constructor is not supported.
  • 不支援將記錄器插入 Startup.ConfigureServices 方法簽章Logger injection into the Startup.ConfigureServices method signature is not supported

這項限制的原因是記錄相依於 DI 和組態,而後者相依於 DI。The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on DI. ConfigureServices 完成後才會設定 DI 容器。The DI container isn't set up until ConfigureServices finishes.

如需設定服務的相關資訊,而這項服務會相依于 ILogger<T> 或為何要 Startup 在舊版中處理記錄器的程式,請參閱設定相依于 ILogger 的服務For information on configuring a service that depends on ILogger<T> or why constructor injection of a logger into Startup worked in earlier versions, see Configure a service that depends on ILogger

無非同步記錄器方法No asynchronous logger methods

記錄速度應該很快,不值得花費非同步程式碼的效能成本來處理。Logging should be so fast that it isn't worth the performance cost of asynchronous code. 如果記錄資料存放區的速度很慢,請不要直接寫入。If a logging data store is slow, don't write to it directly. 請考慮一開始先將記錄檔訊息寫入快速存放區,然後再將它們移到慢速存放區。Consider writing the log messages to a fast store initially, then moving them to the slow store later. 例如,當記錄到 SQL Server 時,請不要直接在方法中執行這項操作 Log ,因為 Log 方法是同步的。For example, when logging to SQL Server, don't do so directly in a Log method, since the Log methods are synchronous. 相反地,以同步方式將記錄訊息新增到記憶體內佇列,並讓背景工作角色提取出佇列的訊息,藉此執行推送資料到 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. 如需詳細資訊,請參閱GitHub 問題。For more information, see this GitHub issue.

變更執行中應用程式的記錄層級Change log levels in a running app

記錄 API 不包含在應用程式執行時變更記錄層級的案例。The Logging API doesn't include a scenario to change log levels while an app is running. 不過,某些設定提供者能夠重載設定,這會立即影響記錄設定。However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. 例如,檔案設定提供者預設會重載記錄設定。For example, the File Configuration Provider, reloads logging configuration by default. 如果應用程式正在執行時,程式碼中的設定有所變更,應用程式可以呼叫IConfigurationRoot來更新應用程式的記錄設定。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 和 ILoggerFactoryILogger and ILoggerFactory

ILogger<TCategoryName>ILoggerFactory 介面和實作為包含在 .NET Core SDK 中。The ILogger<TCategoryName> and ILoggerFactory interfaces and implementations are included in the .NET Core SDK. 下列 NuGet 套件也提供這些功能:They are also available in the following NuGet packages:

在程式碼中套用記錄篩選規則Apply log filter rules in code

設定記錄篩選規則的慣用方法是使用ConfigurationThe preferred approach for setting log filter rules is by using Configuration.

下列範例說明如何在程式碼中註冊篩選規則: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)指定 System 類別目錄和記錄層級 Debuglogging.AddFilter("System", LogLevel.Debug) specifies the System category and log level Debug. 篩選準則會套用至所有提供者,因為未設定特定的提供者。The filter is applied to all providers because a specific provider was not configured.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)指出AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) specifies:

  • Debug記錄提供者。The Debug logging provider.
  • 記錄層級 Information 和更新版本。Log level Information and higher.
  • 所有以為開頭的分類 "Microsoft"All categories starting with "Microsoft".

建立自訂記錄器Create a custom logger

若要新增自訂記錄器,請新增 ILoggerProvider 具有 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()));

ILoggerProvider 建立一或多個 ILogger 實例。The ILoggerProvider creates one or more ILogger instances. ILogger架構會使用實例來記錄資訊。The ILogger instances are used by the framework to log the information.

範例自訂記錄器設定Sample custom logger configuration

此範例:The sample:

  • 的設計是非常基本的範例,會依照事件識別碼和記錄層級設定記錄主控台的色彩。Is designed to be a very basic sample that sets the color of the log console by event ID and log level. 記錄器通常不會因為事件識別碼而變更,而且不是記錄層級特有的。Loggers generally don't change by event ID and are not specific to log level.
  • 使用下列設定類型,為每個記錄層級和事件識別碼建立不同的色彩主控台專案: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;
}

上述程式碼會將預設層級設為 Warning ,並將色彩設定為 YellowThe preceding code sets the default level to Warning and the color to Yellow. 如果 EventId 設定為0,我們將會記錄所有事件。If the EventId is set to 0, we will log all events.

建立自訂記錄器Create the custom logger

ILogger執行分類名稱通常是記錄來源。The ILogger implementation category name is typically the logging source. 例如,建立記錄器的類型: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;
        }
    }
}

上述程式碼:The preceding code:

  • 建立每個類別目錄名稱的記錄器實例。Creates a logger instance per category name.
  • logLevel == _config.LogLevelIsEnabled ,讓每個 logLevel 都有唯一的記錄器。Checks logLevel == _config.LogLevel in IsEnabled, so each logLevel has a unique logger. 通常,記錄器也應該針對所有較高的記錄層級啟用:Generally, loggers should also be enabled for all higher log levels:
public bool IsEnabled(LogLevel logLevel)
{
    return logLevel >= _config.LogLevel;
}

建立自訂 LoggerProviderCreate the custom LoggerProvider

LoggerProvider是建立記錄器實例的類別。The LoggerProvider is the class that creates the logger instances. 可能不需要為每個類別建立記錄器實例,但這對某些記錄器(例如 NLog 或 log4net)而言是合理的。Maybe it is not needed to create a logger instance per category, but this makes sense for some Loggers, like NLog or log4net. 如此一來,您也可以視需要選擇每個類別的不同記錄輸出目標: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();
    }
}

在上述程式碼中, CreateLogger ColorConsoleLogger 會建立每個分類名稱的單一實例,並將其儲存在中 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>;

自訂記錄器的使用方式和註冊Usage and registration of the custom logger

在中註冊記錄器 Startup.ConfigureRegister 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?}");
    });
}

針對上述程式碼,為提供至少一個擴充方法 ILoggerFactoryFor 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);
    }
}

其他資源Additional resources

作者:Tom DykstraSteve SmithBy Tom Dykstra and Steve Smith

.NET Core 支援記錄 API,此 API 能與各種內建和第三方記錄提供者搭配使用。.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. 此文章說明如何搭配內建提供者使用 API。This article shows how to use the logging API with built-in providers.

查看或下載範例程式碼如何下載View or download sample code (how to download)

新增提供者Add providers

記錄提供者會顯示或儲存記錄。A logging provider displays or stores logs. 例如,主控台提供者會在主控台上顯示記錄,而 Azure Application Insights 提供者則會將記錄儲存在 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. 您可以透過新增多個提供者的方式來將記錄傳送到多個目的地。Logs can be sent to multiple destinations by adding multiple providers.

若要新增提供者,請在 Program.cs 中呼叫提供者的 Add{provider name} 擴充方法: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();
}

上述程式碼需要對 Microsoft.Extensions.LoggingMicrosoft.Extensions.Configuration 的參考。The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration.

預設專案範本會呼叫 CreateDefaultBuilder,該項目會新增下列記錄提供者:The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • 主控台Console
  • 偵錯Debug
  • EventSource (從 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>();

若您使用 CreateDefaultBuilder,您可以使用您想要的提供者來取代預設提供者。If you use CreateDefaultBuilder, you can replace the default providers with your own choices. 呼叫 ClearProviders 並新增您要的提供者。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();
        });

在此文章中深入了解內建記錄提供者第三方記錄提供者Learn more about built-in logging providers and third-party logging providers later in the article.

建立記錄Create logs

若要建立記錄,請使用 ILogger<TCategoryName> 物件。To create logs, use an ILogger<TCategoryName> object. 在 Web 應用程式或託管服務中,從相依性插入 (DI) 取得 ILoggerIn a web app or hosted service, get an ILogger from dependency injection (DI). 在非主機主控台應用程式中,使用 LoggerFactory 來建立 ILoggerIn non-host console apps, use the LoggerFactory to create an ILogger.

下列 ASP.NET Core 範例會建立以 TodoApiSample.Pages.AboutModel 作為類別的記錄器。The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category. 記錄「類別」** 是與每個記錄關聯的字串。The log category is a string that is associated with each log. 由 DI 提供的 ILogger<T> 執行個體,會建立使用型別 T 作為類別的完整名稱記錄。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;
    }

在下列 ASP.NET Core 和主控台應用程式範例中,記錄器會用於以 Information 作為層級來建立記錄。In the following ASP.NET Core and console app examples, the logger is used to create logs with Information as the level. 記錄「層級」** 指出已記錄事件的嚴重性。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);
}

此文章稍後將詳細說明層級類別Levels and categories are explained in more detail later in this article.

在啟動中建立記錄Create logs in Startup

若要在 Startup 類別中寫入記錄,請在建構函式簽章中包括 ILogger 參數: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();
    }
}

在 Program 類別中建立記錄Create logs in the Program class

若要在 Program 類別中寫入記錄,請從 DI 取得 ILogger 執行個體: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();
        });

不直接支援在主機結構期間進行記錄。Logging during host construction isn't directly supported. 不過,您可以使用個別的記錄器。However, a separate logger can be used. 在下列範例中,會使用 Serilog 記錄器來記錄 CreateWebHostBuilder。 In the following example, a Serilog logger is used to log in CreateWebHostBuilder. AddSerilog會使用中指定的靜態設定 Log.LoggerAddSerilog 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();
        }
    }
}

無非同步記錄器方法No asynchronous logger methods

記錄速度應該很快,不值得花費非同步程式碼的效能成本來處理。Logging should be so fast that it isn't worth the performance cost of asynchronous code. 若您的記錄資料存放區很慢,請不要直接寫入其中。If your logging data store is slow, don't write to it directly. 請考慮一開始將記錄寫入到快速的存放區,稍後再將它們移到慢速存放區。Consider writing the log messages to a fast store initially, then move them to the slow store later. 例如,如果您要記錄到 SQL Server,您不希望在 Log 方法中直接執行,因為 Log 方法是同步的。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. 相反地,以同步方式將記錄訊息新增到記憶體內佇列,並讓背景工作角色提取出佇列的訊息,藉此執行推送資料到 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. 如需詳細資訊,請參閱GitHub 問題。For more information, see this GitHub issue.

組態Configuration

記錄提供者設定是由一或多個記錄提供者提供:Logging provider configuration is provided by one or more configuration providers:

  • 檔案格式 (INI、JSON 及 XML)。File formats (INI, JSON, and XML).
  • 命令列引數。Command-line arguments.
  • 環境變數。Environment variables.
  • 記憶體內部 .NET 物件。In-memory .NET objects.
  • 未加密的祕密管理員儲存體。The unencrypted Secret Manager storage.
  • 類似 Azure Key Vault的加密使用者存放區。An encrypted user store, such as Azure Key Vault.
  • 自訂提供者 (已安裝或已建立)。Custom providers (installed or created).

例如,記錄設定通常是由應用程式的 Logging 區段所提供的。For example, logging configuration is commonly provided by the Logging section of app settings files. 下列範例顯示一般 appsettings.Development.json 檔案的內容:The following example shows the contents of a typical appsettings.Development.json file:

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

Logging 屬性可以有 LogLevel 與記錄提供者屬性 (會顯示主控台)。The Logging property can have LogLevel and log provider properties (Console is shown).

Logging 下的 LogLevel 屬性會指定要針對所選類記錄的最小層級The LogLevel property under Logging specifies the minimum level to log for selected categories. 在範例中,System 與d Microsoft 類別會在 Information 層級記錄,而所有其他記錄則會在 Debug 層級記錄。In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Logging 下的其他屬性可指定記錄提供者。Other properties under Logging specify logging providers. 範例使用主控台提供者。The example is for the Console provider. 如果提供者支援記錄範圍,則 IncludeScopes 指出是否已啟用。If a provider supports log scopes, IncludeScopes indicates whether they're enabled. 提供者屬性 (例如範例中的 Console) 可能也會指定 LogLevel 屬性。A provider property (such as Console in the example) may also specify a LogLevel property. 提供者下的 LogLevel 會指定提供者的記錄層級。LogLevel under a provider specifies levels to log for that provider.

若已在 Logging.{providername}.LogLevel 中指定層級,它們會覆寫 Logging.LogLevel 中設定的所有項目。If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel. 例如,請考慮下列 JSON:For example, consider the following JSON:

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

在先前的 JSON 中, Console 提供者設定會覆寫先前的(預設)記錄層級。In the preceding JSON, the Console provider settings overrides the preceding (default) log level.

記錄 API 不包含在應用程式執行時變更記錄層級的案例。The Logging API doesn't include a scenario to change log levels while an app is running. 不過,某些設定提供者能夠重載設定,這會立即影響記錄設定。However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. 例如,檔案設定提供者(由新增) CreateDefaultBuilder 以讀取設定檔案,預設會重載記錄設定。For example, the File Configuration Provider, which is added by CreateDefaultBuilder to read settings files, reloads logging configuration by default. 如果應用程式正在執行時,程式碼中的設定有所變更,應用程式可以呼叫IConfigurationRoot來更新應用程式的記錄設定。If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

如需有關如何實作設定提供者的詳細資訊,請參閱 ASP.NET Core 的設定For information on implementing configuration providers, see ASP.NET Core 的設定.

範例記錄輸出Sample logging output

使用上一節中顯示的範例程式碼時,當從命令列執行應用程式時,記錄會出現在主控台中。With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. 主控台輸出範例如下: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

上述記錄是透過向位於 http://localhost:5000/api/todo/0 的範例應用程式建立 HTTP Get 要求所產生。The preceding logs were generated by making an HTTP Get request to the sample app at http://localhost:5000/api/todo/0.

以下是您在 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

這些透過上一節中所示 ILogger 呼叫所建立的記錄是以 "TodoApi" 為開頭。The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi". 開頭為 "Microsoft" 類別的記錄則是來自 ASP.NET Core 架構程式碼。The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core 與應用程式程式碼會使用相同的記錄 API 與提供者。ASP.NET Core and application code are using the same logging API and providers.

本文的其餘部分將說明記錄的一些詳細資料和選項。The remainder of this article explains some details and options for logging.

NuGet 套件NuGet packages

ILoggerILoggerFactory 介面位於 Microsoft.Extensions.Logging.Abstractions 中,其預設實作則位於 Microsoft.Extensions.Logging 中。The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

記錄分類Log category

建立 ILogger 物件時,會為它指定「類別」**。When an ILogger object is created, a category is specified for it. 該類別會包含在每個由該 ILogger 執行個體所產生的記錄訊息中。That category is included with each log message created by that instance of ILogger. 類別可以是任意字串,但慣例是使用類別名稱,例如 "TodoApi.Controllers.TodoController"。The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

使用 ILogger<T> 來取得ILogger 執行個體,它使用 T 的完整類型名稱做為類別: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;
    }

若要明確指定類別,請呼叫 ILoggerFactory.CreateLoggerTo 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> 相當於使用 T的完整類型名稱來呼叫 CreateLoggerILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

記錄層級Log level

每個記錄都會指定 LogLevel 值。Every log specifies a LogLevel value. 記錄層級表示嚴重性或重要性。The log level indicates the severity or importance. 例如,您可以在方法不正常終止時寫入 Information 記錄,並在方法傳回 404 找不到 狀態碼時寫入 Warning 記錄。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.

下列程式碼會建立 InformationWarning 記錄: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);
}

在上述程式碼中, MyLogEvents.GetItemMyLogEvents.GetItemNotFound 參數是記錄事件識別碼In the preceding code, the MyLogEvents.GetItem and MyLogEvents.GetItemNotFound parameters are the Log event ID. 第二個參數是訊息範本,其中的預留位置會置入其餘方法參數所提供的引數值。The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. 在本文的記錄訊息範本一節中會說明方法參數。The method parameters are explained in the Log message template section in this article.

在方法名稱中包含層級的記錄方法 (例如 LogInformationLogWarning) 是 ILogger 的擴充方法Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. 這些方法會呼叫接受 Log 參數的 LogLevelThese methods call a Log method that takes a LogLevel parameter. 您可以直接呼叫 Log 方法,而不是呼叫其中一個擴充方法,但語法會更複雜。You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. 如需詳細資訊,請參閱 ILogger記錄器延伸模組原始程式碼For more information, see ILogger and the logger extensions source code.

ASP.NET Core 定義下列記錄層級,並從最低嚴重性排列到最高嚴重性。ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • 追蹤 = 0Trace = 0

    針對通常只對偵錯有價值的資訊。For information that's typically valuable only for debugging. 這些訊息可能包含敏感性應用程式資料,因此不應該在生產環境中啟用。These messages may contain sensitive application data and so shouldn't be enabled in a production environment. 預設為停用。Disabled by default.

  • 偵錯 = 1Debug = 1

    針對可在開發與偵錯中使用的資訊。For information that may be useful in development and debugging. 範例:Entering method Configure with flag set to true. 由於記錄的數目很龐大,因此除非您正在進行疑難排解,否則通常不會在生產環境中啟用 Debug 層級記錄。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.

  • 資訊 = 2Information = 2

    針對一般應用程式流程的追蹤。For tracking the general flow of the app. 這些記錄通常有一些長期值。These logs typically have some long-term value. 範例: Request received for path /api/todoExample: Request received for path /api/todo

  • 警告 = 3Warning = 3

    針對應用程式流程中發生的異常或意外事件。For abnormal or unexpected events in the app flow. 這些記錄可能包含不會造成應用程式停止,但可能需要進行調查的錯誤或其他狀況。These may include errors or other conditions that don't cause the app to stop but might need to be investigated. 已處理的例外狀況即為使用 Warning 記錄層級的常見位置。Handled exceptions are a common place to use the Warning log level. 範例: FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • 錯誤 = 4Error = 4

    發生無法處理的錯誤和例外狀況。For errors and exceptions that cannot be handled. 這些訊息指出目前活動或作業 (例如目前的 HTTP 要求) 中發生失敗,這不是整個應用程式的失敗。These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. 範例記錄訊息:Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • 重大 = 5Critical = 5

    發生需要立即注意的失敗。For failures that require immediate attention. 範例:資料遺失情況、磁碟空間不足。Examples: data loss scenarios, out of disk space.

使用此記錄層級來控制要寫入至特定儲存媒體或顯示視窗的記錄輸出量。Use the log level to control how much log output is written to a particular storage medium or display window. 例如:For example:

  • 在生產環境中:In production:
    • Trace透過層級的記錄會 Information 產生大量的詳細記錄訊息。Logging at the Trace through Information levels produces a high-volume of detailed log messages. 若要控制成本,而不超過資料儲存體限制,請將 Trace Information 層級訊息記錄到高容量、低成本的資料存放區。To control costs and not exceed data storage limits, log Trace through Information level messages to a high-volume, low-cost data store.
    • Warning透過 Critical 層級登入通常會產生較少、較小的記錄檔訊息。Logging at Warning through Critical levels typically produces fewer, smaller log messages. 因此,成本和儲存體限制通常不會造成問題,因此可讓您更靈活地選擇資料存放區。Therefore, costs and storage limits usually aren't a concern, which results in greater flexibility of data store choice.
  • 在開發期間:During development:
    • Warning Critical 將訊息記錄到主控台。Log Warning through Critical messages to the console.
    • Trace Information 進行疑難排解時,新增訊息。Add Trace through Information messages when troubleshooting.

本文稍後的記錄篩選一節將說明如何控制提供者所處理的記錄層級。The Log filtering section later in this article explains how to control which log levels a provider handles.

ASP.NET Core 會寫入架構事件的記錄。ASP.NET Core writes logs for framework events. 此文章稍早的記錄範例已排除 Information 層級以下的記錄,因此未建立 DebugTrace 層級的任何記錄。The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. 以下是透過執行設定為顯示 Debug 記錄之範例應用程式所產生的主控台記錄範例: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

記錄事件識別碼Log event ID

每個記錄都可以指定「事件識別碼」**。Each log can specify an event ID. 範例應用程式透過使用本機定義的 LoggingEvents 類別來執行此動作: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;
}

事件識別碼會將一組事件關聯。An event ID associates a set of events. 例如,與在頁面上顯示項目清單相關的所有記錄可能都是 1001。For example, all logs related to displaying a list of items on a page might be 1001.

記錄提供者可能將事件識別碼存放到識別碼欄位、記錄訊息中或完全不存放。The logging provider may store the event ID in an ID field, in the logging message, or not at all. 偵錯提供者不會顯示事件識別碼。The Debug provider doesn't show event IDs. 主控台提供者會在類別後面以括弧顯示事件識別碼: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

記錄訊息範本Log message template

每個記錄都會指定訊息範本。Each log specifies a message template. 訊息範本可以包含有關提供哪個引數的預留位置。The message template can contain placeholders for which arguments are provided. 使用名稱而非數字做為預留位置。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);
}

預留位置的順序 (而不是其名稱) 會決定使用哪些參數來提供其值。The order of placeholders, not their names, determines which parameters are used to provide their values. 請注意,在下列程式碼中,參數名稱在訊息範本中未依順序出現: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);

此程式碼會使用依順序的參數值建立記錄訊息:This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

記錄架構以這種方式運作,因此記錄提供者可以實作語意記錄 (亦稱為結構化記錄)The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. 引數本身會被傳遞到記錄系統,而不只是格式化的訊息範本。The arguments themselves are passed to the logging system, not just the formatted message template. 此資訊可讓記錄提供者將參數值儲存為欄位。This information enables logging providers to store the parameter values as fields. 例如,假設記錄器方法呼叫看起來像這樣:For example, suppose logger method calls look like this:

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

若您正在將記錄傳送到 Azure 表格儲存體,每個 Azure 資料表實體都可以有 IDRequestTime 屬性,以簡化記錄資料的查詢。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. 查詢可以尋找特定 RequestTime 範圍內的所有記錄,而不需要從文字訊息剖析時間。A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

記錄例外狀況Logging exceptions

記錄器方法具有多載,可讓您傳入例外狀況,如下列範例所示: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);

不同提供者處理例外狀況資訊的方式會不同。Different providers handle the exception information in different ways. 以下是來自上述程式碼中的偵錯提供者輸出範例。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

記錄篩選Log filtering

您可以指定特定提供者和類別的最低記錄層級,也可以指定所有提供者或所有類別的最低記錄層級。You can specify a minimum log level for a specific provider and category or for all providers or all categories. 最低層級以下的任何記錄都不會傳遞給該提供者,因此不會顯示或儲存。Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

若要隱藏所有記錄,請指定 LogLevel.None 作為最低記錄層級。To suppress all logs, specify LogLevel.None as the minimum log level. LogLevel.None 的整數值為 6,高於 LogLevel.Critical (5)。The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

在組態中建立篩選規則Create filter rules in configuration

專案範本程式碼會呼叫 CreateDefaultBuilder 以設定主控台、Debug 和 EventSource (ASP.NET Core 2.2 或更新版本)提供者的記錄。The project template code calls CreateDefaultBuilder to set up logging for the Console, Debug, and EventSource (ASP.NET Core 2.2 or later) providers. CreateDefaultBuilder 方法會設定記錄以尋找 Logging 區段中的組態,如本文先前所述The CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as explained earlier in this article.

組態資料會依提供者和類別指定最低記錄層級,如下列範例所示: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"
    }
  }
}

此 JSON 會建立六個篩選規則:一個適用於偵錯提供者、四個適用於主控台提供者,一個適用於所有提供者。This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. 建立 ILogger 物件時,會為每個提供者選取一個規則。A single rule is chosen for each provider when an ILogger object is created.

程式碼中的篩選規則Filter rules in code

下列範例說明如何在程式碼中註冊篩選規則: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));

第二個 AddFilter 會使用其類型名稱來指定偵錯提供者。The second AddFilter specifies the Debug provider by using its type name. 第一個 AddFilter 由於未指定提供者類型,因此適用於所有提供者。The first AddFilter applies to all providers because it doesn't specify a provider type.

如何套用篩選規則How filtering rules are applied

組態資料和上述範例中所示的 AddFilter 程式碼會建立下表中所示的規則。The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. 前六項來自組態範例,最後兩項來自程式碼範例。The first six come from the configuration example and the last two come from the code example.

NumberNumber 提供者Provider 開頭如下的類別...Categories that begin with ... 最低記錄層級Minimum log level
11 偵錯Debug 所有類別All categories 資訊Information
22 主控台Console AspNetCore Razor 。內部Microsoft.AspNetCore.Mvc.Razor.Internal 警告Warning
33 主控台Console AspNetCore Razor 。RazorMicrosoft.AspNetCore.Mvc.Razor.Razor 偵錯Debug
44 主控台Console AspNetCore。RazorMicrosoft.AspNetCore.Mvc.Razor 錯誤Error
55 主控台Console 所有類別All categories 資訊Information
66 所有提供者All providers 所有類別All categories 偵錯Debug
77 所有提供者All providers 系統System 偵錯Debug
88 偵錯Debug MicrosoftMicrosoft 追蹤Trace

建立 ILogger 物件時,ILoggerFactory 物件會針對每個提供者選取一個規則來套用到該記錄器。When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. ILogger 執行個體寫入的所有訊息都會根據選取的規則進行篩選。All messages written by an ILogger instance are filtered based on the selected rules. 系統會從可用的規則中,盡可能選取對每個提供者和類別配對最明確的規則。The most specific rule possible for each provider and category pair is selected from the available rules.

當建立指定類別的 ILogger 時,系統會針對每個提供者使用下列演算法:The following algorithm is used for each provider when an ILogger is created for a given category:

  • 選取所有符合提供者或其別名的規則。Select all rules that match the provider or its alias. 如果找不到符合的項目,請選取所有規則搭配空白提供者。If no match is found, select all rules with an empty provider.
  • 從上一個步驟的結果中,選取具有最長相符類別前置字元的規則。From the result of the preceding step, select rules with longest matching category prefix. 如果找不到符合的項目,請選取未指定類別的所有規則。If no match is found, select all rules that don't specify a category.
  • 如果選取多個規則,請使用最後一個。If multiple rules are selected, take the last one.
  • 如果未選取任何規則,請使用 MinimumLevelIf no rules are selected, use MinimumLevel.

在上述的規則清單中,假設您建立了 ILogger 類別 "AspNetCore Razor Razor " 的物件。ViewEngine":With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • 針對偵錯提供者,規則 1、6 和 8 均適用。For the Debug provider, rules 1, 6, and 8 apply. 規則 8 最明確,因此會選取此規則。Rule 8 is most specific, so that's the one selected.
  • 針對主控台提供者,規則 3、4、5 和 6 均適用。For the Console provider, rules 3, 4, 5, and 6 apply. 規則 3 最明確。Rule 3 is most specific.

產生的 ILogger 執行個體會傳送 Trace 層級以上的記錄到偵錯提供者。The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Debug 層級以上的記錄會傳送到主控台提供者。Logs of Debug level and above are sent to the Console provider.

提供者別名Provider aliases

每個提供者都會定義「別名」**,可在設定中用來取代完整類型名稱。Each provider defines an alias that can be used in configuration in place of the fully qualified type name. 針對內建提供者,請使用下列別名:For the built-in providers, use the following aliases:

  • 主控台Console
  • 偵錯Debug
  • EventSourceEventSource
  • EventLogEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

預設最低層級Default minimum level

只有組態或程式碼中沒有適用於指定提供者和類別的規則時,最低層級設定才會生效。There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. 下列範例示範如何設定最低層級:The following example shows how to set the minimum level:

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

如果您未明確設定最低層級,預設值為 Information,這表示會略過 TraceDebug 記錄。If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

篩選函數Filter functions

針對組態或程式碼未指派規則的所有提供者和類別,會叫用篩選函式。A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. 函式中的程式碼可以存取提供者類型、類別與記錄層級。Code in the function has access to the provider type, category, and log level. 例如: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;
        });
    });

系統類別與層級System categories and levels

以下是由 ASP.NET Core 與 Entity Framework Core 所使用的一些類別,以及有關它們可傳回哪些記錄的附註:Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

類別Category 注意Notes
Microsoft.AspNetCoreMicrosoft.AspNetCore 一般 ASP.NET Core 診斷。General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection 已考慮、發現及使用哪些金鑰。Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering 允許主機。Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting HTTP 要求花了多少時間完成,以及其開始時間。How long HTTP requests took to complete and what time they started. 載入了哪些裝載啟動組件。Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc MVC 和 Razor 診斷。MVC and Razor diagnostics. 模型繫結、篩選執行、檢視編譯、動作選取。Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing 路由比對資訊。Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server 連線開始、停止與保持運作回應。Connection start, stop, and keep alive responses. HTTPS 憑證資訊。HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles 提供的檔案。Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore 一般 Entity Framework Core 診斷。General Entity Framework Core diagnostics. 資料庫活動與設定、變更偵測、移轉。Database activity and configuration, change detection, migrations.

記錄範圍Log scopes

「範圍」** 可用來將邏輯作業組成群組。A scope can group a set of logical operations. 此分組功能可用來將相同的資料附加到已建立為集合之一部分的每個記錄。This grouping can be used to attach the same data to each log that's created as part of a set. 例如,在處理邀交易時建立的每個記錄都可以包括該交易識別碼。For example, every log created as part of processing a transaction can include the transaction ID.

範圍是 BeginScope 方法所傳回的 IDisposable 類型,並會持續到被處置為止。A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. 透過將記錄器呼叫封裝在 using 區塊中以使用範圍: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);
}

下列程式碼會啟用主控台提供者的範圍:The following code enables scopes for the console provider:

Program.csProgram.cs:

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

注意

您必須設定 IncludeScopes 主控台記錄器選項才能啟用範圍記錄。Configuring the IncludeScopes console logger option is required to enable scope-based logging.

如需有關設定的詳細資訊,請參閱設定一節。For information on configuration, see the Configuration section.

每個記錄訊息包含範圍資訊: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

內建記錄提供者Built-in logging providers

ASP.NET Core 隨附下列提供者:ASP.NET Core ships the following providers:

如需 ASP.NET Core 模組的 StdOut 和偵錯記錄相關資訊,請參閱 針對 Azure App Service 和 IIS 上的 ASP.NET Core 進行疑難排解ASP.NET Core 模組For information on stdout and debug logging with the ASP.NET Core Module, see 針對 Azure App Service 和 IIS 上的 ASP.NET Core 進行疑難排解 and ASP.NET Core 模組.

Console 提供者Console provider

Microsoft.Extensions.Logging.Console 提供者套件會將記錄輸出傳送至主控台。The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();

若要查看主控台記錄輸出,請在專案資料夾中開啟命令提示字元,然後執行下列命令:To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Debug 提供者Debug provider

Microsoft.Extensions.Logging.Debug 提供者套件使用 System.Diagnostics.Debug 類別 (Debug.WriteLine 方法呼叫) 來寫入記錄輸出。The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

在 Linux 上,此提供者會將記錄寫入至 /var/log/messageOn Linux, this provider writes logs to /var/log/message.

logging.AddDebug();

事件來源提供者Event Source provider

在跨平臺的事件來源中,會寫入名為的記錄 Microsoft-Extensions-Logging 檔。The Microsoft.Extensions.Logging.EventSource provider package writes to an Event Source cross-platform with the name Microsoft-Extensions-Logging. 在 Windows 上,提供者會使用ETWOn Windows, the provider uses ETW.

logging.AddEventSourceLogger();

呼叫以建立主機時,會自動新增事件來源提供者 CreateDefaultBuilderThe Event Source provider is added automatically when CreateDefaultBuilder is called to build the host.

使用PerfView 公用程式來收集及查看記錄。Use the PerfView utility to collect and view logs. 此外還有一些其他工具可檢視 ETW 記錄,但 PerfView 提供處理 ASP.NET Core 所發出 ETW 事件的最佳體驗。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.

若要設定 PerfView 以收集此提供者所記錄的事件,請將字串 *Microsoft-Extensions-Logging 新增至 [其他提供者]**** 清單To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (請勿遺漏字串開頭的星號)。(Don't miss the asterisk at the start of the string.)

PerfView 的其他提供者

Windows EventLog 提供者Windows EventLog provider

Microsoft.Extensions.Logging.EventLog 提供者套件會將記錄輸出傳送至 Windows 事件記錄檔。The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();

AddEventLog 多載可讓您傳入 EventLogSettingsAddEventLog overloads let you pass in EventLogSettings. null 未指定,則會使用下列預設設定:If null or not specified, the following default settings are used:

  • LogName:「應用程式」LogName: "Application"
  • SourceName: ".NET Runtime"SourceName: ".NET Runtime"
  • MachineName:使用本機電腦名稱稱。MachineName: The local machine name is used.

記錄警告層級和更新版本的事件。Events are logged for Warning level and higher. 下列範例會將事件記錄檔的預設記錄層級設定為 LogLevel.InformationThe following example sets the Event Log default log level to LogLevel.Information:

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

TraceSource 提供者TraceSource provider

Microsoft.Extensions.Logging.TraceSource 提供者套件使用 TraceSource 程式庫與提供者。The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);

AddTraceSource 多載可讓您傳入來源參數和追蹤接聽項。AddTraceSource overloads let you pass in a source switch and a trace listener.

若要使用此提供者,應用程式必須在 .NET Framework (而非 .NET Core) 上執行。To use this provider, an app has to run on the .NET Framework (rather than .NET Core). 該提供者可讓您將訊息路由傳送到種不同的接聽程式,例如範例應用程式中所使用的 TextWriterTraceListenerThe provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

Azure App Service 提供者Azure App Service provider

Microsoft.Extensions.Logging.AzureAppServices 提供者套件會將記錄寫入至 Azure App Service 應用程式檔案系統中的文字檔,並寫入至 Azure 儲存體帳戶中的 Blob 儲存體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();

Microsoft.AspNetCore.App 中繼套件未包含提供者套件。The provider package isn't included in the Microsoft.AspNetCore.App metapackage. 當以 .NET Framework 為目標或是參考 Microsoft.AspNetCore.App 中繼套件時,請將提供者套件新增至專案。When targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project.

AddAzureWebAppDiagnostics 多載可讓您傳入 AzureAppServicesDiagnosticsSettingsAn AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. 設定物件可覆寫預設設定,例如記錄輸出範本、Blob 名稱與檔案大小限制。The settings object can override default settings, such as the logging output template, blob name, and file size limit. (輸出範本是訊息範本,它除了會套用到 ILogger 方法呼叫所提供的記錄之外,還會套用到所有記錄。)(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

當您部署到 App Service 應用程式時,應用程式會遵循 Azure 入口網站 [App Service]**** 頁面中 App Service 記錄區段的設定。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. 當下列設定更新時,變更會立即生效,而不需要重新啟動或重新部署應用程式。When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • 應用程式記錄 (檔案系統)Application Logging (Filesystem)
  • 應用程式記錄 (Blob)Application Logging (Blob)

記錄檔的預設位置為 D:\home\LogFiles\Application 資料夾,而預設檔案名稱為 diagnostics-yyyymmdd.txtThe default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. 預設檔案大小限制為 10 MB,而預設保留的檔案數目上限為 2。The default file size limit is 10 MB, and the default maximum number of files retained is 2. 預設 Blob 名稱為 {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txtThe default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

此提供者僅適用於專案在 Azure 環境中執行的情況。The provider only works when the project runs in the Azure environment. 若在本機執行專案,不會有任何作用,即它不會寫入本機檔案或 blob 的本機開發儲存體。It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Azure 記錄資料流Azure log streaming

Azure 記錄串流可讓您即時檢視來自下列位置的記錄活動:Azure log streaming lets you view log activity in real time from:

  • 應用程式伺服器The app server
  • 網頁伺服器The web server
  • 失敗的要求追蹤Failed request tracing

若要設定 Azure 記錄資料流:To configure Azure log streaming:

  • 從您應用程式的入口網站頁面瀏覽到 [App Service 記錄]****。Navigate to the App Service logs page from your app's portal page.
  • 將 [應用程式記錄 (檔案系統)]**** 設定為 [開啟]****。Set Application Logging (Filesystem) to On.
  • 選擇記錄 [層級]****。Choose the log Level. 此設定僅適用于 Azure 記錄串流,而不適用於應用程式中的其他記錄提供者。This setting only applies to Azure log streaming, not other logging providers in the app.

瀏覽到 [記錄資料流]**** 頁面以檢視應用程式訊息。Navigate to the Log Stream page to view app messages. 這些是應用程式透過 ILogger 介面產生的訊息。They're logged by the app through the ILogger interface.

Azure Application Insights 追蹤記錄Azure Application Insights trace logging

Microsoft.Extensions.Logging.ApplicationInsights (英文) 提供者套件會將記錄寫入至 Azure Application Insights。The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights 是可監視 Web 應用程式的服務,並提供可用來查詢及分析遙測資料的工具。Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. 如果您使用此提供者,就可以使用 Application Insights 工具來查詢及分析記錄。If you use this provider, you can query and analyze your logs by using the Application Insights tools.

記錄提供者會以 Microsoft.ApplicationInsights.AspNetCore (英文) 的相依性形式隨附,這是針對 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. 如果您使用此套件,就不需安裝提供者套件。If you use this package, you don't have to install the provider package.

不要使用 Microsoft.ApplicationInsights.Web (英文) 套件—該套件適用於 ASP.NET 4.x。Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

如需詳細資訊,請參閱下列資源:For more information, see the following resources:

協力廠商記錄提供者Third-party logging providers

可搭配 ASP.NET Core 使用的協力廠商記錄架構:Third-party logging frameworks that work with ASP.NET Core:

某些協力廠商架構可以執行語意記錄 (也稱為結構化記錄) (英文)。Some third-party frameworks can perform semantic logging, also known as structured logging.

使用協力廠商架構類似於使用內建的提供者之一:Using a third-party framework is similar to using one of the built-in providers:

  1. 將 NuGet 套件新增至專案。Add a NuGet package to your project.
  2. 呼叫 ILoggerFactory 記錄架構所提供的擴充方法。Call an ILoggerFactory extension method provided by the logging framework.

如需詳細資訊,請參閱每個提供者的文件。For more information, see each provider's documentation. Microsoft 不支援第三方記錄提供者。Third-party logging providers aren't supported by Microsoft.

其他資源Additional resources