NLog在.NET Framework中的使用学习心得

NLog使用

帮助文档

官网配置说明

 引入

1. Install the latest NLog from NuGet.
2. 从NuGet也可以下载 NLog.Config，但是只针对于.NET Framework。

#命令行安装也可以
Install-Package 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"
      throwExceptions="false"
      internalLogLevel="Off" internalLogFile="c:\temp\nlog-internal.log">

	<!-- 添加变量-->
	<variable name="logDirectory" value="logs"/>

	<!--添加target节点，用以指定写入的文件，一个target有一个name，在rules中指定name，相应的规则就会写入相应的文件中-->
	<targets>
		<target xsi:type="File" name="allfile" fileName="${logDirectory}/nlog-all-${shortdate}.log"
				layout="${longdate}|${logger}|${uppercase:${level}}|${message} ${exception}" encoding="utf-8"/>
		<target xsi:type="File" name="testfile" fileName="${logDirectory}/nlog-test-${shortdate}.log"
		        layout="${longdate}|${logger}|${uppercase:${level}}|${message:exceptionSeparator=\r\n:withException=true} ${exception:format=Type,Message,Method,StackTrace}" encoding="utf-8"/>
        	<!-- 不需要的日志记录可以放到黑洞中-->
    <target xsi:type="Null" name="blackhole" />
	</targets>

	<rules>
		<!-- 添加rules，name可指定命名空间，或者类 -->
		<!-- 添加rules，filter可以添加条件 when -->
		<logger name="*" minlevel="Info" writeTo="testfile" >
			<filters defaultAction="Ignore">
				<when condition="equals(message ,'test')" action="Log"/>
			</filters>
		</logger>
        <!--  MicroSoft相关的日志直接丢进黑洞里 并且因为final的原因，不会向下匹配规则-->
        <logger name="Microsoft.*" minlevel="Trace" writeTo="blackhole" final="true" />
		<logger name="*" minlevel="Info" writeTo="allfile" />
	</rules>
</nlog>

 targets节点

<target xsi:type="File" name="allfile" fileName="${logDirectory}/nlog-all-${shortdate}.log"
				layout="${longdate}|${logger}|${uppercase:${level}}|${message} ${exception}" encoding="utf-8"/>

1. 作用：

   用以指定写入的文件，一个target有一个name，在rules中指定name，相应的规则就会写入相应的文件中

2. 属性：

   1. xsi:type：指定写入的形式，可以为txt，email等等

   2. name：target的名称属性，用来调用

   3. fileName：指定写入的文件名，可以使用变量。

   4. layout：写入内容的样式指定。

      <target layout="${longdate}|${logger}|${uppercase:${level}}|${message:exceptionSeparator=\r\n:withException=true} ${exception:format=Type,Message,Method,StackTrace}" encoding="utf-8"/>
      

      1. ${message:exceptionSeparator=\r\n:withException=true} ：
         1. exceptionSeparator=\r\n 代表异常信息使用换行分割，参考文档
         2. :withException=true 代表message带上格式化后的异常信息，包括：message，method，type，StackTrack属性内容。
         3. ${exception:format=Type,Message,Method,StackTrace}：对异常信息进行格式化处理，参考文档

   5. encoding：写入文件的编码，乱码的时候可以调一调。

      1. 一些预设的变量：date,logger,level,message,exception

      2. 符号含义

         1. : is the value separator.
         2. } is the end of the layout

         Examples:

         1. ${appdomain:format={1\}{0\}} (escape of })
         2. ${rot13:inner=${scopenested:topFrames=3:separator=x}} (no escaping needed)
         3. ${when:when=1 == 1:Inner=Test\: Hello} (escape of :)

3. 其他属性

   包括文件多大，多久删除，多久备份一次

4. 其他说明

   ${message}说明：

   LogHelper.Logger.Error(e,"test");
   

   如果这样写，message 就是test,如果不写 就是e.Message。

 rules节点

1. 基本样式

<logger name="*" minlevel="Info" writeTo="allfile" />

2. 作用及基本属性

   通过编写规则实现不同的日志写入不同的文件中，eg:

   <targets>
       <target xsi:type="Null" name="blackhole" />
     </targets>
    
     <rules>
       <!--All logs, including from Microsoft-->
       <logger name="*" minlevel="Trace" writeTo="allfile" />
    
       <!-- Microsoft相关日志 扔进黑洞中-->
       <logger name="Microsoft.*" minlevel="Trace" writeTo="blackhole" final="true" />
       <logger name="*" minlevel="Trace" writeTo="ownFile-web" />
     </rules>
   

   1. name:可以使用正则表达式，匹配相应的命名空间，类库

   2. minlevel：指定rule记录的最小级别的日志level。

   3. writeTo:匹配Target中相应的name，表明该条规则写入的文件是Target的文件

   4. final：最终规则匹配后不处理任何规则,

      ：当一条log进入rules中匹配，他可以匹配很多条规则，所以对应很多的Target，但是如果他匹配到一条规则带有final=true 的属性，那他就不会继续向下匹配。

3.  filter属性

   		<logger name="*" minlevel="Info" writeTo="testfile" final="true">
                   <!--defaultAction代表执行的操作 默认的操作-->
   			<filters defaultAction="Ignore">
                   <!--action代表执行的操作 记录还是忽略-->
   				<when condition="equals(message ,'test')" action="Log"/>
   			</filters>
   		</logger>
   

   1. contition预设

      1. Predefined Tokens
      • message - LogEvent 格式化消息
      • logger - 记录器名称
      • level - LogLevel 对象
      • exception - 异常对象（NLog 5.0 引入）
      • ${layout} - 所有可用的布局选项（堆栈跟踪除外）。

   2. 条件语法

      The filter expressions are written in a special mini-language. The language consists of:

      • 关系运算符：==、!=、<、<=和注意：某些>=预定义的*XML 字符**可能需要转义。**例如，如果您尝试使用“<”字符，XML 解析器会将其解释为开始标记，从而导致配置文件中出现错误。相反，在这种情况下使用 ‘<’ 的转义版本。<
      • 布尔运算符：and, or,not
      • 始终作为布局评估的字符串文字 -${somerenderer}
      • 布尔文字 -true和false
      • 数字文字 - 例如12345（整数文字）和12345.678（浮点文字）
      • 日志级别文字 - LogLevel.Trace, LogLevel.Debug, …LogLevel.Fatal
      • 用于访问最常见日志事件属性的预定义关键字-level和message``logger
      • 大括号 - 覆盖默认优先级并将表达式组合在一起
      • 条件函数 - 执行string和object测试
      • 单引号应该用另一个单引号转义。

   3. 条件函数

      • contains(s1,s2)确定第二个字符串是否是第一个字符串的子字符串。返回：true当第二个字符串是第一个字符串的子字符串时，false否则。

      • ends-with(s1,s2)确定第二个字符串是否是第一个字符串的后缀。返回：true当第二个字符串是第一个字符串的前缀时，false否则。

      • equals(o1,o2)比较两个对象是否相等。返回：true当两个对象相等时，false否则。

      • length(s)返回字符串的长度。

      • starts-with(s1,s2)确定第二个字符串是否是第一个字符串的前缀。返回：true当第二个字符串是第一个字符串的前缀时，false否则。

      • regex-matches(input, pattern, options)在 NLog 4.5 中引入。指示正则表达式pattern是否在指定input字符串中找到匹配项。options是来自RegexOptions枚举的可选逗号分隔值列表。

        返回：在输入字符串中找到匹配项时，true

        否则 false

        例子 ：regex-matches('${message}', '^foo$', 'ignorecase,singleline')

        <rules>
            <logger name="*" writeTo="file">
                <filters defaultAction="Log">
                    <when condition="exception != null" action="Log" />
                    <when condition="length(message) > 100" action="Ignore" />
                    <when condition="length('${OnHasProperties:True}') > 0" action="Ignore" />
                    <when condition="logger == 'MyApps.SomeClass'" action="Ignore" />
                    <when condition="(level >= LogLevel.Debug and contains(message, 'PleaseDontLogThis')) or level==LogLevel.Warn" action="Ignore" />
                    <when condition="not starts-with(message, 'PleaseLogThis')" action="Ignore" />
                    <when condition="contains(message, '&quot;Bob&quot;')" action="Ignore" />  <!-- "Bob" -->
                </filters>
            </logger>
        </rules>
        

   4. name的匹配样式

      <rules>
        <logger name="*" minlevel="Info" writeTo="logconsole" />
        <logger name="Name.Space.*" minlevel="Debug" writeTo="f1" />  
        <logger name="*.Class1" minlevel="Trace" writeTo="f2" />
        <logger name="*.Library.*" minlevel="Warn" writeTo="f3" />
      </rules>
      

   5. action的枚举类型

      defaultAction也可以为:

      • Ignore - 不应记录该消息。
      • IgnoreFinal - 不应记录该消息并忽略接下来的记录规则。
      • Log - 应记录该消息。
      • LogFinal - 应记录该消息并忽略接下来的记录规则。
      • Neutral - 过滤器不想决定是记录还是丢弃消息。

4. 日志level

Level	Typical Use
Fatal	发生了不好的事情；应用程序正在关闭
Error	失败了；应用程序可能会或可能不会继续
Warn	出乎意料的事情；应用程序将继续
Info	正常行为，例如发送的邮件、用户更新的个人资料等
Debug	用于调试；执行查询，用户认证，会话过期
Trace	用于跟踪调试；开始方法 X，结束方法 X

5. rules节点中要求匹配的元素属性名

• name – 匹配记录器对象的记录器名称 - 可能包含通配符（* 和？）
• minlevel –记录的最低级别
• maxlevel – 记录的最高级别
• level –单级记录
• levels - 以逗号分隔的要记录的级别列表
• writeTo – 逗号分隔的要写入的目标列表
• final –最终规则匹配后不处理任何规则
• enabled - 设置为false禁用规则而不删除它
• ruleName - 允许使用和进行规则查找的规则标识符 Configuration.RemoveRuleByName。在 NLog 4.6.4 中引入
• finalMinLevel - 匹配的记录器将被限制为以下规则的指定最低级别。

 variable节点

NLog 配置变量允许您通过减少重复文本来简化配置。变量可用于为常用（或长而复杂）的 NLog 布局提供人名。这使得组织和构建 NLog 配置变得更加容易。

<!--声明节点-->
<variable name="logDirectory" value="logs/${shortdate}" />
<!--使用节点-->
<target name="file1" xsi:type="File" fileName="${logDirectory}/file1.txt"/>

总结：

1. 首先配置变量，用以分类存储日志，比如说根据时间日期，或者日志等级等level

2. 配置targets节点，声明要存的文件位置，消息格式化类型等等。

   <target xsi:type="File" name="testfile" fileName="${logDirectory}/nlog-test-${shortdate}.log"
   		        layout="${longdate}|${logger}|${uppercase:${level}}|${message:exceptionSeparator=\r\n:withException=true} ${exception:format=Type,Message,Method,StackTrace}" encoding="utf-8"/>
   

3. 配置rules，根据不同的规则写入不同的target，

    比如说过滤Microsoft相关的日志，

   <!--  MicroSoft相关的日志直接丢进黑洞里 并且因为final的原因，不会向下匹配规则-->
   <logger name="Microsoft.*" minlevel="Trace" writeTo="blackhole" final="true" />
   

   比如说通过消息内包含test输入test.log中，

   		<logger name="*" minlevel="Info" writeTo="testfile" final="true">
   			<filters defaultAction="Ignore">
   				<when condition="equals(message ,'test')" action="Log"/>
   			</filters>
   		</logger>