NLOG的使用

article/2025/10/11 17:23:42

Tartget Properties

header

archiveFileName

archiveNumbering

maxArchiveFiles

keepFileOpen

archiveOldFileOnStartup

rules

加载配置文件

rules 的使用

最近在学习GRBL-PLOTTER代码，其日志系统用的是NLOG，将一些内容进行总结；

Config | NLog (nlog-project.org)

NLog在使用时，可以使用配置文件进行配置，可以在程序中利用关键字进行配置；

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><variable name="basedir" value="${specialfolder:folder=CommonApplicationData}/GRBL-Plotter" />    <!-- default, optional --><targets><target name="file" xsi:type="File"layout="${longdate} | ${pad:padding=-5:inner=${level}} | ${pad:padding=-30:inner=${logger}} | ${message}${exception:format=ToString}" header="----- Possible levels: Trace, Debug, Info, Warn, Error, Fatal ----|&#xD;&#xA;"fileName="${var:basedir}/logfile.txt"archiveFileName="${var:basedir}/log_{#}.txt"keepFileOpen="true"maxArchiveFiles="20"encoding="utf-8" archiveNumbering="DateAndSequence"archiveOldFileOnStartup="true"/><target name="file2" xsi:type="File"layout="${message}${exception:format=ToString}" fileName="${var:basedir}/logpos.nc"keepFileOpen="false"encoding="utf-8" archiveNumbering="Rolling"archiveOldFileOnStartup="true"maxArchiveFiles="3"/></targets><rules><logger name="*" minlevel="Info" writeTo="file" /><logger name="LogPos" minlevel="Trace" writeTo="file2" /></rules>
</nlog>

在编写配置文件时，主要配置Targets，Layout和Layout renderers三项

The following types can be configured:

Targets - the destinations of a logevent, e.g. file, database, console
Layout - the layout e.g. json, csv, plain-text (default)
Layout renderers - the template markers, e.g. ${message}, ${exception}, ${date}

Targets是日志的目标系统，可以数据库、控制台，也可以是文件

Layout是日志内容的格式，利用Layout renderers来进行格式化

layout="${longdate} | ${pad:padding=-5:inner=${level}} | ${pad:padding=-30:inner=${logger}} | ${message}${exception:format=ToString}"

如上述格式配置，形成的日志信息如下所示

2022-08-16 14:08:00.4998 | Info  | GrblPlotter.MainForm           | GetAppDataPath from Default: C:\Users\Thinkpad\Desktop\GRBL-Plotter-master\GRBL-Plotter-master\GRBL-Plotter\bin\x86\Debug

关于renderers的格式说明，参考renderers说明

Tartget Properties

参考：NLog属性

header是日志文件的标题

archiveFileName

归档的文件名，该文件名包括路径；如下所示，在进行归档时，将日志文件改名为log_{#}.txt进行保存；该属性与archiveOldFileOnStartup选项一起使用；表明在软件打开时，将上一次的日志文件进行归档，新的文件清空，重新记录

archiveFileName="${var:basedir}/log_{#}.txt"

其它选项暂时没有找到说明

archiveNumbering

日志文件归档时文件名格式，有以下四个选项；示例中使用到的DateAndSepuence，是用日期和序事情

Member name    Value	Description
Sequence        0	    Sequence style numbering. The most recent archive has the highest number.
Rolling	        1	    Rolling style numbering (the most recent is always #0 then #1, ..., #N.
Date	        2	    Date style numbering. Archives will be stamped with the prior period (Year, Month, Day, Hour, Minute) datetime.
DateAndSequence	3	    Date and sequence style numbering. Archives will be stamped with the prior period (Year, Month, Day) datetime. The most recent archive has the highest number (in combination with the date).

使用该DateAndSequence选项时，日志文件的存档内容如下图所示

maxArchiveFiles

读取和设置最大存档的文件数

keepFileOpen

设置在每次录前后是否关闭和打开日志文件，还是一直保持日志文件处于打开状态

archiveOldFileOnStartup

为TRUE时，表示是在启动时，归档旧的日志文件

rules

<rules><logger name="*" minlevel="Warn" writeTo="target1,target2,target3" />
</rules>

上述 rules 生成的规则是满足所有 LOGGER 设备的，在信息的消息等级在 warn 以上时，就把日志信息写入 target1\target2 和 target3 设备中。

<rules><logger name="*" minlevel="Warn" writeTo="target1" /><logger name="*" levels="Debug,Warn,Info" writeTo="target2" />
</rules>

也可以指定具肯体的日志级别到指定的记录设备上。上述 rules 中，第二条定义将 debug\warn\info 三个级别的信息写到 target2 设备中。

可以为 rules 设定 filter，如下

<rules><logger name="*" minlevel="Info" writeTo="target1"><filters defaultAction='Log'><when condition="contains('${message}','Common')" action="Ignore" /></filters></logger>
</rules>

且日志规则可以嵌套，如下所示

<rules><logger name="*" minlevel="Info" writeTo="target1"><logger name="*" minlevel="Warn" writeTo="target2" /></logger>
</rules>

上述规则的意义是，如果某个日志信息的 warn, 就会将这条信息写到 target1 和 target2 中；如果某个信息的级别 info 的话，就只写到 target1 中

加载配置文件

LogManager.Configuration = new XmlLoggingConfiguration("NLog.config");

rules 的使用

在使用 NLog 时，需要首先获得一个日志实例，如下

var commonLogger = LogManager.GetLogger("Common");

这时，NLog 会根据名名（Common）从缓存取得或者重新创造一个新的 logger；在创建时，遍历 rules 中的所有 logger 信息，找到对应的名称的 logger，再按照定义好的规则进行创建。

<rules><logger name="*" minlevel="Info" writeTo="target1"><filters defaultAction='Log'><when condition="contains('${message}','Common')" action="Ignore" /></filters></logger>
</rules>

上述 rules 定义的 logger 带有过滤条件；

在使用时，NLog 会计算 condition 的结果，如果结果为 TRUE，则执行 action 后的操作；为 FALSE 的话，返回 Neutral，即不执行任何操作，进行以后条件的判断；如果没有后续条件了，就执行 defaultAction 操作；

条件语句返回的结构是 FilterResult 类型，如下；具体返回值，NLog 采取的操作如下代码段的注释所示。

    public enum FilterResult{/// <summary>/// The filter doesn't want to decide whether to log or discard the message./// </summary>Neutral, /// <summary>/// The message should be logged./// </summary>Log, /// <summary>/// The message should not be logged./// </summary>Ignore, /// <summary>/// The message should be logged and processing should be finished./// </summary>LogFinal, /// <summary>/// The message should not be logged and processing should be finished./// </summary>IgnoreFinal, }