[转]NLog学习笔记二：深入学习

本文转自：http://www.cnblogs.com/CCHUncle/p/5207735.html

配置文件

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机制。这样配置文件将类似如下所示：

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();
}
}
}

View Code

目标（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。

参考文档

https://github.com/NLog/NLog/wiki/Configuration-file

http://www.cnblogs.com/dflying/archive/2006/12/06/584426.html