NLog学习笔记二：深入学习

配置文件

NLog所有的配置信息都可以写到一个单独的xml文件中，也可以在程序代码中进行配置。

配置文件位置

启动的时候，NLog会试图查找配置文件完成自动配置，查找的文件依次如下（找到配置信息则结束查询）：

1. 应用程序的标准配置文件（通常为applicationname.exe.config）
2. 应用程序所在目录中的applicationname.exe.nlog文件
3. 应用程序所在目录中的NLog.config文件
4. NLog.dll所在目录中的NLog.dll.nlog文件
5. 环境变量NLOG_GLOBAL_CONFIG_FILE所指向的文件

对于ASP.NET应用程序，NLog将自动按照顺序搜索下列路径：

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. 应用程序所在目录中的applicationname.exe.nlog文件
2. 应用程序所在目录中的NLog.config文件
3. NLog.dll所在目录中的NLog.dll.nlog文件

配置文件形式

NLog支持两种形式的配置文件：

1. 嵌入到*.exe.config或web.config等标准配置文件中
2. 单独的配置文件NLog.config

对于第一种形式，我们使用了标准化的configSection机制。这样配置文件将类似如下所示：

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

在配置文件的<nlog />根元素中，我们可以指定如下的子元素。其中前两个是必须设定的，其余三个为可选设定。

1. <targets /> ：定义日志的输出目标
2. <rules /> ：定义对日志信息进行路由的规则
3. <extensions /> ：定义从其他dll文件中加载的NLog扩展模块
4. <include /> ： 引入外部的配置文件
5. <variable /> ： 定义配置文件中用到的变量

例如：

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <!--***configSections节点必须位于顶部-->
  <configSections>
    <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog" requirePermission="false" />
  </configSections>
  
    <startup> 
        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
    </startup>

  <nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <targets>
      <target name="logfile" xsi:type="File" fileName="file.txt" />
    </targets>

    <rules>
      <logger name="*" minlevel="Info" writeTo="logfile" />
    </rules>
  </nlog>
</configuration>

代码中配置

NLog也可以通过编程配置，代码如下：

using NLog;
using NLog.Config;
using NLog.Targets;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace NLogConsoleDemo
{
    /// <summary>
    /// 测试在代码中配置NLog
    /// </summary>
    class Program
    {
        static void Main(string[] args)
        {
            // Step 1. Create configuration object 
            var config = new LoggingConfiguration();

            // Step 2. Create targets and add them to the configuration 
            var consoleTarget = new ColoredConsoleTarget();
            config.AddTarget("console", consoleTarget);

            var fileTarget = new FileTarget();
            config.AddTarget("file", fileTarget);

            // Step 3. Set target properties 
            consoleTarget.Layout = @"${date:format=HH:mm:ss} ${logger} ${message}";
            fileTarget.FileName = "${basedir}/file.txt";
            fileTarget.Layout = "${message}";

            // Step 4. Define rules
            var rule1 = new LoggingRule("*", LogLevel.Debug, consoleTarget);
            config.LoggingRules.Add(rule1);

            var rule2 = new LoggingRule("*", LogLevel.Debug, fileTarget);
            config.LoggingRules.Add(rule2);

            // Step 5. Activate the configuration
            LogManager.Configuration = config;

            // Example usage
            Logger logger = LogManager.GetLogger("Program");
            logger.Trace("trace log message");
            logger.Debug("debug log message");
            logger.Info("info log message");
            logger.Warn("warn log message");
            logger.Error("error log message");
            logger.Fatal("fatal log message");

            Console.ReadLine();
        }
    }
}

目标（Targets）

<targets />节点用来定义日志信息的输出位置。每一个输出位置都用一个<target />元素表示。<target />元素有两个必须设置的属性：

1. name - 输出目标的名称
2. type - 输出目标的类型，例如“File”、“DataBase”、“Mail”等。若我们为配置文件指定了命名空间，则该属性名为xsi:type。

除了上述两个必须设置的属性之外，<target />元素还支持一些其他的属性，同样可以影响记录诊断信息的方式。我们可以为每一个输出目标设定不同的属性参数，这些属性均在NLog的主页上有详细描述，且Visual Studio也都为其提供了智能感知功能支持。

例如：“File”输出目标接受一个名为fileName的参数，用来指定输出文件的名称；而“Console”输出目标则接受一个名为error的参数，表示是否用标准错误输出（stderr）代替标准输出（stdout）。

关于文件目标的详细介绍请查看File target，关于目标类型的详细介绍请查看Targets。

规则（Rules）

路由规则将定义在配置文件的<rules />节中。这部分内容就是一个简单的路由表，用来定义不同的日志源（Logger的名称）以及记录等级的日志信息将被发送至哪个输出目标中。路由规则将从列表中的第一项开始执行，如果符合当前的路由规则，则该条日志信息将被发送至指定的输出目标中，若路由表中任意一项都不满足，则该条日志信息将不会被处理。

路由表中的每一个条目都由一个<logger />元素定义，<logger />元素支持如下几个属性：

1. name - 日志源（Logger的名称），可以使用*通配符
2. minlevel -  匹配该规则需要的最低记录等级
3. maxlevel - 匹配该规则需要的最高记录等级
4. level - 匹配该规则需要的单一的记录等级
5. levels - 匹配该规则需要的记录等级列表，记录等级之间用逗号隔开
6. writeTo - 匹配该规则的日志信息将被发送至的输出目标列表，输出目标之间用逗号隔开
7. final - 让该规则成为日志信息的最后一个匹配条目。满足该条规则的日志信息被处理之后，将不会再继续尝试匹配下面定义的路由规则。

一些例子：

来自于命名空间Name.Space下Class1的、记录等级等于或高于Debug的日志信息将被发送至输出目标f1。

<logger name="Name.Space.Class1" minlevel="Debug" writeTo="f1" />

 来自于命名空间Name.Space下Class1的、记录等级等于为Debug或Error的日志信息将被发送至输出目标f1。

<logger name="Name.Space.Class1" levels="Debug,Error" writeTo="f1" />

 来自于命名空间Name.Space下任意类的任意日志信息将被发送至输出目标f3和f4。

<logger name="Name.Space.*" writeTo="f3,f4" />

 来自于命名空间Name.Space下任意类的、记录等级在Debug和Error之间（包括Debug、Info、Warn和Error）的日志信息将被忽略（没有writeTo属性），且也不会再被下面的路由规则处理（因为设置了final="true"）。

<logger name="Name.Space.*" minlevel="Debug" maxlevel="Error" final="true" />

在前面的示例程序中，配置文件只包含了一个<target />元素和一个<logger />元素。随着对程序的需求不断扩充，添加新的输出目标以及路由规则也将一样非常简单。

可用的日志等级如下（降序排序）：

• Fatal：致命异常信息，非常严重的错误。
• Erorr：错误信息，用于记录异常。
• Warn：警告信息，用于记录不正确的，但程序还可以允许的行为。
• Info：信息类型的消息，用于记录一般的操作。
• Debug：一般用来调试程序，用于记录查询、用户认证、session过期等。
• Trace：最常见的记录信息，一般用于普通输出，例如：开始于哪个方法，结束于哪个方法。

布局和布局渲染器（Layouts and layout renderers）

NLog最具优势的特性之一就是它的布局（layout）概念。“${}”符号用来表示“布局呈现器（layout renderer）”，即随当前日志插入一段上下文信息。我们可以在很多地方使用布局，例如控制日志信息写入到屏幕以及文件中的格式，甚至还可以控制日志输出文件的名称。这个特性功能非常强大，接下来我们就来看看：

假设我们需要为输出到控制台的每一条信息添加如下附加信息：

1. 当前的时间日期
2. 发送该消息的类名和方法名
3. 日志等级
4. 日志内容

实现起来非常简单：

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

 还可以让来自不同类的日志信息输出到不同的文件中：

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

 默认的layout属性值： ${longdate}|${level:uppercase=true}|${logger}|${message} ，关于布局的详细介绍请查看Layouts。

关于布局渲染器的详细介绍请查看Layout Renderers，此处介绍几个常用的：

• ${date:universalTime=Boolean:format=String:culture=Culture}：当前日期和时间。
• ${shortdate:universalTime=Boolean}：表示格式为 yyyy-MM-dd 的短日期。 
• ${longdate:universalTime=Boolean}：表示格式为 yyyy-MM-dd HH:mm:ss.ffff  的长日期格式。 universalTime 设置是否输出UTC时间代替本地时间，默认为 false 。 例如：2016-02-19 10:33:49.9398
• ${level}：表示日志等级。  uppercase  值设置大小写，默认为 false ，即首字母大写，其余字母小写。例如（依次为默认、大写）：Trace、TRACE
• ${logger}：表示日志记录器的名称，也就是方法 LogManager.GetLogger("Program")  的参数值。例如：Program
• ${message}：表示日志消息。例如：  logger.Trace("Sample trace message");  ，则结果为：Sample trace message
• ${machinename}：表示服务器名称，即计算机名称。
• ${newline}：表示换行。
• ${exception:innerFormat=String:maxInnerExceptionLevel=Integer:innerExceptionSeparator=String:separator=String:format=String}：表示异常信息。 format - 设置输出格式，必须是异常的属性：Message、Type、ShortType、ToString、Method、StackTrace、Data，默认值为Message； innerFormat - 设置内部异常的输出格式，可选值：Message, Type, ShortType, ToString, Method, StackTrace； maxInnerExceptionLevel - 设置包含在输出中的最大内部异常个数，默认为0； innerExceptionSeparator - 设置内部异常之间的分隔符，默认为换行； separator - 设置用于连接格式中的多个数据，默认为一个空格，例如： ${exception:format=message,tostring} ，则用一个空格分隔message和string。

包含文件

有时我们需要将NLog的配置文件分割成几个存放。NLog同样支持在某一配置文件中对其他的配置文件进行引用包含，然后在运行时一起处理。和NLog配置文件中其他部分一样，我们可以使用熟悉的${var}标记。这样就方便根据不同环境设置智能装载相应的配置文件，例如如下示例降加载基于计算机名的配置文件：

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

可选属性， ignoreErrors="true" ，默认为 false ，可以设置当包含的文件未找到或格式不正确时是否抛出异常。当设置为 true 时，使用 Troubleshooting logging节点记录错误。

变量（Variables）

变量被用于定义复杂的表达式，或者多次重复出现的表达式。例如：

<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>

变量需要在使用前声明，否则初始化配置时将失败。

但是，自从NLog 4.1以后，使用  ${var:var1} 代替 ${var1} ，例如：

<nlog>
  <variable name="user" value="admin" />
  <variable name="password" value="realgoodpassword" />      
  <targets>
    <target name="debug" type="Debug" layout="${message} and ${var:user}=${var:password}" />
  </targets>
  <rules>
    <logger name="*" minlevel="Debug" writeTo="debug" />
  </rules>
</nlog>

自动重新配置（Autonatic reconfiguration）

配置文件在程序启动的时候被自动读取。程序长时间的运行过程中，有时可能想要改变日志等级，而不停止应用程序。NLog可以监控配置文件，在配置文件发生改变后重新读取。需要如下设置：

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

 注意：包含的文件发生改变也会导致重新加载。

日志功能排错（Troubleshooting logging）

有时虽然已经配置好了NLog，可是有些时候应用程序仍旧会出现一些难以理解的问题，例如没有任何日志输出。其中最常见的原因就是ASP.NET的权限——ASP.NET的aspnet_wp.exe或w3wp.exe可能没有对NLog配置文件中指定目录的写入权限。NLog对于其自身运行中发生的异常有着很强的监测能力。如下设定可以将这些监测结果输出至指定位置，或是对这些异常进行相应的处理（默认设定将忽略自身异常）：

• <nlog throwExceptions="true" />- 当NLog自身掷出异常时，该选项可以将异常掷回日志的调用者。在开发过程中，这个设定将变得非常有用，能够迅速帮助我们定位异常的位置以及原因。而当程序开发结束并部署到应用环境时，应该尽快设定throwExceptions为false，免得NLog自身的异常导致整个应用程序的崩溃。
• <nlog internalLogFile="file.txt" />- 让NLog将自身运行过程中的日志信息（包括可能出现的异常）写入到文件中。
• <nlog internalLogLevel="Trace|Debug|Info|Warn|Error|Fatal" /> - 选择写入内部日志的记录等级。该等级设定的越高，相应的输出日志文件将越小。
• <nlog internalLogToConsole="false|true" /> - 将内部日志信息发送至控制台。
• <nlog internalLogToConsoleError="false|true" /> - 将内部日志信息发送至标准异常输出（stderr）。

异步处理和包装器（Asynchronous processing and wrapper targets）

NLog的包装器和复合输出目标特性让我们能够修改输出目标的默认行为，这种修改体现在如下几个方面：

• 异步处理（向目标输出将用单独的线程处理）
• 异常时自动重试
• 负载平衡
• 缓存 
• 过滤 
• 备用输出目标（主输出目标失败时启用备用输出目标）

只要在配置文件中将若干个target节点嵌套起来，即可完成对包装器或复合输出目标的定义。嵌套深度没有任何限制。例如为某个输出目标添加异步处理以及异常自动重试功能，只要按照如下代码配置NLog即可：

<targets> 
  <target name="n" xsi:type="AsyncWrapper"> 
    <target xsi:type="RetryingWrapper"> 
      <target xsi:type="File" fileName="${file}.txt"/> 
    </target> 
  </target> 
</targets> 

 异步处理特性极为常用，因此NLog提供了一种简写方式——即 <targets async="true" /> ，这样该输出目标将自动应用AsyncWrapper包装器。

扩展（Extendsions）

关于扩展的详细信息请查看Extending NLog。

参考文档

1. https://github.com/NLog/NLog/wiki/Configuration-file
2. http://www.cnblogs.com/dflying/archive/2006/12/06/584426.html
3. https://github.com/net-commons/common-logging