[开发工具].NET平台下的日志记录工具类库NLog_通过配置文件的方式

一、NLog介绍

1.1、简介

? ?NLog是一个在.NET平台下的免费且具有丰富路由和管理功能的日志记录工具类库；适用于.NET平台下的所有编程语言，能够让开发人员通过配置文件自由的搭配日志样式内容，且调用方式很简单；让开发人员能够十分便捷高效的生成记录应用程序的日志；

? ? NLog还遵从BSD license【即允许商业应用且完全开放源代码；任何人都可以免费使用并对其进行测试】

1.2、效果演示

我这里的效果演示的是通过配置文件生成对应的日志级别文件、可以动态修改日志配置系统自动监测执行效果：

1.3、通过代码方式配置NLog

?如果想要通过代码方式配置NLog内容则可以参考如下链接：

Configure from code · NLog/NLog Wiki · GitHubhttps://github.com/NLog/NLog/wiki/Configure-from-code

二、NLog在项目中的配置使用

2.1、安装NLog包

?2.2、创建NLog的配置文件NLog.config

2.2.1、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">

    <targets>
        <target name="logfile" xsi:type="File" fileName="file.txt" />
        <target name="logconsole" xsi:type="Console" />
    </targets>

    <rules>
        <logger name="*" minlevel="Info" writeTo="logconsole" />
        <logger name="*" minlevel="Debug" writeTo="logfile" />
    </rules>
</nlog>

2.2.2、我自己使用的NLog.config配置文件

首先需要在项目的根目录下创建NLog.config文件，文件内容如下：

<?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"
      autoReload="true"
	  internalLogLevel="Trace"
	  internalLogFile="C:\NLog\CoffeeProject\log.txt">

	<!--定义变量指定日志保存到的指定路径-->
	<variable name="UnitTestFolder" value="C:/NLog/Coffee/Project/UnitTestLog/" />
	<targets>
		<!--此部分中的所有目标将自动异步同步到【相对的应用程序根目录下】-->
		<target name="asyncFile" xsi:type="AsyncWrapper">
			<!--项目日志保存文件路径说明fileName="${basedir}/保存目录，以年月日的格式创建/${shortdate}/${记录器名称}-${单级记录}-${shortdate}.txt"-->
			<target xsi:type="File"
					fileName="${basedir}/ProjectLogs/MainLog/${shortdate}/${date:yyyy-MM-dd HH}-${level}.txt"
					layout="${date:yyyy-MM-dd HH\:mm\:ss} | ${message} ${onexception:${exception:format=message} ${newline} ${stacktrace} ${newline}"
					archiveFileName="${basedir}/archives/${logger}-${level}-${shortdate}-{#####}.txt"
					archiveAboveSize="102400"
					archiveEvery="Hour" 
					archiveNumbering="Sequence"
					concurrentWrites="true"
					keepFileOpen="false" />
		</target>

		<!--此部分中的所有目标将自动异步同步到【指定的绝对路径下】-->
		<target name="asyncFile2" xsi:type="AsyncWrapper">
			<target xsi:type="File"
				fileName="${UnitTestFolder}/${shortdate}/${date:yyyy-MM-dd HH}-${level}.txt"
				layout="${date:yyyy-MM-dd HH\:mm\:ss} | ${message} ${onexception:${exception:format=message} ${newline} ${stacktrace} ${newline}"
				archiveFileName="${UnitTestFolder}/archives/${logger}-${level}-${shortdate}-{#####}.txt"
				archiveAboveSize="102400"
				archiveEvery="Hour"
				archiveNumbering="Sequence"
				concurrentWrites="true"
				keepFileOpen="false" />
		</target>
		<!--使用可自定义的着色将日志消息写入控制台-->
		<target name="colorConsole" xsi:type="ColoredConsole" layout="[${date:format=HH\:mm\:ss}]:${message} ${exception:format=message}" />
	</targets>

	<!--规则配置,final - 最终规则匹配后不处理任何规则-->
	<rules>
		<!--所有命名空间下的所有类的【在Trace和Fatal间(即：Trace\Debug\Info\Warn\Error\Fatal)】日志信息被写入【colorConsole】控制台上-->
		<logger name="*" minlevel="Trace" writeTo="colorConsole" enable="true" />
		<!--所有命名空间下的所有类的【在Trace和Fatal间(即：Trace\Debug\Info\Warn\Error\Fatal)】日志信息被写入【asyncFile】格式文件中-->
		<!--<logger name="*" minlevel="Trace" writeTo="asyncFile"/>-->
		<!--所有命名空间下所有类中级别【在Trace和Info之间（即：Trace\Debug\Info】日志信息被写入【asyncFile】格式文件中【相对的应用程序根目录下】）-->
		<logger name="*" minlevel="Trace" maxlevel="Info" writeTo="asyncFile" enabled="false"/>
		<!--在Test_NLog.Test命名空间下所有类中级别【在Trace和Info之间（即：Warn\Error\Fatal】日志信息被写入【asyncFile2】格式文件中【指定的绝对路径下】）-->
		<logger name="Test_NLog.Test.*" minlevel="Warn" maxlevel="Error" writeTo="asyncFile2" final="true"/>

	</rules>
</nlog>

? ? ? 注意：该NLog.config配置文件创建完成后，需要选中该配置文件的属性，修改复制到输出目录为【始终复制】?，如下图所示：

2.3、 写入日志示例

2.3.1、官方示例

public static class Program
{
    //获取NLog.config配置文件内容并实例化日志对象Logger
    private static readonly NLog.Logger Logger = NLog.LogManager.GetCurrentClassLogger();

    public static void Main()
    {
        try
        {
           //写入Info级别的日志
           Logger.Info("Hello world");
           System.Console.ReadKey();
        }
        catch (Exception ex)
        {
           Logger.Error(ex, "Goodbye cruel world");
        }
    }
}  

?2.3.2、我自己使用的NLogHelper帮助类

? ?该帮助类可以避免在每个需要使用日志的类下实例化一次日志【?private static readonly NLog.Logger Logger = NLog.LogManager.GetCurrentClassLogger();】后才能调用；

? ? 注意：如果使用了该帮助类，则在NLog的配置文件Rules里面的命名空间过滤那里只能使用*,而不能够使用指定的命名空间或（命名空间.类名称）进行精准过滤日志内容了。

/***
*	Title："NLog" 项目
*		主题：NLog日志帮助类（线程安全的单例模式）
*	Description：
*		功能：
*	Date：2022
*	Version：0.1版本
*	Author：Coffee
*	Modify Recoder：
*/

using NLog;
using NLog.Config;
using NLog.Targets;
using System;
using System.Collections.Generic;

namespace NLogHelper
{
    public class LogHelper
    {
        #region   基础参数
        //获取配置文件并实例化
        private static Logger _logger;

        #endregion

        #region   单例模式
        private LogHelper()
        {
            _logger = LogManager.GetCurrentClassLogger();
        }

        private static class SingleHolder
        {
            internal static readonly LogHelper _Instance = new LogHelper();
        }

        public static LogHelper Instance
        {
            get { return SingleHolder._Instance; }
        }

        #endregion


        #region   信息的级别

        #region Trace——①追踪（最常见的记录信息【一般用于开发环境】的普通输出）
        public void Trace(string msg)
        {
            _logger.Trace(msg);
        }

        public void Trace(string msg, Exception err)
        {
            _logger.Trace(err, msg);
        }
        #endregion

        #region Debug——②调试（记录信息，出现频率比Trace少一些【一般用于开发环境】的调试程序）
        public void Debug(string msg)
        {
            _logger.Debug(msg);
        }

        public void Debug(string msg, Exception err)
        {
            _logger.Debug(err, msg);
        }
        #endregion

        #region Info——③信息（【用于生产环境】的消息记录）
        public void Info(string msg)
        {
            _logger.Info(msg);
        }

        public void Info(string msg, Exception err)
        {
            _logger.Info(err, msg);
        }
        #endregion

        #region Warn——④警告（【用于生产环境】的比较重要场合）
        public void Warn(string msg)
        {
            _logger.Warn(msg);
        }

        public void Warn(string msg, Exception err)
        {
            _logger.Warn(err, msg);
        }
        #endregion

        #region Error——⑤错误（【用于生产环境】的错误信息记录）
        public void Error(string msg)
        {
            _logger.Error(msg);
        }

        public void Error(string msg, Exception err)
        {
            _logger.Error(err, msg);
        }
        #endregion

        #region Fatal——⑥致命错误信息（【用于生产环境】的系统发生异常后无法执行记录）
        public void Fatal(string msg)
        {
            _logger.Fatal(msg);
        }

        public void Fatal(string msg, Exception err)
        {
            _logger.Fatal(err, msg);
        }
        #endregion

        #endregion

        /// <summary>
        /// 刷新数据到日志文件中
        /// </summary>
        /// <param name="millisecondsTimeout"></param>
        public void Flush(int? millisecondsTimeout = null)
        {
            if (millisecondsTimeout != null)
            {
                LogManager.Flush(millisecondsTimeout.Value);
            }

            LogManager.Flush();
        }

    }//Class_end
}

2.3.3、NLogHelper类的使用

?①引入命名空间【using NLogHelper;】

?②使用方法如下：

LogHelper.Instance.Trace("Trace log message");
LogHelper.Instance.Debug("Debug log message");
LogHelper.Instance.Info("Info log message");
LogHelper.Instance.Warn("Warn log message");
LogHelper.Instance.Error("Error log message");
LogHelper.Instance.Fatal("Fatal log message");

③日志效果如下：

?

?

?NLog日志的安装配置手册向导链接：

Tutorial · NLog/NLog Wiki · GitHubhttps://github.com/nlog/nlog/wiki/Tutorial

三、NLog的配置说明

如下是NLog项目的源码工程链接：

GitHub - NLog/NLog: NLog - Advanced and Structured Logging for Various .NET Platformshttps://github.com/NLog/NLog

3.1、NLog的配置文件NLog.config

? ? 当.NET应用程序启动时，NLog程序会在项目根目录下检索配置信息，并加载首先发现的配置，同时停止搜索；如果找不到对应的配置文件信息则NLog启动失败；

为了NLog配置文件的通用性，可以直接使用【NLog.config】的配置文件，如下所示：

3.2、NLog配置文件说明

这是NLog的官方配置文件内容介绍地址https://github.com/NLog/NLog/wiki/Configuration-file#rules

3.3、剖析NLog的配置文件

? ? NLog配置文件时一个以【nlog为根节点】的xml文件,其中【targets(目标集)】、【rules(规则集)】是必须要填写的内容，适用于高级使用场景。

<?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">

    <targets>
        <target name="logfile" xsi:type="File" fileName="file.txt" />
        <target name="logconsole" xsi:type="Console" />
    </targets>

    <rules>
        <logger name="*" minlevel="Info" writeTo="logconsole" />
        <logger name="*" minlevel="Debug" writeTo="logfile" />
    </rules>
</nlog>

3.3.1、nlog根节点属性

?nlog根节点属性说明：

internalLogLevel="Trace"

internalLogFile="
C:\NLog\CoffeeProject\log.txt">

<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      autoReload="true"
	  internalLogLevel="Trace"
	  internalLogFile="C:\NLog\Coffee\Project\log.txt">
</nlog>

?3.3.2、targets目标集?

NLog官方target内容配置说明链接https://github.com/NLog/NLog/wiki/File-target? ? targets节点中定义了多个日志输出的目标，每个日志输出目标是一个target元素；【通常情况下，每个target元素，必须指定name和type属性】

?target的所有属性语法内容和说明如下：

<targets>
  <target xsi:type="File"
          name="String"        //【必填】目标名称（便于规则路由选择）
          layout="Layout"      //【必填】布局选项(即：可以定义每条日志消息显示的风格样式)
          header="Layout"      //日志内容的标题
          footer="Layout"      //日志内容的页脚
          encoding="Encoding"  //日志编码（默认是Utf-8）
          lineEnding="Enum"    //每行日志的结束模式（默认值每行之后插入平台依赖性终端序列）    
          archiveAboveSize="Long"    //日志文件的大小（单位是：byte字节）
          maxArchiveFiles="Integer"  //应保留的最大日志存档数量（如果值小于等于0则不删除任何旧日志文件》）
          maxArchiveDays="Integer"   //日志文件保存的最大天数（如果值小于等于0则不删除任何旧日志文件》）
          archiveFileName="Layout"   //日志文件的存档名称（它可能包含一个特殊的占位符{###}，它将根据归档策略代替一系列数字。使用的哈希字符数确定用于编号文件的数值数字数量）
          archiveNumbering="Enum"    //日志文件的存档编号
          archiveDateFormat="String" //日志文件的存档日期格式（默认是:年月日）
          archiveEvery="Enum"        //是否每次指定时间通过时自动创建对应时间名称的日志文件          
          archiveOldFileOnStartup="Boolean"     //启用时使用旧日志文件（默认是false）
          archiveOldFileOnStartupAboveSize="Long"     //文件大小阈值到启动时归档旧日志文件(默认值为0);这意味着在启用ArchiveOldFileOnStartup后立即将文件存档
          replaceFileContentsOnEachWrite="Boolean"    //是否要替换每个写入上的文件内容，而不是在末尾附加日志消息(默认是false，即不替换)
          fileAttributes="Enum"   //文件属性（如：读写、只读、隐藏等）
          fileName="Layout"       //【必填】文件名称（即：日志消息保存的路径和文件名称，可以自定义）
          deleteOldFileOnStartup="Boolean"    //是否在启动程序时删除旧日志文件（默认false）
          enableFileDelete="Boolean"
          createDirs="Boolean"    //是否创建目录（默认是true:即不存在就会创建）
          concurrentWrites="Boolean"    //使用keepfileopen = true时，可以支持优化的并发写入同一机器主机上的多个进程的同一日志文件
          openFileFlushTimeout="Integer"    //文件缓冲区的显式刷新的秒数；有助于确保当autoflush = false时最终刷新文件缓冲区（默认值：0）
          openFileCacheTimeout="Integer"    //文件打开的最大秒数;如果此数字为负，则在不活动的时间后不会自动关闭文件;整数默认值：-1
          openFileCacheSize="Integer"       //保持打开的日志文件缓存数量（默认值：5）；您不应将此参数设置为非常高的值。不应超过10-15之类的数字，因为您将保持大量的文件打开，以消耗系统资源。
          networkWrites="Boolean"           //网络写入日志；并发是否通过不同网络主机上的多个进程写入日志文件。（默认值：false）
          concurrentWriteAttemptDelay="Integer"    //并发写入日志文件信息的延迟毫秒等待，然后才尝试再次写入文件。（默认值：1）
          concurrentWriteAttempts="Integer"        //在nlog丢弃日志消息之前，并发在日志文件上尝试写入的次数（默认值：10）
          bufferSize="Integer"      //日志文件缓冲区大小（默认是：32768字节）
          autoFlush="Boolean"       //每个日志消息后是否自动刷新文件缓冲区（默认是true）;禁用此功能将提高性能
          keepFileOpen="Boolean"    //是否要保持日志文件打开，而不是在每个记录事件中打开和关闭;将此属性打开则将极大提高性能，但也将使文件句柄锁定（默认是false）;考虑在启用此功能时设置OpenFileCachetime Out = 30，因为它将允许存档操作并进行反应以删除日志文件。
          forceManaged="Boolean"    //
          enableArchiveFileCompression="Boolean"    //启用将日志文件进行压缩（默认是false）
          cleanupFileName="Boolean"                 //在写入文件之前，将检查文件的名称是否为非法字符(默认值为：true);如果将其设置为false则可以提高性能，但是需要文件名错误就会被清除了。
          writeFooterOnArchivingOnly="Boolean"      //只有在文件存档时才应写下页脚（默认false）
          writeBom="Boolean" />   //是否要在创建的文件中编写BOM（字节顺序标记）默认是false
</targets>

《1》同步单日志文件的NLog.config配置内容

指定日志文件的相对路径语法为:【${basedir}等价于（AppDomain.BaseDirectory）】；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>
        <target name="file" xsi:type="File"
            layout="${longdate} ${logger} ${message}${exception:format=ToString}" 
            fileName="${basedir}/logs/logfile.txt" 
            keepFileOpen="true"
            encoding="utf-8" />
    </targets>
 
    <rules>
        <logger name="*" minlevel="Debug" writeTo="file" />
    </rules>
</nlog>

《2》日志文件目录也可以使用定义变量指定的绝对路径

<variable name="LogFixedFolder" value="C:/NLog/Coffee/Project/" />
<targets>
<target type="file" name="logfile" filename="${LogFixedFolder}test.log" />
</targets>

《3》批量异步写入日志内容

NLog官方的异步包装器说明【AsyncWrapper target】https://github.com/NLog/NLog/wiki/AsyncWrapper-target? ? 将多个日志消息写入一个日志文件时；使用批次写入将提高性能，特别是在使用keepfileopen = false时；使用AsyncWrapper时，会自动启用批处理异步写入【注意：使用AsyncWrapper时，需要在关闭程序时调用（?LogManager.Flush()方法将缓存消息写入日志文件中）】。

批量异步写入日志内容的配置基础语法如下：

<targets>
  <target xsi:type="AsyncWrapper"
          name="String"    //目标的名称
          queueLimit="Integer"    //限制懒汉式写入线程请求队列中的请求数（默认值是：10000）
          timeToSleepBetweenBatches="Integer"    //两个批量处理间的休眠毫秒数（默认值是：1）
          batchSize="Integer"    //懒汉式线程在批处理中处理的日志事件的大小（默认是：100）
          overflowAction="Enum">    //内存已被填满，这意味着后台线程写入日志的处理是滞后的，无法跟上应用程序的记录（默认值是丢弃【Discard】）
    <target xsi:type="wrappedTargetType" ...target properties... />
  </target>
</targets>

?注意：如果使用批量异步包装器但规则使用的是指定了包含在【AsyncWrapper】异步包装器的目标名称，则此时将不会使用异步写入日志文件；如下图配置所示：

   <targets>
      <target name="target2" xsi:type="AsyncWrapper">
        <target name ="target1" xsi:type="File"
                    fileName="c:/temp/test.log" layout="${message}"
                    keepFileOpen="true" />
      </target>
    <rules>
      <!--规则路由这里使用了在【AsyncWrapper】异步包装器下的target1则不会将消息调用异步方法写入日志文件；只有【规则路由这里使用了在【AsyncWrapper】异步包装器下的target2才会将消息调用异步方法写入日志文件】-->
      <logger name="*" minlevel="Info" writeTo="target1"/> 
    </rules>
  </targets> 

3.3.3、rules路由规则

? ? 路由规则是用一个记录器【logger】元素定义的；且路由规则控制了哪些记录器对象、日志级别处于活动状态和输出的目标内容；

如下是单规则路由示例（启用匹配所有记录器【name=*】,且最小日志级别为Trace及其之后【Trace\Debug\Info\Warn\Error\Fatal】的消息输出到控制台上显示）：

<targets>
       <target name="colorConsole" xsi:type="ColoredConsole" layout="[${date:format=HH\:mm\:ss}]:${message} ${exception:format=message}" />
</targets>
<rules>
       <logger name="*" minlevel="Trace" writeTo="colorConsole" enable="true" />
</rules>

?《1》记录器的名称过滤器说明

? ? 当在需要输出日志的类中使用【nlog.logmanager.getCurrentClassLogger()】时，记录器(Logger)名称将具有“ namespace.classname”的格式。这使得在名称空间中的所有类设置过滤非常方便；如下所示：

namespace Test_NLog.Test
{
    public class TestNlog
    {
        //使用该方法将记录该类对应的命名空间和名称用于路由规则的过滤【即：Test_NLog.Test.TestNlog】
        Logger logger = LogManager.GetCurrentClassLogger();

        public void Test()
        {
            string log = $"这是用于测试_TestNlog=>{this.GetType().Name} 方法输出到日志";

            logger.Trace($"Trace_{log}");
            logger.Debug($"Debug_{log}");
            logger.Info($"Info_{log}");
            logger.Warn($"Warn_{log}");
            logger.Error($"Error_{log}");
            logger.Fatal($"Fatal_{log}");
        }

    }//Class_end
}

<!--将匹配Test_NLog.Test命名空间下所有类中级别【在Trace和Info之间（即：Warn\Error\Fatal】日志信息被写入【asyncFile2】格式文件中，且之后的规则将不再执行（因为指定了final=true））-->
<logger name="Test_NLog.Test.*" minlevel="Warn" maxlevel="Error" writeTo="asyncFile2" final="true"/>


<!--只匹配Test_NLog.Test.TestNlog这一个类中级别【在Trace和Info之间（即：Warn\Error\Fatal】日志信息被写入【asyncFile2】格式文件中，且之后的规则将不再执行（因为指定了final=true））-->
<logger name="Test_NLog.Test.TestNlog" minlevel="Warn" maxlevel="Error" writeTo="asyncFile2" final="true"/>

《2》日志级别

《3》布局内容

NLog官方的布局内容详细文档https://nlog-project.org/config/?tab=layout-renderers? ? ??

创作打卡挑战赛

赢取流量/现金/CSDN周边激励大奖