Log4Net 之走进Log4Net （四）

原文:Log4Net 之走进Log4Net （四）

一、Log4net的结构

log4net 有四种主要的组件，分别是Logger（记录器）, Repository（库）, Appender（附着器）以及 Layout（布局）.

1、Logger

1.1 Logger接口

　　Logger是应用程序需要交互的主要组件，它用来产生日志消息。产生的日志消息并不直接显示，还要预先经过Layout的格式化处理后才会输出。

　　Logger提供了多种方式来记录一个日志消息，你可以在你的应用程序里创建多个Logger，每个实例化的Logger对象都被log4net框架作为命名实体(named entity)来维护。这意味着为了重用Logger对象，你不必将它在不同的类或对象间传递，只需要用它的名字为参数调用就可以了。log4net框架使用继承体系，继承体系类似于.NET中的名字空间。也就是说，如果有两个logger,分别被定义为a.b.c和a.b，那么我们说a.b是a.b.c的祖先。每一个logger都继承了祖先的属性

　　Log4net框架定义了一个ILog接口，所有的logger类都必须实现这个接口。如果你想实现一个自定义的logger，你必须首先实现这个接口。你可以参考在/extension目录下的几个例子。

　　ILog接口的定义如下：

　　

public interface ILog
　{
  　　void Debug(object message);
  　　void Info(object message);
  　　void Warn(object message);
  　　void Error(object message);
  　　void Fatal(object message);

　　　//以上的每一个方法都有一个重载的方法，用来支持异常处理。

　　　//每一个重载方法都如下所示，有一个异常类型的附加参数。
  　　void Debug(object message, Exception ex);
  　　// ...

　　  //Boolean 属性用来检查Logger的日志级别

　　　//（我们马上会在后面看到日志级别）
  　　bool isDebugEnabled;
  　　bool isInfoEnabled;
  　　//… 其他方法对应的Boolean属性
}

　　Log4net框架定义了一个叫做LogManager的类，用来管理所有的logger对象。它有一个GetLogger()静态方法，用我们提供的名字参数来检索已经存在的Logger对象。如果框架里不存在该Logger对象，它也会为我们创建一个Logger对象。代码如下所示：

　　log4net.ILog log = log4net.LogManager.GetLogger("logger-name");

　　通常来说，我们会以类（class）的类型（type）为参数来调用GetLogger()，以便跟踪我们正在进行日志记录的类。传递的类(class)的类型(type)可以用typeof(Classname)方法来获得，或者可以用如下的反射方法来获得：

　　System.Reflection.MethodBase.GetCurrentMethod().DeclaringType

　　尽管符号长了一些，但是后者可以用于一些场合，比如获取调用方法的类(class)的类型(type)。

1.2     日志的级别

　　正如你在ILog的接口中看到的一样，有五种不同的方法可以跟踪一个应用程序。事实上，这五种方法是运作在Logger对象设置的不同日志优先级别上。这几种不同的级别是作为常量定义在log4net.spi.Level类中。你可以在程序中使用任何一种方法。但是在最后的发布中你也许不想让所有的代码来浪费你的CPU周期，因此，框架提供了7种级别和相应的Boolean属性来控制日志记录的类型。

　　

　　Level有以下几种取值

级别	允许的方法	Boolean属性	优先级别
OFF			Highest
FATAL	void Fatal(...);	bool IsFatalEnabled;
RROR	void Error(...);	bool IsErrorEnabled;
WARN	void Warn(...);	bool IsWarnEnabled;
INFO	void Info(...);	bool IsInfoEnabled;
DEBUG	void Debug(...);	bool IsDebugEnabled;
ALL			Lowest

表1  Logger的日志级别

　　在log4net框架里，通过设置配置文件，每个日志对象都被分配了一个日志优先级别。如果没有给一个日志对象显式地分配一个级别，那么该对象会试图从他的祖先继承一个级别值。

　　ILog接口的每个方法都有一个预先定义好了的级别值。正如你在表1看到的，ILog的Inof()方法具有INFO级别。同样的，以此类推，Error()方法具有ERROR级别。当我们使用以上的任何一种方法时，log4net框架会检查日志对象logger的级别和方法的级别。只有当方法的级别高于日志级别时，日志请求才会被接受并执行。

　　举例说明，当你创建了一个日志对象，并且把他的级别设置为INFO。于是框架会设置日志的每个Boolean属性。当你调用相应的日志方法时，框架会检查相应的Boolean属性，以决定该方法能不能执行。如下的代码：

　　Logger.Info("message");

　　Logger.Debug("message");

　　Logger.Warn("message");

　　对于第一种方法，Info()的级别等与日志的级别（INFO），因此日志请求会被传递，我们可以得到输出结果”message”。

　　对于第二种方法，Debug()的级别低于日志对象logger的日志级别(INFO)，因此，日志请求被拒绝了，我们得不到任何输出。同样的，针对第三行语句，我们可以很容易得出结论。

　　在表1中有两个特殊的级别：ALL和OFF。ALL表示允许所有的日志请求。OFF是拒绝所有的请求。

　　你也可以显式地检查Logger对象的Boolean属性，如下所示：

　　if (logger.IsDebugEnabled)

　　{

  　　　　Logger.Debug("message");

　　}

1.3 Repository

　　Repository主要用于负责日志对象组织结构的维护。在log4net的以前版本中，框架仅支持分等级的组织结构(hierarchical organization)。这种等级结构本质上是库的一个实现，并且定义在log4net.Repository.Hierarchy 名字空间中。要实现一个Repository，需要实现log4net.Repository.ILoggerRepository 接口。但是通常并不是直接实现该接口，而是以log4net.Repository.LoggerRepositorySkeleton为基类继承。体系库 (hierarchical repository )则由log4net.Repository.Hierarchy.Hierarchy类实现。

　　如果你是个log4net框架的使用者，而非扩展者，那么你几乎不会在你的代码里用到Repository的类。相反的，你需要用到LogManager类来自动管理库和日志对象。

1.4 Appender

　　一个好的日志框架应该能够产生多目的地的输出。比如说输出到控制台或保存到一个日志文件。log4net 能够很好的满足这些要求。它使用一个叫做Appender的组件来定义输出介质。正如名字所示，这些组件把它们附加到Logger日志组件上并将输出传递到输出流中。你可以把多个Appender组件附加到一个日志对象上。 Log4net框架提供了几个Appender组件。关于log4net提供的Appender组件的完整列表可以在log4net框架的帮助手册中找到。有了这些现成的Appender组件，一般来说你没有必要再自己编写了。但是如果你愿意，可以从log4net.Appender.AppenderSkeleton类继承。

1.5 Appender Filters

　　一个Appender 对象缺省地将所有的日志事件传递到输出流。Appender的过滤器(Appender Filters) 可以按照不同的标准过滤日志事件。在log4net.Filter的名字空间下已经有几个预定义的过滤器。使用这些过滤器，你可以按照日志级别范围过滤日志事件，或者按照某个特殊的字符串进行过滤。你可以在API的帮助文件中发现更多关于过滤器的信息。

1.6 Layout

　　Layout 组件用于向用户显示最后经过格式化的输出信息。输出信息可以以多种格式显示，主要依赖于我们采用的Layout组件类型。可以是线性的或一个XML文件。Layout组件和一个Appender组件一起工作。API帮助手册中有关于不同Layout组件的列表。一个Appender对象，只能对应一个Layout对象。要实现你自己的Layout类，你需要从log4net.Layout.LayoutSkeleton类继承，它实现了ILayout接口。

          

二. 在程序中使用log4net

　　在开始对你的程序进行日志记录前，需要先启动log4net引擎。这意味着你需要先配置前面提到的三种组件。你可以用两种方法来设定配置：在单独的文件中设定配置或在代码中定义配置。

　　因为下面几种原因，推荐在一个单独的文件中定义配置：

　　　　你不需要重新编译源代码就能改变配置；

　　　　你可以在程序正运行的时候就改变配置。这一点在一些WEB程序和远程过程调用的程序中有时很重要；

　　考虑到第一种方法的重要性，我们先看看怎样在文件中设定配置信息。

2.1 定义配置文件

　　配置信息可以放在如下几种形式文件的一种中。

　　在程序的配置文件里，如AssemblyName.config 或web.config.

　　在你自己的文件里。文件名可以是任何你想要的名字，如AppName.exe.xyz等.

　　log4net框架会在相对于AppDomain.CurrentDomain.BaseDirectory 属性定义的目录路径下查找配置文件。框架在配置文件里要查找的唯一标识是<log4net>标签。一个完整的配置文件的例子如下：

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler,log4net-net-1.0"/>
  </configSections>
  <log4net>
    <root>
      <level value="WARN" />
      <appender-ref ref="LogFileAppender" />
      <appender-ref ref="ConsoleAppender" />
    </root>
    <logger name="testApp.Logging">
      <level value="DEBUG"/>
    </logger>
    <appender name="LogFileAppender"  type="log4net.Appender.FileAppender" >
      <param name="File" value="log-file.txt" />
      <param name="AppendToFile" value="true" />
      <layout type="log4net.Layout.PatternLayout">
        <param name="Header" value="[Header]\r\n"/>
        <param name="Footer" value="[Footer]\r\n"/>
        <param name="ConversionPattern" value="%d [%t] %-5p %c [%x]  - %m%n"/>
      </layout>
      <filter type="log4net.Filter.LevelRangeFilter">
        <param name="LevelMin" value="DEBUG" />
        <param name="LevelMax" value="WARN" />
      </filter>
    </appender>
    <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender" >
      <layout type="log4net.Layout.PatternLayout">
        <param name="ConversionPattern" value="%d [%t] %-5p %c [%x] - %m%n"/>
      </layout>
   </appender>
  </log4net>
</configuration>

　　你可以直接将上面的文本拷贝到任何程序中使用，但是最好还是能够理解配置文件是怎样构成的。 只有当你需要在应用程序配置文件中使用log4net配置时，才需要在<configSection>标签中加入<section>配置节点入口。对于其他的单独文件，只有<log4net>标签内的文本才是必需的，这些标签的顺序并不是固定的。下面我们依次讲解各个标签内文本的含义：

2.2 <root>

<root>
  <level value="WARN" />
  <appender-ref ref="LogFileAppender" />
  <appender-ref ref="ConsoleAppender" />
</root>

　　在框架的体系里，所有的日志对象都是根日志(root logger)的后代。 因此如果一个日志对象没有在配置文件里显式定义，则框架使用根日志中定义的属性。在<root>标签里，可以定义level级别值和Appender的列表。如果没有定义LEVEL的值，则缺省为DEBUG。可以通过<appender-ref>标签定义日志对象使用的Appender对象。<appender-ref>声明了在其他地方定义的Appender对象的一个引用。在一个logger对象中的设置会覆盖根日志的设置。而对Appender属性来说，子日志对象则会继承父日志对象的Appender列表。这种缺省的行为方式也可以通过显式地设定<logger>标签的additivity属性为false而改变。

　　<logger name="testApp.Logging" additivity="false">

　　</logger>

　　Additivity的值缺省是true.

2.3 <Logger>

<logger name="testApp.Logging">
  <level value="DEBUG"/>
</logger>

　　<logger> 元素预定义了一个具体日志对象的设置。然后通过调用LogManager.GetLogger(“testAPP.Logging”)函数，你可以检索具有该名字的日志。如果LogManager.GetLogger(…)打开的不是预定义的日志对象，则该日志对象会继承根日志对象的属性。知道了这一点，我们可以说，其实<logger>标签并不是必须的。

2.4 <appender>

<appender name="LogFileAppender" type="log4net.Appender.FileAppender" >
  <param name="File" value="log-file.txt" />
  <param name="AppendToFile" value="true" />
  <layout type="log4net.Layout.PatternLayout">
    <param name="Header" value="[Header]\r\n" />
    <param name="Footer" value="[Footer]\r\n"/>
    <param name="ConversionPattern" value="%d [%t] %-5p %c - %m%n"/>
  </layout>
  <filter type="log4net.Filter.LevelRangeFilter">
    <param name="LevelMin" value="DEBUG" />
    <param name="LevelMax" value="WARN" />
  </filter>
</appender>

　　在<root>标签或单个的<logger>标签里的Appender对象可以用<appender>标签定义。<appender>标签的基本形式如上面所示。它定义了appender的名字和类型。 另外比较重要的是<appender>标签内部的其他标签。不同的appender有不同的<param>标签。在这里，为了使用FileAppender,你需要一个文件名作为参数。另外还需要一个在<appender>标签内部定义一个Layout对象。Layout对象定义在它自己的<layout>标签内。<layout>标签的type属性定义了Layout的类型(在本例里是PatternLayout)，同时也确定了需要提供的参数值。Header和Footer标签提供了一个日志会话(logging session)开始和结束时输出的文字。有关每种appender的具体配置的例子，可以在log4net\doc\manual\example-config-appender.html中得到。

2.5  log4net.Layout.PatternLayout中的转换模式(ConversionPattern)

　　%m(message):输出的日志消息，如ILog.Debug(…)输出的一条消息

　　%n(new line):换行

　　%d(datetime):输出当前语句运行的时刻

　　%r(run time):输出程序从运行到执行到当前语句时消耗的毫秒数

　　%t(thread id):当前语句所在的线程ID

　　%p(priority): 日志的当前优先级别，即DEBUG、INFO、WARN…等

　　%c(class):当前日志对象的名称，例如：

       模式字符串为：%-10c-%m%n

       代码为：

　　ILog log=LogManager.GetLogger(“Exam.Log”);

　　log.Debug(“Hello”);

     则输出为下面的形式：

　　Exam.Log       - Hello

　　%L：输出语句所在的行号

　　%F：输出语句所在的文件名

　　%-数字：表示该项的最小长度，如果不够，则用空格填充

　　例如，转换模式为%r [%t]%-5p %c - %m%n 的 PatternLayout 将生成类似于以下内容的输出：

　　176 [main] INFO  org.foo.Bar - Located nearest gas station.

2.6 <filter>

　　最后，让我们看看在Appender元素里的<filter>标签。它定义了应用到Appender对象的过滤器。本例中，我们使用了LevelRangeFilter过滤器,它可以只记录LevelMin和LevelMax参数指定的日志级别之间的日志事件。可以在一个Appender上定义多个过滤器（Filter）,这些过滤器将会按照它们定义的顺序对日志事件进行过滤。其他过滤器的有关信息可以在log4net的SDK文档中找到。