NLog之：文件类型目标（File target）

英文原文[http://nlog-project.org/wiki/File_target]

用途

将日志信息写到一个或多个文件中。

支持.NET Framework1.0; 1.1; 2.0; 3.5; 4.0 SilverLight4.0 .NET Compact Framework1.0; 2.0; 3.5; Mono.NET.

配置语法

<targets>
  <target xsi:type="File"
          name="String"
          layout="Layout"
          header="Layout"
          footer="Layout"
          encoding="Encoding"
          lineEnding="Enum"
          archiveAboveSize="Long"
          maxArchiveFiles="Integer"
          archiveFileName="Layout"
          archiveNumbering="Enum"
          archiveEvery="Enum"
          replaceFileContentsOnEachWrite="Boolean"
          fileAttributes="Enum"
          fileName="Layout"
          deleteOldFileOnStartup="Boolean"
          enableFileDelete="Boolean"
          createDirs="Boolean"
          concurrentWrites="Boolean"
          openFileCacheTimeout="Integer"
          openFileCacheSize="Integer"
          networkWrites="Boolean"
          concurrentWriteAttemptDelay="Integer"
          concurrentWriteAttempts="Integer"
          bufferSize="Integer"
          autoFlush="Boolean"
          keepFileOpen="Boolean" />
</targets>

更多配置文件使用方法。

参数

常规选项

 name – target节点名称

布局选项

 layout – 日志呈现的文本内容。默认为：

 ${longdate}|${level:uppercase=true}|${logger}|${message}

 header – 日志头显示的文本内容。

 footer – 日志尾显示的文本内容。

 encoding – 文件编码方式。

 lineEnding – 行结束模式。

可选值：

•   CR – 在每尾部插入回车符号（ASCII 13）。
•   CRLF – 在每行尾部插入回车和换行符号（ASCII 13 & ASCII 10）。
•   Default – 在每行尾部插入平台相关的行结束符号（默认）。
•   LF - 在每行尾部插入换行符号（ASCII 10）。
•   None – 不插入任何行结束符号。

文件存档选项

archiveAboveSize – 存档上限值。当日志文件大于此值是，将自动存档。其类型为Long。

注意：在多进程并发记录日志的情况下，启用该选项可能会大幅降低日志记录速度。在单进程时，为了达到最佳性能，可以考虑设置ConcurrentWrites为false。

maxArchiveFiles – 保存的最大存档文件数。其类型类Integer，默认为9个。

archiveFileName – 存档文件名称。允许使用Layout。

备注：此文件名称中可能包含特殊占位符{#####}，它将根据存档策略，由一个数字序列替代，其中占位符的个数决定了文件名称中的数字。

archiveNumbering – 存档文件的编号方式。

可选值：

Rolling – 滚动式编号，即最新的日志文件编号为0，然后是1，… ，N。

• Sequence – 序列式编号，即最大编号的日志文件为最新的日志文件。

archiveEvery – 是否在每个设定时间刻自动存档日志文件。

可选值：

• Day – 每日存档。
• Hour – 每小时存档。
• Minute – 每分钟存档。
• Month – 每月存档。
• None – 不按时间固定存档。
• Year – 每年存档。

备注：作为写日志的一部分，文件移动到存档位置的操作发生的时间变换时刻。例如，当前时间从10点变至11点，则当在写第11点或11点之后的第一个写操作时，触发日志文件归  档。

注意：在多进程并发记录日志的情况下，启用该选项可能会大幅降低日志记录速度。在单进程时，为了达到最佳性能，可以考虑设置ConcurrentWrites为false。

输出选项

replaceFileContentsOnEachWrite – 是否覆盖每次写入的日志内容，而不是在文件后面追加。其取值类型为Boolean，默认为false。

fileAttributes – 文件属性（只支持Windows）。

可选值：

Archive – 归档文件。

Compressed – 此文件是压缩文件。

DeleteOnClose – 文件关闭后删除。

Device – 设备文件（MSDN中为：保留供将来使用）。

Encrypted – 加密文件。

Hidden – 隐藏文件。

NoBuffering –文件打开时不使用系统缓存 。

Normal - 文件正常，没有设置其他的特性。

NotContentIndexed – 将不会通过操作系统的内容索引服务来索引此文件。

PosixSemantics – 按照POSIX规则存取的文件。

ReadOnly – 只读。

ReparsePoint – 重(新)分析点^[1]。

SparseFile – 稀疏文件。

System – 系统文件。

Temporary – 临时文件（尽可能的保存在缓存中，但是不会写入磁盘）。

WriteThrough – 系统通过任何中间缓存后再直接写入磁盘中。

    此参数在以下平台中不支持：

    NLog v1.0 for .NET Compact Framework 1.0

    NLog v1.0 for .NET Compact Framework 2.0

    NLog v2.0 for .NET Compact Framework 2.0

    NLog v2.0 for .NET Compact Framework 3.5

    NLog v2.0 for Silverlight 4.0

 filename – 写入日志的文件名称。支持Layout。

备注：文件名字符串中可能包含布局呈现器中的实例变量。这样可以通过配置单个目标节点，而将日志写入多个文件中。

以下fileName属性值将使得NLog在应用程序启动目录下，根据日志级别不同，将日志信息写到不同的文件中。

${basedir}/${level}.log

因此，所有的Debug级别日志写入到Debug.log文件中，所有的Info级别日志写入到Info.log文件中，其它以此类推。同时，也可以结合其它布局呈现器实例，组成所要的日志文件名称。

 deleteOldFileOnStartUp – 启动时，是否删除旧的日志文件。其取值类型为Boolean，默认为false。

备注：此选项，仅在“fileName”参数为单个文件时有效。

 enableFileDelete – 是否允许删除日志文件。其取值类型为Boolean，默认为true。

 createDirs – 是否允许自动创建（不存在的）目录。其取值类型为Boolean，默认为true。

备注：设置此属性为false或许会对性能有那么一丁点的改善，但是如果目录不存在，则会在试图写入日志时报错。

性能优化选项

 concurrentWirtes – 是否允许使用通过多个进程的方式，将日志信息并行写入文件中。其取值类型为Boolean，默认为true。

备注：这使得多进程记录日志成为可能。NLog使用一种特别的技术使用文件保持打开状态以备写入。

 openFileCacheTimeout – 文件保持打开状态的最大时间秒数。如果这个数字为负数，则在一定不活动时间后，文件不会自动关闭。其取值类型为Integer，默认值为-1。（即默 认状态下文件始终处于打开状态以备写入。）

openFileCacheSize – 保持打开状态的文件数量。当通过设置单个文件类型目标，且结果写入多个不同文件（如根据日志等级或日志对象名称）时，则可将此属性设置为一个较 高的值以改善性能。其取值类型为Integer，默认值为5。

备注：这些文件是在最近最少使用算法基础管理的，此算法在缓存空间不足时将最长时间内没有使用的文件Flush。一般来说，不应当把此参数设置过大，最好不要超过10-15，这是因同时保持多个文件处于打开状态，对系统资源来说是一个很大的消耗。

networkWrites – 是否通过多线程由不同的网络主机并行向文件中写入日志。其取值类型为Boolean，默认值为false。

备注：通过此此种方式，可以有效阻止文件长期保存为打开状态。

concurrentWriteAttemptDelay – 在再次尝试将日志写入文件之前延迟的毫秒数。其取值类型为Integer，默认值为1。

备注：实际的延迟时间，是一个介于0到指定参数值之间的随机整数，且在每次尝试失败之后，都会将此参数加倍。假使此参数值为10，则第一次重试写入的延迟时间（毫秒数）在 0-10之间的一个随机数，第二次重试时为0-20之间的一个随机数，第三次重试时为0-40之间的一个随机数，第四次重试时为0-80之间的一个随机数等等，以此类推。

concurrentWriteAttempts – 在NLog丢弃日志信息之前的追加（尝试重写）写次数。其取值类型为Integer，默认值为10。

bufferSize – 日志文件缓存区大小（单位：字节）。其取值类型为Integer，默认值为32768（32KB）。

autoFlush – 在每次日志信息后，是否自动刷新文件缓存区。其取值类型为Boolean，默认值为true。

keepFileOpen – 是否保持日志文件处于打开状态，以代替其在每次日志写事件发生时频繁打开和关闭。其取值类型为Boolean，默认值为false。

备注：设置此属性为true，有助于提高性能。

 

---

 

配置示例

简单日志记录

下面是一个非常简单的文件类型目标示例，它将生成单个日志文件，为此需要将以下代码放到NLog.config此类的配置文件中，程序日志将被写入到应用程序目录下的logs/logfile.txt文件中。

<?xml version="1.0" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/logs/logfile.txt"
            keepFileOpen="false"
            encoding="iso-8859-2" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

分级别日志记录文件

单个文件类型目标也可以将日志写入多个文件中，下面的配置将促使每个级别的日志信息写入单独的文件中，因此你将看到有以下文件：

Trace.log

Debug.log

Info.log

Warn.log

Error.log

Fatal.log

<?xml version="1.0" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/${level}.log" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

每天生成一个日志文件

下面的配置将每天产生一个日志文件，并且将按以下命名方式命名：

2010-06-05.log

2010-06-06.log

2010-06-07.log

2010-06-08.log

……

<?xml version="1.0" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/${shortdate}.log" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

异步日志记录

根据使用场景，可以为文件类型目标增加异步包装器属性，通过此种方法可以使用独立的线程记录日志信息，从而防止主线程被阻塞且更快的执行。推荐在多线程的服务器应用程序中使用异步日志记录功能，而在执行时间不长的命令行程序中则没有必要使用此方法。

<?xml version="1.0" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <targets>
        <!-- Log in a separate thread, possibly queueing up to
        5000 messages. When the queue overflows, discard any
        extra messages-->

        <target name="file" xsi:type="AsyncWrapper" queueLimit="5000" overflowAction="Discard">
            <target xsi:type="File" fileName="${basedir}/logs/${level}.txt" />
        </target>
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

创建以逗号隔开的日志文件（CSV格式）

为了创建CSV格式文件，可以使用以下配置，它利用了CsvLayout。以下示例将创建一个含有4列并被格式化为CSV格式的日志文件。

<?xml version="1.0" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <targets>
        <target name="csv" xsi:type="File" fileName="${basedir}/file.csv">
            <layout xsi:type="CSVLayout">
                <column name="time" layout="${longdate}" />
                <column name="message" layout="${message}" />
                <column name="logger" layout="${logger}"/>
                <column name="level" layout="${level}"/>
            </layout>
        </target>
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="csv" />
    </rules>
</nlog>

按大小将文件存档

日志文件达到一定大小之后，将移动到指定的其它位置以存档。下面的配置将创建logs/logfile.txt，并当此文件大小达到10KB时，将日志内容移动至archives/log.000000.txt, archives/log.000001.txt, archives/log.000002.txt等（并且默认只保留最后的9个存档文件）。

<?xml version="1.0" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/logs/logfile.txt"
            archiveFileName="${basedir}/archives/log.{#####}.txt"
            archiveAboveSize="10240"
            archiveNumbering="Sequence"
            concurrentWrites="true"
            keepFileOpen="false"
            encoding="iso-8859-2" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

按时间将文件存档

日志文件也可以基于时间设置自动存档。下面的配置将在每天的开始时刻里将日志文件存档，并且使用滚动文件命名方式。因此，前一天的日志可以在文件archives/log.0.txt文件中找到，再前一天的数据可以在archives/log.1.txt文件中找到，以此类推。此配置将保存最近的7个存档文件，因此，早于当前时间一周前的日志数据将被删除。

<?xml version="1.0" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <targets>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}"
            fileName="${basedir}/logs/logfile.txt"
            archiveFileName="${basedir}/archives/log.{#}.txt"
            archiveEvery="Day"
            archiveNumbering="Rolling"
            maxArchiveFiles="7"
            concurrentWrites="true"
            keepFileOpen="false"
            encoding="iso-8859-2" />
    </targets>

    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

[1] http://msdn.microsoft.com/zh-cn/library/aa365503(v=VS.85).aspx

Technorati 标签: NLog 日志管理