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  争世不悔  阅读(4606)  评论(0)  编辑  收藏  举报