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 支持两种配置文件格式

  1. 配置在*.exe.config or 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 />根节点下面有如下的子元素。 头两个元素是配置文件必须的,其他的为可选配置:

  • <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>
posted @ 2014-10-31 14:41  争世不悔  阅读(4661)  评论(0编辑  收藏  举报