NLog详解

大家好，欢迎来到IT知识分享网。

目录

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 { /// <summary> /// 写日志 /// </summary> /// <param name="content"></param> 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<WeatherForecastController> _logger; //public WeatherForecastController(ILogger<WeatherForecastController> logger) //{ // _logger = logger; //} [HttpGet(Name = "GetWeatherForecast")] public IEnumerable<WeatherForecast> 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; /// <summary> /// /// </summary> static NLogService() { //判断配置文件NLog.config是否存在 bool flag = File.Exists(Path.Combine(Path.GetDirectoryName(typeof(NLogService).Assembly.Location), "NLog.config")); //获取配置信息 LogManager.Configuration = GetXmlLoggingConfiguration(!flag); } /// <summary> /// /// </summary> private NLogService() { } /// <summary> /// logger 初始化 /// </summary> 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)); } /// <summary> /// 获取logger 配置信息 /// </summary> /// <param name="fromManifestResource"></param> /// <returns></returns> 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; } /// <summary> /// write info log /// </summary> /// <param name="msg"></param> public static void Info(string msg) { SetLogger(); _logger.Info(msg); } /// <summary> /// write warn log /// </summary> /// <param name="msg"></param> public static void Warn(string msg) { SetLogger(); _logger.Warn(msg); } /// <summary> /// write debug log /// </summary> /// <param name="msg"></param> public static void Debug(string msg) { SetLogger(); _logger.Debug(msg); } /// <summary> /// write error log /// </summary> /// <param name="msg"></param> public static void Error(string msg) { SetLogger(); _logger.Error(msg); } /// <summary> /// write exception log /// </summary> /// <param name="e"></param> public static void Exception(Exception e) { SetLogger(); _logger.Error<Exception>(e); } } }

2）接口启动项目中，新增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" xsi:schemaLocation="http://www.nlog-project.org/schemas/NLog.xsd NLog.xsd" autoReload="true" internalLogLevel="Info" internalLogFile="nlog-internal.log"> <!--Nlog 文档参考地址：https://github.com/NLog/NLog/wiki--> <!--internalLogLevel Nlog内部日志记录为Off关闭。除非纠错，不可以设为Trace否则速度很慢，起码Debug以上--> <!--自定义日志输出文件路径及命名规则--> <variable name="logDir" value="${basedir}/nlogs/${date:format=yyyyMMdd}/${level}.log"/> <!-- Load the ASP.NET Core plugin,enable asp.net core layout renderers--> <extensions> <add assembly="NLog.Web.AspNetCore" /> </extensions> <!--define various log targets--> <targets async="true"> <!--写入文件--> <!--滚动日志文件上限数，滚动日志文件数达到上限新的文件内容会覆盖旧文件内容 --> <!--archiveAboveSize每个日志文件大小的最大值（单位：字节），主日志文件超过大小超过该值时会将文件内容写入滚动日志并清空主日志文件内容--> <!--${basedir}表示当前应用程序域所在的根目录--> <target name="allfile" xsi:type="File" fileName="${basedir}/adminlogs/all.txt" archiveFileName="${basedir}/adminlogs/all.{}.txt" archiveEvery="Day" archiveNumbering="DateAndSequence" archiveAboveSize="" 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}"/> <!--SQL--> <target name="sqlfile" xsi:type="File" fileName="${basedir}/adminlogs/all-sql.txt" archiveFileName="${basedir}/adminlogs/all.sql{}.txt" archiveEvery="Day" archiveNumbering="DateAndSequence" archiveAboveSize="" 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}"/> <!--SQL写入控制台--> <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> <!--define various log rules--> <rules> <!-- 除非调试需要，把 .NET Core 程序集的 Debug 输出都屏蔽 Trace -> Debug-> Info ->Warn-> Error-> Critical--> <!--All logs, including from Microsoft--> <logger name="*" minlevel="Trace" writeTo="allfile" /> <!-- 除非调试需要，把系统的 Debug 输出都屏蔽 --> <logger name="*" minLevel="Debug" writeTo="console"/> <!--跳过所有级别的Microsoft组件的日志记录--> <logger name="Microsoft.*" writeTo="blackhole" final="true" /> <!--<logger name="System.*" writeTo="blackhole" final="true" />--> </rules> </nlog> 

项目运行后的日志：

3.NLog配置参数详解

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

3.1 全局配置

3.2 根元素

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

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

3.2.1 targets

<targets async="true"> <!--写入文件--> <!--滚动日志文件上限数，滚动日志文件数达到上限新的文件内容会覆盖旧文件内容 --> <!--archiveAboveSize每个日志文件大小的最大值（单位：字节），主日志文件超过大小超过该值时会将文件内容写入滚动日志并清空主日志文件内容--> <!--${basedir}表示当前应用程序域所在的根目录--> <target name="allfile" xsi:type="File" fileName="${basedir}/adminlogs/all.txt" archiveFileName="${basedir}/adminlogs/all.{}.txt" archiveEvery="Day" archiveNumbering="DateAndSequence" archiveAboveSize="" 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> <!-- 除非调试需要，把 .NET Core 程序集的 Debug 输出都屏蔽 Trace -> Debug-> Info ->Warn-> Error-> Critical--> <!--All logs, including from Microsoft--> <logger name="*" minlevel="Trace" writeTo="allfile" /> <!-- 除非调试需要，把系统的 Debug 输出都屏蔽 --> <logger name="*" minLevel="Debug" writeTo="console"/> <!--跳过所有级别的Microsoft组件的日志记录--> <logger name="Microsoft.*" writeTo="blackhole" final="true" /> <!--<logger name="System.*" 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