NLog配置
配置文件路径
NLog会在以下位置查找配置文件,在启动读取:
对于独立的exe可执行应用程序,会在下面的位置查找配置文件:
- 应用程序配置文件 (一般命名为 applicationname.exe.config)
- 应用程序目录下面的applicationname.exe.nlog文件
- 应用程序目录下面的NLog.config文件
- NLog.dll所在目录下面的NLog.dll.nlog文件 (在NLog没有安装在GAC时有效)
- 环境变量中的"NLOG_GLOBAL_CONFIG_FILE"配置 (NLog 1.0有效,NLog 2.0中被移除)
如果是ASP.NET应用程序,会在下面的位置查找配置文件:
- web.config文件
- web.config所在目录下面的web.nlog文件
- 站点下面的NLog.config文件
- NLog.dll所在目录下面的NLog.dll.nlog文件 (在NLog没有安装在GAC时有效)
- 环境变量中的"NLOG_GLOBAL_CONFIG_FILE"配置 (NLog 1.0有效,NLog 2.0中被移除)
.NET Compact Framework没有应用配置文件 (*.exe.config) 或者环境变量, 所以NLog仅仅会在以下地方查找配置文件
- 应用目录下面的applicationname.exe.nlog文件
- 应用下面的NLog.config文件
- NLog.dll所在目录下面的NLog.dll.nlog文件 (在NLog没有安装在GAC时有效)
配置文件格式
NLog 支持两种配置文件格式
- 配置在*.exe.config or web.config文件中
- 配置在特定的文件中
对于第一种情况, 我们使用了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 />根节点下面有如下的子元素。 头两个元素是配置文件必须的,其他的为可选配置:
- <targets /> – 定义日志 targets/outputs
- <rules /> – 定义日志路由规则
- <extensions /> – 从*.dll文件中加载日志扩展
- <include /> – 引入其他的外部配置
- <variable /> – 设置配置变量的值
Targets
<targets /> 节点定义了配置的 Targets. 每一个target都被定义为了一个元素节点。下面是target必须包含的特性:
- name – target 的名称
- type – target 类型– 比如 "File", "Database", "Mail"。如果加载了命名空间,配置名称为 xsi:type.
除了这两个特性, targets 还有其他的参数, 用于配置日志的输出。
比如 – File target 接收fileName 参数,用于定义输出的日志文件名称。Console target 有一个error参数,用于将跟踪记录信息输出到错误信息栏,而不是原来的输出信息栏。
一个<targets /> 可以包括多个targer,比如下面的例子,两个文件targer, 一个network target 和一个 OutputDebugString target:
<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提供了许多预定义的 Targets。当然,也能够容易的创建自定义的Targets。
Rules
Log 路由规则定义在 <rules /> 节点。这是一个很简单的路由表,我们定义了日志的等级(logger对象)和输出方式(targets)的关联。规则会从列表的第一条开始匹配。当一个规则匹配,日志信息会通过该规则关联的targer输出。如果该规则定义了final标记,那么,就不会继续匹配下面的规则。
每一条路由都是一个<logger /> 元素, 具有下面的特性
- name – source/logger 的名称 (可能包含通配符 * )
- minlevel – 该路由可以匹配的最小日志等级
- maxlevel – 该路由可以匹配的最大日志等级
- level – 该路由匹配的日志等级
- levels - 该路由可以匹配的多个日志等级
- writeTo – 使用哪个target来输出日志
- final – 匹配了本条路由以后,不再匹配后面的路由
rules 示例
所有Name.Space.Class1类输出的Debug等级以上的日志,都通过"f1"target输出
<logger name="Name.Space.Class1" minlevel="Debug" writeTo="f1" />
所有Name.Space.Class1类输出的Debug或者Error等级的日志,都通过"f1"target输出
<logger name="Name.Space.Class1" levels="Debug,Error" writeTo="f1" />
命名空间Name.Space下的所有类输出的日志,都通过"f3","f4"target输出
<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" />
在简单的应用场景下,可以只有一个targer和一个rule。但是,随着应用的发展,你会发现多个targer和多个rule能够更加的灵活,适应更多的应用场景
Layouts 和 layout renderers
NLog一个强大的地方,就是可以使用 layouts。一个简单的form布局,就是由${和}标记组成的文本。这个标记叫做Layout Renderers, 用于在生成的日志文件中插入信息
布局能够在许多地方使用,比如,它能够控制输出到文本或者控制台的信息格式,输出文件的文件名样式。他非常的强大,我们接下去就会看到。
现在,我们假设,我们想输出的控制台信息具有如下的格式:
- 正确的日期时间
- 调用日志输出的类名和方法名称
- 日志等级
- 日志信息
这非常简单:
<target name="c" xsi:type="Console" layout="${longdate} ${callsite} ${level} ${message}"/>
我们能把每个Logger输出的日志,都输出到不同的日志文件:
<target name="f" xsi:type="File" fileName="${logger}.txt"/>
你会返现, fileName特性使用了${logger} 布局渲染,这使得输出的日志文件的文件名称都包含该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
Include files
有时,我们希望能够把配置文件分成很多小块。 NLog 提供了一套包含其他外部文件的机制。为了引入外部文件,你仅仅需要写一个标签。 他只需要一个file特性,和许多NLog配置的特性一样,通过layout renderers,比如${},可以获取动态的值,实现了根据环境的不同,调用不同的配置
The following configuration example demonstrates this, by loading a file whose name is derived from the name of the machine we’re running on.
<nlog>
...
<include file="${basedir}/${machinename}.config"/>
...
</nlog>
还有可选配置, ignoreErrors="true",默认是false,能够拦截因为文件不存在或者文件格式不正确而产生的错误。如果设置了ignoreErrors="true",使用Troubleshooting logging 节点来记录日志错误
Variables
变量能够用于记录常常变化或者复杂的值 (比如文件名称),定义参数使用如下语法:
<variable name="var" value="xxx" />
如果我们定义好了变量,就能在layout renderers中使用 – 通过 ${var} 语法,就像下面的例子:
<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>
Automatic reconfiguration
配置文件会在程序启动的时候自动读取。在程序运行期间,我们有时希望能够更改配置,不需要重启应用及可以生效。NLog能够监控配置文件,在其更改的时候,自动重新读取配置。要使用这套机制,只需要在配置文件中增加autoReload="true"特性
<nlog autoReload="true">
...
</nlog>
注意,重新加载的配置机制也会监控外部配置(include节点中的外部配置文件),所以,如果我们变更了外部文件中的配置,也会重新加载NLog配置
要明确,自动加载配置,并不需要回收IIS的应用程序池
Troubleshooting logging
有时候,我们明明配置好了,却没有写入日志。这可能有很多的原因。最常见的是权限不足,通常,ASP.NET 进程, 及aspnet_wp.exe 或者 w3wp.exe 进程没有向指定路径写入日志的权限
NLog在运行时不会抛出异常。下面的设置能够更改这个默认行为:
- <nlog throwExceptions="true" /> - 在配置文件中添加throwExceptions特性,是的NLog会将异常抛出。这个特性常用于开发环境快速定位错误,但在开发环境中,建议设置为false。
- <nlog internalLogFile="file.txt" /> - 在配置文件中添加internalLogFile特性,是的NLog会在特定的文件中记录自身的错误。
- <nlog internalLogLevel="Trace|Debug|Info|Warn|Error|Fatal" /> – 确定需要记录的内部日志等级。等级越高,记录的越详细
- <nlog internalLogToConsole="false|true" /> – 内部错误信息是否输出到控制台
- <nlog internalLogToConsoleError="false|true" /> – 内部错误信息是否输出到错误信息框
Asynchronous processing and wrapper targets
NLog提供了wrapper和复合targets用于控制其他target的行为:
- asynchronous processing (wrapped target runs in a separate thread)
- retry-on-error
- load balancing
- buffering
- filtering
- failover (failover)
在配置文件中定义wrapper,就是target标签的简单嵌套。你甚至可以wraper再嵌套wraper - 嵌套层数没有限制。比如,retry-on-error wrapper嵌套在asynchronous wrapper中,配置文件如下:
<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" ,所有其下的元素,都会具有异步特性
<nlog>
<targets async="true">
<!-- all targets in this section will automatically be asynchronous -->
</targets>
</nlog>
Default wrappers
有时,我们需要定义多有的target都有同样的wrapper,比如,为所有的target添加 buffering and/or retrying包装器。 NLog 提供了 <default-wrapper /> 语法来实现这一功能。你只需要在targets元素中配置<default-wrapper />元素,那么该targets下面的target都会具有配置的warpper。
<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>
Default target parameters
同默认的wrapper一样,NLog提供了<default-target-parameters />来实现统一配置一个targets元素下面的target元素参数。比如,如果你不想文件一直保持打开状态,你可以设置keepFileOpen="false",代码如下:
<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>
你可以使用<default-target-parameters />简化上面的写法
<source lang="xml">
<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>