记录器层次结构

任何日志记录 API 相对于普通 System.Console.WriteLine 的首要优势在于它能够禁用某些日志语句，同时允许其他语句不受阻碍地打印。此功能假设日志空间，即所有可能的日志语句的空间，根据某些开发人员选择的标准进行分类。

记录器是命名的实体。记录器名称区分大小写，并遵循以下分层命名规则

命名层次结构

如果一个记录器的名称后跟一个点是 后代 记录器名称的前缀，则称该记录器是另一个记录器的 祖先。如果一个记录器与其后代记录器之间没有祖先，则称该记录器是 子 记录器的 父 记录器。

层次结构的工作方式与 .NET 中的命名空间和类层次结构非常相似。正如我们很快将看到的那样，这非常方便。

例如，名为 "Foo.Bar" 的记录器是名为 "Foo.Bar.Baz" 的记录器的父记录器。类似地，"System" 是 "System.Text" 的父记录器，是 "System.Text.StringBuilder" 的祖先。这种命名方案应该为大多数开发人员所熟悉。

根 记录器位于记录器层次结构的顶部。它在三个方面是特殊的

1. 它始终存在
2. 它不能通过名称检索
3. 它始终具有分配的级别

记录器使用 log4net.LogManager 类的静态方法检索。GetLogger 方法将所需记录器的名称作为参数。它们列在下面

namespace log4net
{
    public class LogManager
    {
        public static ILog GetLogger(string name);
        public static ILog GetLogger(Type type);
    }
}

使用 Type 参数的 GetLogger 方法使用完全限定的类型名称作为要检索的记录器的名称。

这些 GetLogger 方法返回一个 ILog 接口。这是传递回开发人员的 记录器 的表示形式。ILog 接口定义如下

namespace log4net
{
    public interface ILog
    {
        /* Test if a level is enabled for logging */
        bool IsDebugEnabled { get; }
        bool IsInfoEnabled { get; }
        bool IsWarnEnabled { get; }
        bool IsErrorEnabled { get; }
        bool IsFatalEnabled { get; }

        /* Log a message object */
        void Debug(object message);
        void Info(object message);
        void Warn(object message);
        void Error(object message);
        void Fatal(object message);

        /* Log a message object and exception */
        void Debug(object message, Exception t);
        void Info(object message, Exception t);
        void Warn(object message, Exception t);
        void Error(object message, Exception t);
        void Fatal(object message, Exception t);

        /* Log a message string using the System.String.Format syntax */
        void DebugFormat(string format, params object[] args);
        void InfoFormat(string format, params object[] args);
        void WarnFormat(string format, params object[] args);
        void ErrorFormat(string format, params object[] args);
        void FatalFormat(string format, params object[] args);

        /* Log a message string using the System.String.Format syntax */
        void DebugFormat(IFormatProvider provider, string format, params object[] args);
        void InfoFormat(IFormatProvider provider, string format, params object[] args);
        void WarnFormat(IFormatProvider provider, string format, params object[] args);
        void ErrorFormat(IFormatProvider provider, string format, params object[] args);
        void FatalFormat(IFormatProvider provider, string format, params object[] args);
    }
}

记录器 可以 分配级别。级别是 log4net.Core.Level 类的实例。以下级别按优先级递增的顺序定义

• ALL
• DEBUG
• INFO
• WARN
• ERROR
• FATAL
• OFF

如果给定记录器未分配级别，则它将从其具有分配级别的最近祖先继承一个级别。更正式地说

级别继承

给定记录器 X 的 继承级别 等于记录器层次结构中第一个非空级别，从 X 开始，向上沿着层次结构一直到 根 记录器。

为了确保所有记录器最终都能继承一个级别，根 记录器始终具有分配的级别。根 记录器的默认值为 DEBUG。

以下是四个表格，其中包含各种分配的级别值以及根据上述规则得出的继承级别。

在上面的 示例 1 中，只有 根 记录器分配了级别。此级别值 Proot 由其他记录器 X、X.Y 和 X.Y.Z 继承。

在上面的 示例 2 中，所有记录器都具有分配的级别值。不需要级别继承。

在上面的 示例 3 中，记录器 root、X 和 X.Y.Z 分别分配了级别 Proot、Px 和 Pxyz。记录器 X.Y 从其父记录器 X 继承其级别值。

在上面的 示例 4 中，记录器 root 和 X 分别分配了级别 Proot 和 Px。记录器 X.Y 和 X.Y.Z 从其具有分配级别的最近父记录器 X 继承其级别值。

日志记录请求是通过调用记录器实例的打印方法之一（通过 log4net.ILog）来完成的。这些打印方法是 Debug、Info、Warn、Error 和 Fatal。

根据定义，打印方法确定日志记录请求的级别。例如，如果 log 是一个记录器实例，则语句 log.Info("..") 是一个级别为 INFO 的日志记录请求。

如果日志记录请求的级别高于或等于其记录器的级别，则称该请求为 已启用。否则，该请求被称为 已禁用。没有分配级别的记录器将从层次结构继承一个级别。此规则总结如下。

基本选择规则

如果 L >= K，则级别为 L 的记录器请求在级别为（分配或继承的，以适用者为准）K 的记录器中被启用。

此规则是 log4net 的核心。它假设级别是有序的。对于标准级别，我们有 DEBUG < INFO < WARN < ERROR < FATAL。

使用相同名称调用 log4net.LogManager.GetLogger 方法将始终返回对完全相同的记录器对象的引用。

例如，在

ILog x = LogManager.GetLogger("wombat");
ILog y = LogManager.GetLogger("wombat");

x 和 y 引用 完全 相同的记录器对象。

因此，可以配置一个记录器，然后在代码中的其他地方检索相同的实例，而无需传递引用。与生物学上的父母关系形成根本矛盾的是，父母总是先于子女，而 log4net 记录器可以按任何顺序创建和配置。特别是，"父" 记录器将找到并链接到其后代，即使它是在它们之后实例化的。

log4net 环境的配置通常在应用程序初始化时完成。首选方法是读取配置文件。这种方法将在稍后讨论。

log4net 使得通过 软件组件 命名记录器变得容易。这可以通过在每个类中静态实例化一个记录器来实现，记录器名称等于类的完全限定名称。这是一种定义记录器的有用且直接的方法。由于日志输出带有生成记录器的名称，因此这种命名策略使识别日志消息的来源变得容易。但是，这仅仅是命名记录器的一种可能的，尽管是常见的，策略。log4net 并不限制可能的记录器集。开发人员可以自由地根据需要命名记录器。

尽管如此，将记录器命名为它们所在的类似乎是目前已知的最佳策略。它简单明了，开发人员可以清楚地知道每个日志消息来自哪里。最重要的是，它利用应用程序的设计来生成记录器层次结构的设计。希望应用程序的设计已经经过深思熟虑。

附加器

根据记录器选择性地启用或禁用日志请求只是其中的一部分。Log4net 允许日志请求打印到多个目标。在 log4net 中，输出目标称为附加器。附加器必须实现 log4net.Appenders.IAppender 接口。

log4net 包中定义了以下附加器

可以将多个附加器附加到记录器。

对于给定记录器的每个已启用日志请求，都将转发到该记录器中的所有附加器以及层次结构中更高层的附加器。 换句话说，附加器是从记录器层次结构中累加继承的。例如，如果将控制台附加器添加到根记录器，则所有已启用的日志请求至少会打印到控制台。如果另外将文件附加器添加到记录器（例如X），则X及其子级的已启用日志请求将打印到文件和控制台。可以通过将记录器上的附加性标志设置为 false 来覆盖此默认行为，以便附加器累加不再是累加的。

下面总结了控制附加器附加性的规则。

附加器附加性

记录器X的日志语句的输出将发送到X及其祖先中的所有附加器。这就是“附加器附加性”一词的含义。

但是，如果记录器X的祖先（例如Y）的附加性标志设置为 false，则X的输出将被定向到X及其祖先（包括Y）中的所有附加器，但不包括Y的任何祖先中的附加器。

默认情况下，记录器的附加性标志设置为 true。

下表显示了一个示例

过滤器

附加器可以过滤传递给它们的事件。可以在配置中指定过滤器，以允许对通过不同附加器记录的事件进行精细控制。

最简单的控制形式是在附加器上指定一个 Threshold。这通过仅记录级别大于或等于阈值的事件来实现。

可以使用每个附加器上定义的过滤器链进行更复杂和自定义的事件过滤。过滤器必须实现 log4net.Filter.IFilter 接口。

log4net 包中定义了以下过滤器

可以将过滤器配置为根据匹配结果接受或拒绝事件。

布局

通常，用户不仅希望自定义输出目标，还希望自定义输出格式。这是通过将布局与附加器关联来实现的。布局负责根据用户的意愿格式化日志请求，而附加器负责将格式化的输出发送到其目标。 PatternLayout（标准 log4net 发行版的一部分）允许用户根据类似于 C 语言 printf 函数的转换模式指定输出格式。

例如，具有转换模式 "%timestamp [%thread] %-5level %logger - %message%newline" 的 PatternLayout 将输出类似于以下内容

176 [main] INFO  Com.Foo.Bar - Located nearest gas station.

第一个字段是程序启动后经过的毫秒数。第二个字段是发出日志请求的线程。第三个字段是日志语句的级别。第四个字段是与日志请求关联的记录器的名称。'-' 后的文本是语句的消息。

log4net 包中包含以下布局

对象渲染器

同样重要的是，log4net 将根据用户指定的标准呈现日志消息的内容。例如，如果您经常需要记录 Oranges（当前项目中使用的对象类型），那么您可以注册一个 OrangeRenderer，它将在需要记录橙子时被调用。

对象渲染遵循类层次结构。例如，假设橙子是水果，如果您注册了一个 FruitRenderer，那么所有水果（包括橙子）都将由 FruitRenderer 渲染，除非您注册了一个特定于橙子的 OrangeRenderer。

对象渲染器必须实现 log4net.ObjectRenderer.IObjectRenderer 接口。

请注意，DebugFormat、InfoFormat、WarnFormat、ErrorFormat 和 FatalFormat 方法不使用对象渲染器。