共用方式為


.NET 中的記錄提供者

記錄提供者會保存記錄 (Console 提供者除外),並且只會將記錄顯示為標準輸出。 例如,Azure Application Insights 提供者會將記錄儲存在 Azure Application Insights 中。 您可以啟用多個提供者。

預設 .NET 背景工作角色應用程式範本:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

上述程式碼會顯示使用 .NET 背景工作角色應用程式範本所建立的 Program 類別。 接下來的幾節會根據使用泛型主機的 .NET 背景工作角色應用程式範本來提供範例。

若要覆寫 Host.CreateApplicationBuilder 所新增的記錄提供者預設集,請呼叫 ClearProviders 並新增您想要的記錄提供者。 例如,下列程式碼:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddConsole();

如需其他提供者,請參閱:

設定相依於 ILogger 的服務

若要設定相依於 ILogger<T> 的服務,請使用建構函式插入或提供 Factory 方法。 只有在沒有其他選項時,才建議使用 Factory 方法。 例如,請考慮需要 ILogger<T> DI 所提供執行個體的服務:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddSingleton<IExampleService>(
    container => new DefaultExampleService
    {
        Logger = container.GetRequiredService<ILogger<IExampleService>>()
    });

前面的程式碼是 Func<IServiceProvider, IExampleService>,會在 DI 容器第一次需要建立 IExampleService 的執行個體時執行。 您可以用此方式存取任何已註冊的服務。

內建記錄提供者

Microsoft 延伸模組包含以下記錄提供者以作為執行階段程式庫的一部分:

下列記錄提供者由 Microsoft 提供,不是執行階段程式庫的一部分。 必須將其安裝做為額外的 NuGet 套件。

主控台

Console 提供者會將輸出記錄到主控台。

偵錯

Debug 提供者只有在有附加偵錯工具時,會利用 System.Diagnostics.Debug 類別來寫入記錄輸出 (具體而言是透過 Debug.WriteLine 方法)。 DebugLoggerProvider 會建立可實作 ILogger 介面的記錄器類別執行個體。

事件來源

EventSource 提供者會寫入名稱為 Microsoft-Extensions-Logging 的跨平台事件來源。 在 Windows 上,提供者會使用 ETW

dotnet 追蹤工具

dotnet-trace 工具是一種跨平台 CLI 全域工具,可收集執行中程序的 .NET Core 追蹤。 此工具會使用 LoggingEventSource 收集 Microsoft.Extensions.Logging.EventSource 提供者資料。

如需安裝指示,請參閱 dotnet-trace。 如需使用 dotnet-trace 的診斷教學課程,請參閱在 .NET Core 中針對高 CPU 使用量進行偵錯

Windows EventLog

EventLog 提供者會將記錄輸出傳送至 Windows 事件記錄檔。 與其他提供者不同,EventLog 提供者不會繼承預設的非提供者設定。 如果未指定 EventLog 記錄設定,則預設為 LogLevel.Warning

若要記錄低於 LogLevel.Warning 的事件,請明確設定記錄層級。 下列範例會將事件記錄檔預設記錄層級設定為 LogLevel.Information

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

AddEventLog 多載 可傳入 EventLogSettings。 如果 null 或未指定,則會使用下列預設設定:

  • LogName:「應用程式」
  • SourceName:「.NET Runtime」
  • MachineName:使用本機電腦名稱。

下列程式碼會將 SourceName".NET Runtime" 的預設值變更為 CustomLogs

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddEventLog(
    config => config.SourceName = "CustomLogs");

using IHost host = builder.Build();

host.Run();

Azure App Service

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

提供者套件不包含在執行階段程式庫中。 若要使用提供者,請將提供者套件新增至專案。

如果要進行提供者設定,請使用 AzureFileLoggerOptionsAzureBlobLoggerOptions,如以下範例中所示:

using Microsoft.Extensions.Logging.AzureAppServices;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args)

builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
    options.FileName = "azure-diagnostics-";
    options.FileSizeLimit = 50 * 1024;
    options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
    options.BlobName = "log.txt";
});

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

當部署到 Azure App Service 時,應用程式會使用 Azure 入口網站 [App Service] 頁面中 App Service 記錄區段的設定。 當下列設定更新時,變更會立即生效,而不需要重新啟動或重新部署應用程式。

記錄檔的預設位置為 D:\home\LogFiles\Application 資料夾。 其他預設值會因提供者而異:

  • 應用程式記錄 (Filesystem):預設檔案系統檔案名稱為 diagnostics-yyyymmdd.txt。 預設檔案大小限制為 10 MB,而預設保留的檔案數目上限為 2。
  • 應用程式記錄 (Blob):預設 Blob 名稱為 {app-name}/yyyy/mm/dd/hh/{guid}_applicationLog.txt

此提供者僅記錄專案在 Azure 環境中執行的情況。

Azure 記錄串流

Azure 記錄串流可支援即時檢視來自下列位置的記錄活動:

  • 應用程式伺服器
  • 網頁伺服器
  • 失敗要求的追蹤

若要設定 Azure 記錄資料流:

  • 從應用程式的入口網站頁面瀏覽到 [App Service 記錄]
  • 將 [應用程式記錄 (檔案系統)] 設定為 [開啟]
  • 選擇記錄 [層級]。 此設定僅適用於 Azure 記錄串流。

瀏覽到 [記錄資料流] 頁面以檢視記錄。 記錄的訊息會與 ILogger 介面一起記錄。

Azure Application Insights

Microsoft.Extensions.Logging.ApplicationInsights 提供者套件會將記錄寫入至 Azure Application Insights。 Application Insights 是可監視 Web 應用程式的服務,並提供可用來查詢及分析遙測資料的工具。 如果您使用此提供者,就可以使用 Application Insights 工具來查詢及分析記錄。

如需詳細資訊,請參閱以下資源:

記錄提供者的設計考量因素

如果您打算自行開發 ILoggerProvider 介面和對應之 ILogger 介面的實作,請考慮以下幾點:

  • 方法 ILogger.Log 是同步的。
  • 得假設記錄狀態和物件的存留期。

ILoggerProvider 的實作會透過其 ILoggerProvider.CreateLogger 方法建立 ILogger。 如果您的實作要以非封鎖方式將記錄訊息排入佇列,則這些訊息應該先具體化,或者用來具體化記錄項目的物件狀態應該要序列化。 這麼做可以避免和已處置物件相關的潛在例外狀況。

如需詳細資訊,請參閱在 .NET 中實作自訂記錄提供者

協力廠商記錄提供者

以下是一些可搭配不同 .NET 工作負載使用的第三方紀錄架構:

某些協力廠商架構可以執行語意記錄 (也稱為結構化記錄) \(英文\)。

使用協力廠商架構類似於使用內建的提供者之一:

  1. 將 NuGet 套件新增至專案。
  2. 呼叫記錄架構所提供的 ILoggerFactoryILoggingBuilder 擴充方法。

如需詳細資訊,請參閱每個提供者的文件。 Microsoft 不支援第三方記錄提供者。

另請參閱