.NET 中的日志记录提供程序

项目
02/01/2025

日志记录提供程序保留日志，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 Worker 应用程序模板的示例，这些模板使用通用宿主。

若要替代 Host.CreateApplicationBuilder添加的默认日志记录提供程序集，请调用 ClearProviders 并添加所需的日志记录提供程序。例如，以下代码：

调用 ClearProviders 以从生成器中删除所有 ILoggerProvider 实例。
添加控制台日志记录提供程序。

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

有关其他服务提供商，请参阅：

内置日志记录提供程序。
第三方日志记录提供程序。

配置依赖于 ILogger 的服务

若要配置依赖于 ILogger<T>的服务，请使用构造函数注入或提供工厂方法。仅当没有其他选项时，才建议使用工厂方法方法。例如，假设某个服务需要由 DI 提供的 ILogger<T> 实例：

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

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

前面的代码是一个 Func<IServiceProvider、IExampleService>，它在 DI 容器首次需要构造 IExampleService的实例时运行。可以通过这种方式访问任何已注册的服务。

内置日志记录提供程序

Microsoft扩展包括以下日志记录提供程序作为运行时库的一部分：

控制台
调试
EventSource
事件日志

以下日志记录提供程序由Microsoft提供，但不作为运行时库的一部分提供。它们必须作为其他 NuGet 包进行安装。

AzureAppServicesFile 和 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 提供程序将日志输出发送到 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 应用服务

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 应用服务时，应用使用 Azure 门户 应用服务 页应用服务日志部分中的设置。更新以下设置后，更改会立即生效，无需重启或重新部署应用。

日志文件的默认位置位于 D：\home\LogFiles\Application 文件夹中。其他默认值因提供程序而异：

应用程序日志记录（文件系统）：默认文件系统文件名为 diagnostics-yyyymmdd.txt。默认文件大小限制为 10 MB，保留的默认最大文件数为 2。
应用程序日志记录（Blob）：默认 blob 名称 {app-name}/yyyy/mm/dd/hh/{guid}_applicationLog.txt。

此提供程序仅在项目在 Azure 环境中运行时进行日志。

Azure 日志流式处理

Azure 日志流式处理支持从以下位置实时查看日志活动：

应用服务器
Web 服务器
失败请求跟踪

若要配置 Azure 日志流式处理，请执行以下操作：

从应用的门户页导航到 应用服务日志 页。
将“应用程序日志记录(Filesystem)”设置为“开”。
选择日志级别。此设置仅适用于 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 日志记录适配器。
在 Microsoft Learn 站点上安装、配置和初始化 Application Insights SDK - 交互式教程。

记录提供程序设计注意事项

如果打算开发自己的 ILoggerProvider 接口实现和 ILogger的相应自定义实现，请考虑以下几点：

ILogger.Log 方法是同步的。
不应假定日志状态和对象的生存期。

ILoggerProvider 的实现将通过 ILoggerProvider.CreateLogger 方法创建 ILogger。如果要以非阻塞的方式对日志消息进行排队，应该首先将消息转化为具体数据，或者将用于生成日志条目的对象状态序列化。这样做可以避免已释放的对象出现潜在的异常。

有关详细信息，请参阅在 .NET中实现自定义日志记录提供程序。

第三方日志记录提供程序

下面是一些适用于各种 .NET 工作负荷的第三方日志记录框架：

某些第三方框架可以执行语义日志记录，也称为结构化日志记录。

使用第三方框架类似于使用其中一个内置提供程序：

将 NuGet 包添加到项目。
调用日志记录框架提供的 ILoggerFactory 或 ILoggingBuilder 扩展方法。

有关详细信息，请参阅每个提供程序的文档。 Microsoft不支持第三方日志记录提供程序。

另请参阅

.NET 中的日志记录。
在 .NET中实现自定义日志记录提供程序。
.NET 中的高性能日志记录。

通过