.NET 支持适用于各种内置和第三方日志记录提供程序的日志记录 API。 本文介绍了如何将日志记录 API 与内置提供程序结合使用。 日志记录提供程序负责确定写入日志的位置。 本文中提供的大多数代码示例都适用于使用通用主机的 .NET 应用。 对于不使用通用主机的应用，请参阅非主机控制台应用。

提示

所有日志记录示例源代码都可以在示例浏览器中下载。 有关详细信息，请参阅浏览代码示例：.NET 中的日志记录。

重要

从 .NET 6 开始，日志服务不再注册 ILogger 类型。 使用记录器时，指定泛型类型的替换项 ILogger 或将 ILogger 注册为依赖关系注入 (DI)。

若要创建日志，请使用 DI 中的 ILogger 对象。

如下示例中：

本文稍后部分将更详细地介绍级别和类别。

日志配置通常由 appsettings {Environment}.json 文件的 Logging 部分提供 。 以下 appsettings.Development.json 文件由 .NET 辅助角色服务模板生成：

在上述 JSON 中：

Logging 属性可以具有 LogLevel 和日志提供程序属性。 LogLevel 指定要针对所选类别进行记录的最低级别。 在前面的 JSON 中，指定了 Information 和 Warning 日志级别。 LogLevel 表示日志的严重性，范围为 0 到 6：

Trace = 0、Debug = 1、Information = 2、Warning = 3、Error = 4、Critical = 5 和 None = 6。

指定 LogLevel 时，将为指定级别和更高级别的消息启用日志记录。 在前面的 JSON 中，记录了 Information 及更高级别的 Default 类别。 例如，记录了 Information、Warning、Error 和 Critical 消息。 如果未指定 LogLevel，则日志记录默认为 Information 级别。 有关详细信息，请参阅日志级别。

提供程序属性可以指定 LogLevel 属性。 提供程序下的 LogLevel 指定要为该提供程序记录的级别，并替代非提供程序日志设置。 请考虑使用以下 appsettings.json 文件：

Logging.{ProviderName}.LogLevel 中的设置将替代 Logging.LogLevel 中的设置。 在前面的 JSON 中，Debug 提供程序的默认日志级别设置为 Information：

Logging:Debug:LogLevel:Default:Information

前面的设置为每个 Logging:Debug: 类别（Microsoft.Hosting 除外）指定 Information 日志级别。 当列出特定类别时，该特定类别将替代默认类别。 在前面的 JSON 中，Logging:Debug:LogLevel 类别 "Microsoft.Hosting" 和 "Default" 替代 Logging:LogLevel 中的设置

可以为以下任何一项指定最低日志级别：

低于最低级别的任何日志均不会执行以下操作：

要阻止所有日志，请指定 LogLevel.None。 LogLevel.None 的值为 6，该值高于 LogLevel.Critical (5)。

如果提供程序支持日志作用域，则 IncludeScopes 将指示是否启用这些域。 有关详细信息，请参阅日志范围

以下 appsettings.json 文件包含所有内置提供程序的设置：

在上述示例中：

日志级别可以由任何配置提供程序设置。 例如，可以创建一个名为 Logging:LogLevel:Microsoft 且值为 Information 的持久性环境变量。

在给定日志级别值的情况下，创建并分配持久性环境变量。

在命令提示符的新实例中，读取环境变量。

在给定日志级别值的情况下，创建并分配持久性环境变量。

在 PowerShell 的新实例中，读取环境变量。

在给定日志级别值的情况下，创建并分配持久性环境变量。

读取环境变量。

注意

在使用包含 .（句点）的名称配置环境变量时，请注意 Stack Exchange 上提出的“导出带有点 (.) 的变量”问题以及相应的 已接受解答。

前面的环境设置会在环境中持续存在。 若要在使用通过 .NET 辅助角色服务模板创建的应用时测试这些设置，请在分配环境变量后，在项目目录中使用 dotnet run 命令。

提示

设置环境变量后，请重启集成开发环境 (IDE)，以确保新添加的环境变量可用。

在 Azure 应用服务上，选择“设置”>“配置”页面上的“新应用程序设置”。 Azure 应用服务应用程序设置：

若要详细了解如何使用环境变量设置 .NET 配置值，请参阅环境变量。

创建 ILogger 对象时，ILoggerFactory 对象将根据提供程序选择一条规则，将其应用于该记录器。 将按所选规则筛选 ILogger 实例写入的所有消息。 从可用规则中为每个提供程序和类别对选择最具体的规则。

在为给定的类别创建 ILogger 时，以下算法将用于每个提供程序：

创建 ILogger 对象时，将指定类别。 该类别包含在由此 ILogger 实例创建的每条日志消息中。 类别字符串是任意的，但约定将使用类名称。 例如，在服务定义类似于以下对象的应用程序中，类别可能为 "Example.DefaultService"：

要显式指定类别，请调用 LoggerFactory.CreateLogger：

在多个类/类型中使用时，使用固定名称调用 CreateLogger 很有用，这样可以按类别组织事件。

ILogger 相当于使用 T 的完全限定类型名称来调用 CreateLogger。

下表列出了 LogLevel 值、方便的 Log{LogLevel} 扩展方法以及建议的用法：

在上表中，LogLevel 按严重性由低到高的顺序列出。

Log 方法的第一个参数 LogLevel 指示日志的严重性。 大多数开发人员调用 Log{LogLevel} 扩展方法，而不调用 Log(LogLevel, ...)。 Log{LogLevel} 扩展方法调用 Log 方法并指定 LogLevel。 例如，以下两个日志记录调用功能相同，并生成相同的日志：

AppLogEvents.Details 为事件 ID，用常量 Int32 值隐式表示。 AppLogEvents 是一个公开各种命名的标识符常量并显示在日志事件 ID 部分中的类。

下面的代码会创建 Information 和 Warning 日志：

在前面的代码中，第一个 Log{LogLevel} 参数 AppLogEvents.Read 是日志事件 ID。 第二个参数是消息模板，其中的占位符用于填写剩余方法形参提供的实参值。 稍后将在本文的消息模板部分介绍方法参数。

配置适当的日志级别并调用正确的 Log{LogLevel} 方法来控制写入特定存储介质的日志输出量。 例如：

以下 JSON 设置了 Logging:Console:LogLevel:Microsoft:Information：

每个日志可指定一个事件标识符，EventId 是一个具有 Id 和可选 Name 只读属性的结构。 示例源代码使用 AppLogEvents 类来定义事件 ID：

提示

若要详细了解如何将 int 转换为 EventId，请参阅EventId.Implicit(Int32 to EventId) 运算符。

事件 ID 与一组事件相关联。 例如，与从存储库读取值相关的所有日志都可能是 1001。

日志记录提供程序可将事件 ID 记录在 ID 字段中，记录在日志记录消息中，或者不进行记录。 调试提供程序不显示事件 ID。 控制台提供程序在类别后的括号中显示事件 ID：

一些日志记录提供程序将事件 ID 存储在一个字段中，该字段允许对 ID 进行筛选。

每个日志 API 都使用一个消息模板。 消息模板可包含要填写参数的占位符。 请在占位符中使用名称而不是数字。 占位符的顺序（而非其名称）决定了为其提供值的参数。 在以下代码中，消息模板中的参数名称不按顺序排列：

上面的代码按顺序通过参数值创建日志消息：

注意

请注意，在单个消息模板中使用多个占位符时，这些占位符是基于序号的。 这些名称不用于将参数与占位符对齐。

此方法允许日志记录提供程序实现语义或结构化日志记录。 参数本身会传递给日志记录系统，而不仅仅是格式化的消息模板。 这使日志记录提供程序可以将参数值存储为字段。 请考虑使用以下记录器方法：

例如，登录到 Azure 表存储时：

日志消息模板支持占位符格式设置。 模板可随意指定给定类型参数的任何有效格式。 例如，请考虑使用以下 Information 记录器消息模板：

在上一示例中，DateTimeOffset 实例是与记录器消息模板中的 PlaceHolderName 相对应的类型。 由于值基于序号，因此该名称可以是任何内容。 对于 DateTimeOffset 类型来说，MMMM dd, yyyy 格式有效。

若要详细了解 DateTime 和 DateTimeOffset 格式设置，请参阅自定义日期和时间格式字符串。

以下示例演示如何使用 {} 占位符语法设置消息模板格式。 此外，还显示一个转义 {} 占位符语法的示例及其输出。 最后，还显示带有模板化占位符的字符串内插：

提示

记录器方法的重载采用异常参数：

异常日志记录是特定于提供程序的。

如果未设置默认日志级别，则默认的日志级别值为 Information。

例如，请考虑以下辅助角色服务应用：

使用上述设置，导航到隐私或主页会生成许多 Trace、Debug 和 Information 消息，并在类别名称中包含 Microsoft。

如果未在配置中设置默认日志级别，以下代码会设置默认日志级别：

对配置或代码没有向其分配规则的所有提供程序和类别调用筛选器函数：

如果类别包含 Example 或 Microsoft，并且日志级别为 Information 或更高级别，以上代码会显示控制台日志。

作用域可对一组逻辑操作进行分组。 此分组可用于将相同的数据附加到作为集合的一部分而创建的每个日志。 例如，在处理事务期间创建的每个日志都可包括事务 ID。

范围：

以下提供程序支持范围：

要使用作用域，请在 using 块中包装记录器调用：

以下 JSON 为控制台提供程序启用范围：

下列代码为控制台提供程序启用作用域：

对于没有通用主机的应用，日志记录代码在添加提供程序和创建记录器的方式上有所不同。 在非主机控制台应用中，在创建 LoggerFactory 时调用提供程序的 Add{provider name} 扩展方法：

loggerFactory 对象用于创建 ILogger 实例。

以下代码通过在构建主机之后从 DI 获取 ILogger 实例来登录 Main：

前面的代码依赖于两个 NuGet 包：

其项目文件类似于以下内容：

日志记录应该会很快，不值得牺牲性能来使用异步代码。 如果日志记录数据存储很慢，请不要直接写入它。 考虑先将日志消息写入快速存储，然后再将其移至慢速存储。 例如，登录到 SQL Server 时，请勿直接使用 Log 方法登录，因为 Log 方法是同步的。 相反，你会将日志消息同步添加到内存中的队列，并让后台辅助线程从队列中拉出消息，以完成将数据推送到 SQL Server 的异步工作。

不可使用日志记录 API 在应用运行时更改日志记录。 但是，一些配置提供程序可重新加载配置，这将对日志记录配置立即产生影响。 例如，文件配置提供程序默认情况下会重载日志记录配置。 如果在应用运行时在代码中更改了配置，该应用可调用 IConfigurationRoot.Reload 来更新应用的日志记录配置。

ILogger 和 ILoggerFactory 接口和实现都包含在 .NET SDK 中。 它们还可以通过以下 NuGet 包获得：

设置日志筛选器规则的首选方法是使用配置。

下面的示例演示了如何在代码中注册筛选规则：

logging.AddFilter("System", LogLevel.Debug) 指定 System 类别和日志级别 Debug。 筛选器将应用于所有提供程序，因为未配置特定的提供程序。

AddFilter("Microsoft", LogLevel.Information) 指定以下项：