NLog学习笔记二：深入学习

配置文件

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

配置文件位置

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

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

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

Web应用程序的标准配置文件——web.config
web.config所在目录中的web.nlog文件
应用程序所在目录中的NLog.config文件
NLog.dll所在目录中的NLog.dll.nlog文件
环境变量NLOG_GLOBAL_CONFIG_FILE所指向的文件

.NET Compact Framework并不支持应用程序配置文件（*.exe.config）以及环境变量，因此NLog将自动按照顺序搜索下列路径：

应用程序所在目录中的applicationname.exe.nlog文件
应用程序所在目录中的NLog.config文件
NLog.dll所在目录中的NLog.dll.nlog文件

配置文件形式

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

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

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

<configuration>

  <configSections>

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

  </configSections>

  <nlog>

  </nlog>

</configuration>

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

<targets /> ：定义日志的输出目标
<rules /> ：定义对日志信息进行路由的规则
<extensions /> ：定义从其他dll文件中加载的NLog扩展模块
<include /> ：引入外部的配置文件
<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 />元素有两个必须设置的属性：

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

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

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

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

规则（Rules）

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

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

name - 日志源（Logger的名称），可以使用*通配符
minlevel - 匹配该规则需要的最低记录等级
maxlevel - 匹配该规则需要的最高记录等级
level - 匹配该规则需要的单一的记录等级
levels - 匹配该规则需要的记录等级列表，记录等级之间用逗号隔开
writeTo - 匹配该规则的日志信息将被发送至的输出目标列表，输出目标之间用逗号隔开
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）”，即随当前日志插入一段上下文信息。我们可以在很多地方使用布局，例如控制日志信息写入到屏幕以及文件中的格式，甚至还可以控制日志输出文件的名称。这个特性功能非常强大，接下来我们就来看看：

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

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

实现起来非常简单：

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

参考文档