NLog处理异常使用说明书

一.NLog简要介绍:                                    

1.NLog是一个简单灵活的.NET日志记录类库。通过使用NLog，我们可以在任何一种.NET语言中输出带有上下文的（contextual information）调试诊断信息，根据喜好配置其表现样式之后发送到一个或多个输出目标（target）中。

2.NLog的API非常类似于log4net，且配置方式非常简单。NLog使用路由表（routing table）进行配置，但log4net却使用层次性的appender配置，这样就让NLog的配置文件非常容易阅读，并便于今后维护。

3.NLog遵从BSD license，即允许商业应用且完全开放源代码。任何人都可以免费使用并对其进行测试，然后通过邮件列表反馈问题以及建议。

4.NLog支持.NET、C/C++以及COM interop API，因此我们的程序、组件、包括用C++/COM 编写的遗留模块都可以通过同一个路由引擎将信息发送至NLog中。

5.NLog的.NET API的过滤信息功能执行效率很高，这样我们就可以一直保留程序中的日志写入代码，然后由NLog在运行时将其根据需要过滤掉。在一个1.6G单CPU笔记本电脑上，NLog每秒钟可以过滤掉1.5亿条日志写入语句！加上异步处理（asynchronous processing）以及其他包装程序（wrappers）的支持，NLog将成为一个极为强大的、且极具伸缩性的日志记录工具.

二.NLog中Logger类的方法解释:

1.   Trace - 最常见的记录信息，一般用于普通输出

2.   Debug - 同样是记录信息，不过出现的频率要比Trace少一些，一般用来调试程序

3.   Info - 信息类型的消息

4.   Warn - 警告信息，一般用于比较重要的场合

5.   Error - 错误信息

6.   Fatal - 致命异常信息。一般来讲，发生致命异常之后程序将无法继续执行。

 

以下的方法让你决定是否将日志用于特定的等级:

1.IsEnabled() –决定日志是否能用于特定的等级.

2.IsTraceEnabled –决定日志是否能用于Trace这个等级

3.IsDebugEnabled – 决定日志是否能用于Debug这个等级

4.IsInfoEnabled –决定日志是否能用于Info这个等级

5.IsWarnEnabled – 决定日志是否能用于Warn这个等级

6.IsErrorEnabled – 决定日志是否能用于Error这个等级

7.IsFatalEnabled – 决定日志是否能用于Fatal这个等级

以下是英文原文:

The NLog.Logger class has the following methods. Each method has a number of overloads designed to minimize the number of memory allocations in order to improve logging speed. Click on a method name to see the list of overloads for it.

• Log() - Writes the diagnostic message at the specified level using the specified format provider and format parameters.
• Trace() - Writes the diagnostic message at the Trace level using the specified format provider and format parameters.
• Debug() - Writes the diagnostic message at the Debug level using the specified format provider and format parameters.
• Info() - Writes the diagnostic message at the Info level using the specified format provider and format parameters.
• Warn() - Writes the diagnostic message at the Warn level using the specified format provider and format parameters.
• Error() - Writes the diagnostic message at the Error level using the specified format provider and format parameters.
• Fatal() - Writes the diagnostic message at the Fatal level using the specified format provider and format parameters.

The following methods and properties let you determine whether logging is enabled for the specified level:

• IsEnabled() - Determines if logging is enabled for the specified level.
• IsTraceEnabled - Determines if logging is enabled for the Trace level.
• IsDebugEnabled - Determines if logging is enabled for the Debug level.
• IsInfoEnabled - Determines if logging is enabled for the Info level.
• IsWarnEnabled - Determines if logging is enabled for the Warn level.
• IsErrorEnabled - Determines if logging is enabled for the Error level.

Full list of members of the Logger class can be found here.

三. 配置文件详细配置过程

通过在启动的时候对一些常用目录的扫描，NLog会尝试使用找到的配置信息进行自动的自我配置。当你运行一个独立的*.exe客户端可执行程序时，NLog将在以下目录搜索配置信息：

1. 标准的程序配置文件（通常为 程序名.exe.config）
2. 程序目录下的程序名.exe.nlog文件
3. 程序目录下的NLog.config文件
4. NLog.dll所在目录下的NLog.dll.nlog文件
5. 如果定义了NLOG_GLOBAL_CONFIG_FILE环境变量，则该变量所指向的文件

如果是一个ASP.NET程序，被搜索的目录包括：

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

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

1. 程序目录下的NLog.config文件
2. NLog.dll所在目录下的NLog.dll.nlog文件
3. 如果定义了NLOG_GLOBAL_CONFIG_FILE环境变量，则该变量所指向的文件

 

配置文件格式

 NLog支持两种配置文件格式

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

如果你选择了第一种方式，使用的是标准的configSections这种机制，那么你的配置文件看起来差不多是这个样子：

<configuration>

  <configSections>

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

  </configSections>

  <nlog>

  </nlog>

</configuration>

单一格式的配置文件就是一个以<nlog />为根节点的纯XMl文件。命名空间并不强制使用，如果使用的话我们就可以利用Visual Studio的智能感应。

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

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

</nlog>

需要注意的是NLog的配置文件总是大小写敏感的，不管是在使用的时候，或者即使你没有使用名字空间。当然只有你的大小写符合要求，智能感应才能正常工作。

 

配置元素

下面这些元素可以作为<nlog />的字节点。列表中的前两个元素在所有的NLog配置文件中都必须提供，其余的则可以选择使用，通常用于一些复杂场景。

1. <targets /> - 定义日志的目标/输出
2. <rules /> - 定义日志的路由规则
3. <extensions /> - 从*.dll加载NLog扩展
4. <include /> - 导入外部配置文件
5. <variable /> - 为配置变量赋值

 

输出目标

<target />区域定义了日志的目标或者说输出。每一个<target />元素代表一个目标。我们需要为每一个目标设置两个属性：

1. name - 目标的名称
2. type - 目标的类型 - 比如“File”，“Database”，“Mail”。如果你使用了名字空间，这个属性会被命名为 xsi:type.

除了这两个属性，通常来说给目标添加一些其它参数，这些属性将会影响你在程序中如何使用诊断跟踪语句（diagnostic traces）。每一个目标都可以有一组不同的参数集合，并且参数都是上下文相关的，你可以在本项目的主页上找到更多关于参数的详细说明。Visual Studio的智能感应对这些参数同样有用。

举个例子 - “File”目标可以使用“fileName”作为参数来定义输出文件名，而“Console”目标可以借助“error”参数的值来判断是否应该把当前进程的diagnostic traces结果输出到标准错误（stderr）还是标准输出（stdout）控制台。

下面这个例子演示了在<targets />区域同时定义多个目标：两个files目标，一个network目标和一个OutputDebugString目标：

<targets>

  <target name="f1" xsi:type="File" fileName="file1.txt"/>

  <target name="f2" xsi:type="File" fileName="file2.txt"/>

  <target name="n1" xsi:type="Network" address="tcp://localhost:4001"/>

  <target name="ds" xsi:type="OutputDebugString"/>

</targets>

NLog提供了许多已经预先定义好的目标。关于这些目标的详细说明请参考本项目的主页。实际上，你也可以很容易的为自己创建目标 - 全部只需大约15-20行代码即可，更多信息请参考项目文档。

 

路由规则

<rules />区域定义了日志的路由规则。实际上它是一个简单的路由表，对每一个日志源/记录者的名称和记录等级的组合，定义了一个日志写入目标列表。 表中的规则是被顺序处理的。每当遇到匹配的规则时，日志信息就会被送到规则中定义的一个或多个目标去。如果一个规则被标识为最后一个，那么其后的规则都不会被执行。

每一个路由表项就是一个<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")。

最简单的情况下，整个日志的配置信息可以只由一个<target />元素和一个<logger />规则构成，就可以吧一定级别的日志信息路由到期望的目标去。随着程序不断的变大，增加新的目标和规则也很简单。

 

上下文信息

布局由被一个美元符号$加左大括弧“${”和一个右大括弧“}”为标记所包围的文本所组成。这个标记也就是所谓的“布局生成器（layout renderers），我们可以用它来把一些上下文相关的信息插入到日志信息中。布局可以应用在许多地方，比如可以被用在控制输出到屏幕或写入文件信息的格式，也可以用在控制文件名。接下来我们会更多的了解布局的强大。

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

·         当前的日期和时间

·         产生日志信息的类和方法的名字

·         日志等级

·         日志内容

利用Layout来实现很简单：

<target name="c" xsi:type="Console"

  layout="${longdate} ${callsite} ${level} ${message}"/>

或者我们可以把每一个日志记录者生成的日志信息输出到一个单独的文件里：

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

这里我们看到fileName属性的值被设置为布局生成器${logger}，从而使每一条日志信息被写到一个以日志生成者名字命名的一个文件里。上面这个例子将生成如下一系列文件：

·         Name.Space.Class1.txt

·         Name.Space.Class2.txt

·         Name.Space.Class3.txt

·         Other.Name.Space.Class1.txt

·         Other.Name.Space.Class2.txt

·         Other.Name.Space.Class3.txt

·         ...

有一个常见需求是能够用日期信息来区分日志文件。如果使用${shortdate}布局生成器，这简直太容易了：

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

那么可以给每一个职员生成一个日志文件吗？答案就是${windows-identity}布局生成器：

<target name="f" xsi:type="File" fileName="${windows-identity:domain=false}.txt"/>

这样我们就能够给每一个职员生成一个日志文件了：

1. Administrator.txt
2. MaryManager.txt
3. EdwardEmployee.txt
4. ...

更复杂的场景也能做到。下面这个例子说明了如何为每个人每天生成一个日志文件。每天的日志文件存放在不同的文件夹里：

<target name="f" xsi:type="File"