.NET 中的記錄提供者

發行項
05/24/2024

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

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

使用泛型主機。
呼叫 CreateApplicationBuilder，可新增下列記錄提供者：
- 主控台
- 偵錯
- EventSource
- EventLog (僅限 Windows)

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 並新增您想要的記錄提供者。例如，下列程式碼：

呼叫 ClearProviders 以從建立器中移除所有 ILoggerProvider 執行個體。
新增主控台記錄提供者。

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 延伸模組包含以下記錄提供者以作為執行階段程式庫的一部分：

主控台
偵錯
EventSource
EventLog

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

AzureAppServicesFile and AzureAppServicesBlob
ApplicationInsights

主控台

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 儲存體。

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

如果要進行提供者設定，請使用 AzureFileLoggerOptions 和 AzureBlobLoggerOptions，如以下範例中所示：

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 工具來查詢及分析記錄。

如需詳細資訊，請參閱以下資源：

Application Insights 概觀
適用於 .NET Core ILogger 記錄的 ApplicationInsightsLoggerProvider：如果您想要實作記錄提供者，而不需要 Application Insights 遙測的其餘部分，請從這裡開始。
Application Insights logging adapters (Application Insights 記錄配接器)。
安裝、設定及初始化 Application Insights SDK：Microsoft Learn 網站上的互動式教學課程。

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

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

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

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

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

協力廠商記錄提供者

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

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

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

將 NuGet 套件新增至專案。
呼叫記錄架構所提供的 ILoggerFactory 或 ILoggingBuilder 擴充方法。

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

共用方式為