NLog详解

目录

1.简介

2.项目中使用NLog

2.1 快速使用NLog

2.2 通过配置文件使用NLog

3.NLog配置参数详解

3.1 全局配置

3.2 根元素

3.2.1 targets

3.2.1.1 layout

3.2.2 rules

3.2.3 extensions

3.2.4 include

3.2.5 variable

4.附录

---

1.简介

NLog是一个基于.NET平台编写的类库，我们可以使用NLog在应用程序中添加极为完善的跟踪调试代码。

NLog是一个简单灵活的.NET日志记录类库。通过使用NLog，我们可以在任何一种.NET语言中输出带有上下文的（contextual information）调试诊断信息，根据喜好配置其表现样式之后发送到一个或多个输出目标（target）中。

NLog的API非常类似于log4net，且配置方式非常简单。NLog使用路由表（routing table）进行配置，但log4net却使用层次性的appender配置，这样就让NLog的配置文件非常容易阅读，并便于今后维护。

官网：NLog

文档地址：Home · NLog/NLog Wiki · GitHub

2.项目中使用NLog

首先使用VS2022创建基于.Net6的WebApi项目MyNLog，然后项目中创建类库项目MyNLog.Utils

2.1 快速使用NLog

1）MyNLog.Utils项目，从nuget中引入NLog

2） MyNLog.Utils项目中创建类NLogService.cs，使用NLog最简单的方法写日志

using NLog;
 
namespace MyNLog.Utils
{
    public class NLogService
    {
        /// 
        /// 写日志
        /// 
        /// 
        public static void WriteLog(string content)
        {
            var config = new NLog.Config.LoggingConfiguration();// 创建一个配置文件对象
            //创建日志写入目的地
            var logfile = new NLog.Targets.FileTarget("logfile") { FileName = $"logs/{DateTime.Now.ToString("yyyy-MM-dd")}.txt" };
            //添加日志路由规则
            config.AddRule(LogLevel.Debug, LogLevel.Fatal, logfile);
            //配置文件生效
            LogManager.Configuration = config;
            //创建日志记录对象方式1
            Logger Logger = LogManager.GetCurrentClassLogger();
            //创建日志记录对象方式2，手动命名
            //Logger Logger2 = LogManager.GetLogger("MyLogger");
            //打出日志
            Logger.Info(content);
        }
    }
}

3）项目 MyNLog中引用MyNLog.Utils项目，然后在WeatherForecastController中调用日志写入方法

using Microsoft.AspNetCore.Mvc;
 
namespace MyNLog.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };
 
        //private readonly ILogger _logger;
 
        //public WeatherForecastController(ILogger logger)
        //{
        //    _logger = logger;
        //}
 
        [HttpGet(Name = "GetWeatherForecast")]
        public IEnumerable Get()
        {
            MyNLog.Utils.NLogService.WriteLog("Hello NLog");//写日志
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

4）启动项目，Swagger中调用接口，会在bin/Debug/net6.0/logs中看见写入的日志

2.2 通过配置文件使用NLog

参见 Getting started with ASP.NET Core 6 · NLog/NLog Wiki · GitHub

1）修改NLogService中的代码

using System;
using System.Diagnostics;
using System.IO;
using System.Reflection;
using System.Xml;
using NLog.Config;
using NLog;
 
namespace MyNLog.Utils
{
    public class NLogService
    {
		private static ILogger _logger;
		/// 
		/// 
		/// 
		static NLogService()
		{
			//判断配置文件NLog.config是否存在
			bool flag = File.Exists(Path.Combine(Path.GetDirectoryName(typeof(NLogService).Assembly.Location), "NLog.config"));
			//获取配置信息
			LogManager.Configuration = GetXmlLoggingConfiguration(!flag);
		}
		/// 
		/// 
		/// 
		private NLogService()
		{
		}
		/// 
		/// logger 初始化
		/// 
		private static void SetLogger()
		{
			StackFrame stackFrame = new StackFrame(2, false);
			MethodBase method = stackFrame.GetMethod();
			_logger = LogManager.GetLogger(string.Format("{0}.{1}", method.DeclaringType, method.Name));
		}
		/// 
		/// 获取logger 配置信息
		/// 
		/// 
		/// 
		public static XmlLoggingConfiguration GetXmlLoggingConfiguration(bool fromManifestResource = true)
		{
			XmlLoggingConfiguration result;
			if (fromManifestResource)
			{
				Type declaringType = MethodBase.GetCurrentMethod().DeclaringType;
				string text = ((declaringType != null) ? declaringType.Namespace : null) ?? "Logging.NLog";
				Assembly executingAssembly = Assembly.GetExecutingAssembly();
				Stream manifestResourceStream = executingAssembly.GetManifestResourceStream(text + ".nlog.config");
				XmlTextReader xmlTextReader = new XmlTextReader(manifestResourceStream);
				result = new XmlLoggingConfiguration(xmlTextReader);
			}
			else
			{
				string text2 = Path.Combine(Path.GetDirectoryName(typeof(NLogService).Assembly.Location), "nlog.config");
				bool flag = !File.Exists(text2);
				if (flag)
				{
					throw new FileNotFoundException("nlog.config文件未找到。");
				}
				result = new XmlLoggingConfiguration(new FileInfo(text2).FullName);
			}
			return result;
		}
		/// 
		/// write info log
		/// 
		/// 
		public static void Info(string msg)
		{
			SetLogger();
			_logger.Info(msg);
		}
		/// 
		/// write warn log
		/// 
		/// 
		public static void Warn(string msg)
		{
			SetLogger();
			_logger.Warn(msg);
		}
		/// 
		/// write debug log
		/// 
		/// 
		public static void Debug(string msg)
		{
			SetLogger();
			_logger.Debug(msg);
		}
		/// 
		/// write error log
		/// 
		/// 
		public static void Error(string msg)
		{
			SetLogger();
			_logger.Error(msg);
		}
		/// 
		/// write exception log
		/// 
		/// 
		public static void Exception(Exception e)
		{
			SetLogger();
			_logger.Error(e);
		}
	}
}

2）接口启动项目中，新增NLog.config配置文件

"1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.nlog-project.org/schemas/NLog.xsd NLog.xsd"
      autoReload="true"
      internalLogLevel="Info"
      internalLogFile="nlog-internal.log">
 
	
	
	
	<variable name="logDir" value="${basedir}/nlogs/${date:format=yyyyMMdd}/${level}.log"/>
	
	<extensions>
		<add assembly="NLog.Web.AspNetCore" />
	extensions>
	
	<targets async="true">
		
		
		
		
		<target name="allfile" xsi:type="File"
				fileName="${basedir}/adminlogs/all.txt"
				archiveFileName="${basedir}/adminlogs/all.{###}.txt"
				archiveEvery="Day"
				archiveNumbering="DateAndSequence"
				archiveAboveSize="20000000"
				maxArchiveFiles="30"
				keepFileOpen="true"
				layout="${longdate} | ${event-properties:item=EventId_Id} | ${uppercase:${level}} | ${logger} | ${aspnet-request-iP:CheckForwardedForHeader=true} | ${event-properties:item=user} | ${aspnet-request-url} | ${message} | ${event-properties:item=requestParam} | ${event-properties:item=jsonResult} | ${onexception:${exception:format=tostring}"/>
 
		
		<target name="sqlfile" xsi:type="File"
			fileName="${basedir}/adminlogs/all-sql.txt"
			archiveFileName="${basedir}/adminlogs/all.sql{###}.txt"
			archiveEvery="Day"
			archiveNumbering="DateAndSequence"
			archiveAboveSize="20000000"
			maxArchiveFiles="30"
			keepFileOpen="false"
			layout="===========================================${newline} ${longdate} - ${aspnet-request-iP} - ${aspnet-request-headers:HeaderNames=userid} - ${aspnet-request-url} ${newline} ${message}"/>
 
		
		<target name="console" xsi:type="ColoredConsole" layout="${date:format=MM-dd HH\:mm\:ss} | ${uppercase:${level}} | ${logger} | ${aspnet-request-iP} | ${aspnet-request-url} | ${message}"/>
		
		<target name="consoleSql" xsi:type="ColoredConsole" layout="${date:format=MM-dd HH\:mm\:ss} | ${aspnet-request-url} ${newline} ${message}"/>
		
		<target name="blackhole" xsi:type="Null" />
	targets>
	
	<rules>
		
		
		<logger name="*" minlevel="Trace" writeTo="allfile" />
		
		<logger name="*" minLevel="Debug" writeTo="console"/>
		
		<logger name="Microsoft.*" writeTo="blackhole" final="true" />		
		
	rules>
nlog>

项目运行后的日志：

 

3.NLog配置参数详解

关于配置文件相关参数说明参见：https://github.com/NLog/NLog/wiki/Configuration-file

3.1 全局配置

      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.nlog-project.org/schemas/NLog.xsd NLog.xsd"
      autoReload="true"
      internalLogLevel="Info"
      internalLogFile="nlog-internal.log">

 

3.2 根元素

在配置文件的根元素中，我们可以指定如下的子元素。其中前两个是必须设定的，其余三个为可选设定。

• targets：定义日志的输出目标
• rules：定义对日志信息的路由规则
• extensions：定义从其他dll文件中加载的NLog扩展模块
• include：引入外部的配置文件
• variable：定义配置文件中用到的变量

3.2.1 targets

<targets async="true">
		
		
		
		
		<target name="allfile" xsi:type="File"
				fileName="${basedir}/adminlogs/all.txt"
				archiveFileName="${basedir}/adminlogs/all.{###}.txt"
				archiveEvery="Day"
				archiveNumbering="DateAndSequence"
				archiveAboveSize="20000000"
				maxArchiveFiles="30"
				keepFileOpen="true"
				layout="${longdate} | ${event-properties:item=EventId_Id} | ${uppercase:${level}} | ${logger} | ${aspnet-request-iP:CheckForwardedForHeader=true} | ${event-properties:item=user} | ${aspnet-request-url} | ${message} | ${event-properties:item=requestParam} | ${event-properties:item=jsonResult} | ${onexception:${exception:format=tostring}"/>
	targets>

 Nlog允许用户配置单个文件大小, 放置在内容过长效率过慢,配置了大小之后, Nlog会自动创建一个新的文件副本,插入新的日志输出。

常用的参数配置说明：

targets更多参数配置参见：File target · NLog/NLog Wiki · GitHub

3.2.1.1 layout

layout参数配置用来规定输出内容格式，必填项及默认值：${longdate}|${level:uppercase=true}|${logger}|${message:withexception=true}

• $ {cached} -  将缓存应用于另一个布局输出。
• $ {db-null} - 为数据库渲染DbNull
• $ {exception} - 通过调用Logger方法之一提供的异常信息
• $ {level} - 日志级别（例如ERROR，DEBUG）或级别序数（数字）
• $ {literal} - 字符串文字。（文本）-有用，以逃避括号
• $ {logger} - 记录器名称。GetLogger，GetCurrentClassLogger等
• $ {message} - （格式化的）日志消息。
• $ {newline} - 换行文字。
• $ {object-path} -  渲染对象的（嵌套）属性
• $ {onexception} -  仅在为日志消息定义了异常时才输出内部布局。
• $ {var} - 渲染变量

呼叫站点和堆栈跟踪

• $ {callsite} - 调用站点（类名，方法名和源信息）
• $ {callsite-linenumber} - 呼叫站点源行号。
• $ {stacktrace} - 渲染堆栈跟踪

条件

• $ {when} -  仅在满足指定条件时输出内部布局。
• $ {whenempty} -  当内部布局产生空结果时，输出替代布局。

上下文信息

• $ {activityid} - 将System.Diagnostics跟踪关联ID记录到日志中。
• $ {all-event-properties} - 记录所有事件上下文数据。
• $ {event-context} -  记录事件属性数据-替换为$ {event-properties}
• $ {event-properties} - 记录事件属性数据-重命名$ {event-context}
• $ {gdc} - 全局诊断上下文项。包含每个应用程序实例值的字典结构。
• $ {install-context} - 安装参数（传递给InstallNLogConfig）。
• $ {mdc} - 映射诊断上下文-线程局部结构。
• $ {mdlc} - 异步映射诊断上下文-线程局部结构。MDC的异步版本
• $ {ndc} - 嵌套诊断上下文-线程局部结构。
• $ {ndlc} - 异步嵌套诊断上下文-线程本地结构。

专柜

• $ {counter} - 一个计数器值（在每个布局渲染中增加）
• $ {guid} - 全局唯一标识符（GUID）。
• $ {sequenceid} - 日志序列号

日期和时间

• $ {date} - 当前日期和时间。
• $ {longdate} - 日期和时间，采用可排序的长格式`yyyy-MM-dd HH：mm：ss.ffff`。
• $ {qpc} - 高精度计时器，基于QueryPerformanceCounter返回的值。
• $ {shortdate} - 短日期，格式为yyyy-MM-dd。
• $ {ticks} - 当前日期和时间的“ Ticks”值。
• $ {时间} - 在24小时，可排序的格式HH的时间：MM：ss.mmm。

编码和字符串转换

• $ {json-encode} -  使用JSON规则转义另一个布局的输出。
• $ {left} -  文字的左半部分
• $ {小写} -  将另一个布局输出的结果转换为小写。
• $ {norawvalue} -  防止将另一个布局渲染器的输出视为原始值
• $ {pad} -  将填充应用于另一个布局输出。
• $ {replace} -  将另一个布局的输出中的字符串替换为另一个字符串。正则表达式可选
• $ {replace-newlines} -  用另一个字符串替换换行符。
• $ {right} -  文字的右侧
• $ {rot13} -  使用ROT-13解码“加密”的文本。
• $ {substring} -  文本的子字符串
• $ {trim-whitespace} -  从另一个布局渲染器的结果修剪空白。
• $ {uppercase} -  将另一个布局输出的结果转换为大写。
• $ {url-encode} -  编码另一个布局输出的结果，以供URL使用。
• $ {wrapline} -  以指定的行长包装另一个布局输出的结果。
• $ {xml-encode} -  将另一个布局输出的结果转换为XML兼容的。

环境和配置文件

• $ {appsetting} -. config文件 NLog.Extended中的应用程序配置设置
• $ {configsetting} - 来自appsettings.json或ASP.NET Core和.NET Core中其他配置的值 NLog.Extensions.Logging NLog.Extensions.Hosting NLog.Web.AspNetCore
• $ {environment} - 环境变量。（例如PATH，OSVersion）
• $ {environment-user} - 用户身份信息（用户名）。
• $ {}注册表 - 从Windows注册表中的值。

文件和目录

• $ {basedir} - 当前应用程序域的基本目录。
• $ {currentdir} - 应用程序的当前工作目录。
• $ {file-contents} - 呈现指定文件的内容。
• $ {filesystem-normalize} -  通过将文件名替换为安全字符来过滤文件名中不允许的字符。
• $ {} nlogdir - 其中NLog.dll所在的目录。
• $ {specialfolder} - 系统专用文件夹路径（包括“我的文档”，“我的音乐”，“程序文件”，“桌面”等）。
• $ {tempdir} - 临时目录。

身分识别

• $ {identity} - 线程身份信息（名称和身份验证信息）。
• $ {windows-identity} - 线程Windows身份信息（用户名）
• $ {windows-identity} - 线程Windows身份信息（用户名） Nlog.WindowsIdentity

整合方式

• $ {gelf} - 将日志转换为GELF格式 NLog.GelfLayout 外部
• $ {log4jxmlevent} - 与log4j，Chainsaw和NLogViewer兼容的XML事件描述。

进程，线程和程序集

• $ {appdomain} - 当前的应用程序域。
• $ {assembly-version} - 默认应用程序域中可执行文件的版本。
• $ {gc} - 有关垃圾收集器的信息。
• $ {hostname} - 运行该进程的计算机的主机名。
• $ {local-ip} - 来自网络接口的本地IP地址。
• $ {machinename} - 运行进程的计算机名。
• $ {performancecounter} - 性能计数器。
• $ {processid} - 当前进程的标识符。
• $ {processinfo} - 有关正在运行的进程的信息。例如StartTime，PagedMemorySize
• $ {processname} - 当前进程的名称。
• $ {processtime} - 格式为HH：mm：ss.mmm的处理时间。
• $ {threadid} - 当前线程的标识符。
• $ {threadname} - 当前线程的名称。

Silverlight

• $ {document-uri} - 承载当前Silverlight应用程序的HTML页面的URI。
• $ {sl-appinfo} - 有关Silverlight应用程序的信息。

Web，ASP.NET和ASP.NET Core

• $ {ASPNET-appbasepath} - ASP.NET应用程序的基本路径（内容根） NLog.Web NLog.Web.AspNetCore
• $ {ASPNET应用} - ASP.NET应用程序变量。 网络日志
• $ {ASPNET环境} - ASP.NET环境名称 NLog.Web.AspNetCore
• $ {ASPNET项} - ASP.NET`HttpContext`项变量。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET-MVC-行动} - ASP.NET MVC动作名称 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET-MVC控制器} - ASP.NET MVC控制器名称 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET请求} - ASP.NET请求变量。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET-请求的contentType} - ASP.NET Content-Type头（实施例应用/ JSON） NLog.Web.AspNetCore
• $ {ASPNET请求，饼干} - ASP.NET请求的cookie的内容。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET请求形式} - ASP.NET请求表的内容。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET请求报头} - ASP.NET部首键/值对。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET请求主机} - ASP.NET请求主机。 NLog.Web NLog.Web.AspNetCore
• $ {aspnet-request-ip} - 客户端IP。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET请求-方法} - ASP.NET请求方法（GET，POST等）。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET请求，贴体} - ASP.NET贴体/净荷 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET-请求的查询字符串} - ASP.NET请求的查询字符串。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET，请求引荐} - ASP.NET请求引用。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET请求的URL} - ASP.NET请求URL。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET请求，用户代理} - ASP.NET请求用户代理。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET-响应的StatusCode} - ASP.NET响应状态代码的内容。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET会话} - ASP.NET Session变量。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET-的SessionID} - ASP.NET会话ID的变量。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET-traceidentifier} - ASP.NET跟踪标识 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET用户-的authType} - ASP.NET用户验证。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET用户身份} - ASP.NET用户变量。 NLog.Web NLog.Web.AspNetCore
• $ {ASPNET用户-isauthenticated} - ASP.NET用户身份验证？ NLog.Web NLog.Web.AspNetCore
• $ {ASPNET-webrootpath} - ASP.NET Web根目录路径（wwwroot文件） NLog.Web NLog.Web.AspNetCore
• $ {iis-site-name} - IIS网站的名称。 NLog.Web NLog.Web.AspNetCore

3.2.2 rules

规则部分控制如何将Logger对象中的LogEvents重定向到输出目标。其中记录器名称和日志级别可用于筛选。

当创建一个NLogLogger对象时，必须提供一个类似NLog.LogManager.GetLogger的记录器名称（“我的记录器名称”）。也可以使用NLog.LogManager.GetCurrentClassLogger（）从类上下文中提取记录器名称，其中记录器名称变为“NameSpace.ClassName”。

<rules>
		
		
		<logger name="*" minlevel="Trace" writeTo="allfile" />
		
		<logger name="*" minLevel="Debug" writeTo="console"/>
		
		<logger name="Microsoft.*" writeTo="blackhole" final="true" />		
		
	rules>

 参数配置说明

官方文档参见：https://github.com/NLog/NLog/wiki/Configuration-file#rules

3.2.3 extensions

可以将扩展配置为包括其他NLog包或自定义包：

只需在＜extensions/＞中的配置中引用DLL

<extensions>
  <add assembly="NLog.Web.AspNetCore" />
extensions>

3.2.4 include

NLog提供了包含文件功能，因此配置可以存储在多个文件中

<include file="nlog-common.config" />

与NLog-config中的大多数属性一样，file属性可能引用变量。下面的示例包括一个与nlog运行的计算机名称相同的文件。

<include file="${machinename}.config"/>

3.2.5 variable

NLog配置变量允许您通过减少重复文本来简化配置。变量可用于为常用的（或长而复杂的）NLog布局指定人名。这样可以更容易地组织和构造NLog配置。

<variable name="logDir" value="${basedir}/nlogs/${date:format=yyyyMMdd}/${level}.log"/>

4.附录

输出日志到数据库参见：Database target · NLog/NLog Wiki · GitHub

输出日志到控制台参见：ColoredConsole target · NLog/NLog Wiki · GitHub