NLog类库使用探索——详解配置

2 进入正题

2.1 定义

     官方定义：NLog is a free logging platform for .NET, Silverlight and Windows Phone with rich log routing and management capabilities. It makes it easy to produce and manage high-quality logs for your application regardless of its size or complexity. 简单的来说NLog就是一个开源的日志管理平台，支持.net，Silverlight，Windows Phone。有着丰富的路由和管理功能。能够很容易的生成和管理你的项目日志。

NLog is an open source project hosted on GitHub and source code is available under the terms of BSD license. //在GitHub可以下到源码，源码是基于BSD　License的

Binary packages are available via NuGet. ／／可以通过NuGet将类库直接导入到项目中去

验的“新生”来说。苦逼的是

2.2 NLog的特性

          简单的来说NLog能够导出基于.NET语言的（C#，VB）所有的诊断信息。通过数据上下文（contextual information，包含了发生时间，线程，进程，严重程度等）来格式化你想要导出的信息，打出到哪里呢？Nlog提供了导出目标（targets 文本、数据库、Email、控制台等）

2.3 配置实用

          very easy to configure, both through configuration file and programmatically。官方文档中这句算是最重要的了，通过它展示了如何应用到自己的项目中去。提供了两种方式：配置文件和后台编程都可以。

• Files - single file or multiple, with automatic file naming and archival
• Event Log - local or remote
• Database - store your logs in databases supported by .NET
• Network - using TCP, UDP, SOAP, MSMQ protocols
• Command-line console - including color coding of messages
• E-mail - you can receive emails whenever application errors occur

      以上相关链接，给出了向文件，远程日志，数据库，邮箱等为目标的日志输出相关例子，用时查阅即可。下面结合项目实例，简单了解下最简单的使用过程。

3、项目实例

3.1 输出目标为控制台的小例子

          第一步：通过NetGet导入类库dll。

       第二步：打开配置文件NLog.config

      第三步：定义导出目标和输出哪些信息

       添加目标，并指定输出的布局，也就是说我们想把项目日志输出到哪里，输出的格式是什么？

   <target xsi:type="Console" name="Conso"                           layout="${longdate} ${uppercase:${level}} ${message}" />

      layout是固定格式，${}是语法格式，这里分别输出的信息分别为：时间，级别，信息

     第四步：定义输出规则

     我们到底要输出哪些信息到日志文件中去，这就涉及到了记录等级的问题。

    记录等级（log level）信息，用来描述该条信息的重要性。NLog支持如下几种记录等级：

1. Trace - 最常见的记录信息，一般用于普通输出
2. Debug - 同样是记录信息，不过出现的频率要比Trace少一些，一般用来调试程序
3. Info - 信息类型的消息
4. Warn - 警告信息，一般用于比较重要的场合
5. Error - 错误信息
6. Fatal - 致命异常信息。一般来讲，发生致命异常之后程序将无法继续执行。

     这个小例子，我们把输出等级设为等级等于或高于Debug等级的信息输出至控制台

<logger name="*" minlevel="Debug" writeTo="Conso"></logger>  这句话很明了但需要说明的是write to属性应该是target的名字。意思是写到输出目标里面。

    第五步：创建logger对像，若希望生成并输出诊断信息，我们还需要添加一个Logger对象。Logger对象的方法名和记录等级的名称一样（Debug()、Info()、Fatal()……）。Logger对象是通过LogManager对象创建的。建议Logger对象的名称和程序的类名保持一致。调用LogManager的GetCurrentClassLogger()方法即可自动为当前类创建一个Logger对象。后台代码如下：

using NLog;
namespace WpfApplication4
{
    /// <summary>
    /// MainWindow.xaml 的交互逻辑
    /// </summary>
    public partial class MainWindow : Window
    {
        public static Logger mainwindowLogger = LogManager.GetCurrentClassLogger();//该Logger对象代表与当前类相关联的日志消息的来源。 
        public MainWindow()
        {
            InitializeComponent();
            mainwindowLogger.Debug("模拟一条Debug级别的信息");//发出一条Debug记录等级的诊断信息。
        }
    }
}

通过以上几步，应该基本了解了Nlog的工作流程。配置文件中配置输出目标，要输出哪些诊断信息（layout），并定义输出规则，什么等级的信息输出。应用程序后台代码中使用logger对象定义输出的诊断信息。

3.2 进一步的扩展这个例子

          我们新增加一个需求，如果同时输出到一个文件呢？该如何做？这也不难，需要修改配置文件就行。添加一个target即可。

         

        

        两幅图已经很说明问题，不再详细描述。

4、小结

              零零散散写了个简单的例子，只供像我这种入门级别的人看看罢了,下一篇，继续深入探讨NLog。

 

 

1 配置文件的位置(Configuration file locations)

    通过在启动的时候对一些常用目录的扫描，NLog会尝试使用找到的配置信息进行自动的自我配置。

1.1 单独的*.exe客户端

    单独的客户端，NLog将在以下目录搜索配置信息：

1. 标准的程序配置文件（通常为 程序名.exe.config）
2. 程序目录下的程序名.exe.nlog文件
3. 程序目录下的NLog.config文件
4. NLog.dll所在目录下的NLog.dll.nlog文件 （在Nlog没有导入GAC情况下）

1.2 ASP.NET程序

    在ASP.NET项目中搜索的目录包括：

1. 标准的web程序配置文件web.config
2. 和web.config在同一目录下的web.nlog文件
3. 程序目录下的NLog.config文件
4. NLog.dll所在目录下的NLog.dll.nlog文件 （在Nlog没有导入GAC情况下）
5. 如果定义了NLOG_GLOBAL_CONFIG_FILE环境变量，则该变量所指向的文件

1.2 硬件设备类库（.NET Compact Framework）

    .NET Compact Framework不支持程序配置文件（*.exe.config）和环境变量，因此NLog将只会扫描这些地方：

1. 程序目录下的NLog.config文件
2. NLog.dll所在目录下的NLog.dll.nlog文件 （在Nlog没有导入GAC情况下）

1.4 小结

      从上面来看，不管哪个我们把配置文件命名为NLog.config，放在应用程序的目录下，肯定都可以扫描到，哈哈。

2 配置文件的格式(Configuration file format)

   2.1  NLog支持两种配置文件格式

1. 配置信息嵌入在.NET应用程序标准的*.exe.config或者web.config文件里
2. 保存在独立文件里

   第一种就是我们熟悉的常规配置，使用configSections

<configuration>
  <configSections>
    <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog"/>
  </configSections>
  <nlog>
  </nlog>
</configuration>

    如果是第二种，是一个单独的Xml文件的话，需要按如下配置：

<nlog xmlns=http://www.nlog-project.org/schemas/NLog.xsd

      xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance >
</nlog>

    需要说明的是，根节点是<nlong></nlong>,两个命名空间是可选的，但是为了智能感应，你还是把它写上吧。

2.1 子元素的配置

• <targets /> – defines log targets/outputs ，声明目标
• <rules /> – defines log routing rules ，声明规则
• <extensions /> – loads NLog extensions from the *.dll file  加载dll扩展（其实我不懂，没用过）
• <include /> – includes external configuration file   包含外部配置文件
• <variable /> – sets the value of a configuration variable 为配置变量赋值

     需要说明的是前两个元素，也就是targets和rules是必需配置的，其余是可选的，应该用于更复杂的配置上，我个人没用过还。

3 输出目标(Targets )

      第一篇文章已经介绍过，应该不用再解释，具体输出到那个目标的详细配置，参见文档：https://github.com/nlog/NLog/wiki/Targets

4 路由规则(Rules)

   <rules />区域定义了日志的路由规则。每一个路由表项就是一个<logger />元素。<logger />有以下属性：

1. name - 日志源/记录者的名字 (允许使用通配符*)
2. minlevel - 该规则所匹配日志范围的最低级别
3. maxlevel - 该规则所匹配日志范围的最高级别
4. level - 该规则所匹配的单一日志级别
5. levels - 该规则所匹配的一系列日志级别，由逗号分隔。
6. writeTo - 规则匹配时日志应该被写入的一系列目标，由逗号分隔。
7. final - 标记当前规则为最后一个规则。其后的规则即时匹配也不会被运行。

   如：

1. <logger name="Name.Space.Class1" minlevel="Debug" writeTo="f1" /> - 名字空间Name.Space下的Class1这个类的所有级别等于或者高于Debug的日志信息都写入到“f1”这个目标里。
2. <logger name="Name.Space.Class1" levels="Debug,Error" writeTo="f1" /> -名字空间Name.Space下的Class1这个类的所有级别等于Debug或Error的日志信息都写入到“f1”这个目标里。
3. <logger name="Name.Space.*" writeTo="f3,f4" /> -名字空间Name.Space下所有类的所有级别的日志信息都写入到“f3”和“f4”这两个目标里。
4. <logger name="Name.Space.*" minlevel="Debug" maxlevel="Error" final="true" /> - 名字空间Name.Space下所有类的、级别在Debug和Error之间的(包括Debug,Info,Warn,Error) 日志信息都不会被记录(因为这条规则没有定义writeTo)，同时其它后续规则也都会被忽略(因为这里设置了final="true")。

5 上下文布局信息(Layouts and layout renderers)

     NLog最强大的功能之一就是使用布局（layouts）的能力。语法为：“${属性}”为标记所包围的文本所组成。这个标记也就是所谓的“布局生成器（layout renderers），我们可以用它来把一些上下文相关的信息插入到日志信息中。布局可以应用在许多地方，比如可以被用在控制输出到屏幕或写入文件信息的格式，也可以用在控制文件名。

假设我们希望每个输出到控制台的信息都包含一些这些信息：

• 当前的日期和时间
• 产生日志信息的类和方法的名字
• 日志等级
• 日志内容

利用Layout来实现很简单：，前面已经提到过：

<target name="c" xsi:type="Console"  layout="${longdate} ${callsite} ${level} ${message}"/>

使用Layout控制输出的文件名：

<target name="f" xsi:type="File" fileName="${logger}.txt"/>

使用日期来区分日志文件。如果使用${shortdate}布局生成器：

<target name="f" xsi:type="File" fileName="${shortdate}.txt"/>

更多的布局生成器参考官方文档：

https://github.com/nlog/NLog/wiki/Layout%20Renderers

6 包含配置文件(Include files)

    我们有这样的需求，不想让NLog.cofige文件太大，太多，读起来太累，我们可以把它分割下。如何分割成若干小的config呢？使用include简单完成。

<nlog>
  ...
  <include file="${basedir}/${machinename}.config"/>
  ...
</nlog>

制定了要包含的config小文件位置就行。

7 变量(Variables)

配置文件中也可以定义变量，直接上例子，很明了：

//声明语法

<variable name="var" value="xxx" />

<nlog>
  <variable name="logDirectory" value="${basedir}/logs/${shortdate}"/>
  <targets>
    <target name="file1" xsi:type="File" fileName="${logDirectory}/file1.txt"/>
    <target name="file2" xsi:type="File" fileName="${logDirectory}/file2.txt"/>
  </targets>
</nlog>

8 自动再配置(Automatic reconfiguration)

    听起来确实挺不好理解的。但是确实也没什么。换句简单的话来说，当我们一旦启动程序，这时候NLog.config文件被读取后，知道程序再启动都不会再读取配置文件了。假如我们不想停掉程序，比如说服务器哪能说停就停哈。这就用上这个配置了，这个配置功能是，一旦你对配置文件修改，程序将会重新读取配置文件，也就是自动再配置。直接上代码：

<nlog autoReload="true">
   ...
</nlog>

9 日志排错(Troubleshooting logging)

       程序没问题了，日志却出了问题。这个该怎么办，到底是哪里不正确了？假如日志本身除了bug该如何解决？这就需要日志排错。把日志的错误信息写入日志。

• <nlog throwExceptions="true" />    
• <nlog internalLogFile="file.txt" />- 设置internalLogFile属性可以让NLog把内部的调试和异常信息都写入指定文件里。
• <nlog internalLogLevel="Trace|Debug|Info|Warn|Error|Fatal" /> - 决定内部日志的级别，级别越高，输出的日志信息越简洁。
• <nlog internalLogToConsole="false|true" /> - 是否把内部日志输出到标准控制台。
• <nlog internalLogToConsoleError="false|true" /> - 是否把内部日志输出到标准错误控制台 (stderr)。

      设置throwExceptions属性为“true”可以让NLog不再阻挡这类异常，而是把它们抛给调用者。在部署是这样做可以帮我们快速定位问题。一旦应用程序已经正确配置了，我们建议把throwExceptions的值设为“false”，这样由于日志引发的问题不至于导致应用程序的崩溃。

10、异步处理(Asynchronous processing )

       原理也不多说，直接上代码，使其具备异步处理能力。

<nlog>
  <targets async="true">
    <!-- all targets in this section will automatically be asynchronous -->
  </targets>
</nlog>

11 缺省封装(Default  wrappers)

    我们希望用同一种封装来处理所有的目标，比如说增加缓冲和/或自动重试功能。

   NLog为此提供了专门的语法：<default-wrapper />。你只要把这个元素放在<targets />区域里，然后所有的目标都会自动加载同一个封装目标。需要注意的是<default-wrapper />只对当前这个<targets />区域有效，而你可以使用多个<targets />区域，这样你就可以把目标分组并用不同的封装目标处理。

<nlog>  
  <targets>  
    <default-wrapper xsi:type="BufferingWrapper" bufferSize="100"/>  
    <target name="f1" xsi:type="File" fileName="f1.txt"/>  
    <target name="f2" xsi:type="File" fileName="f2.txt"/>  
  </targets>  
  <targets>  
    <default-wrapper xsi:type="AsyncWrapper">  
      <wrapper-target xsi:type="RetryingWrapper"/>  
    </default-wrapper>  
    <target name="n1" xsi:type="Network" address="tcp://localhost:4001"/>  
    <target name="n2" xsi:type="Network" address="tcp://localhost:4002"/>  
    <target name="n3" xsi:type="Network" address="tcp://localhost:4003"/>  
  </targets>  
</nlog>

上面的例子里我们定义了两个缓冲文件目标和三个异步以及自动重试网络目标。

12 缺省目标参数（Default target parameters）

     其实缺省就是把分散的统一在一个区域来定义，仅仅是个语法糖问题，缺省参数自然是把参数相同的抽象出来放到一个区域，统一定义罢了。下面代码是等价的。

<nlog> 
  <targets> 
    <target name="f1" xsi:type="File" fileName="f1.txt" keepFileOpen="false"/> 
    <target name="f2" xsi:type="File" fileName="f2.txt" keepFileOpen="false"/> 
    <target name="f3" xsi:type="File" fileName="f3.txt" keepFileOpen="false"/> 
  </targets> 
</nlog>

<nlog>
  <targets>
    <default-target-parameters xsi:type="File" keepFileOpen="false"/>
    <target name="f1" xsi:type="File" fileName="f1.txt"/>
    <target name="f2" xsi:type="File" fileName="f2.txt"/>
    <target name="f3" xsi:type="File" fileName="f3.txt"/>
  </targets>
</nlog>