.Net Core 2配置 Nlog 日志组件学习笔记 [2] 配置篇

上一篇大致介绍了Nlog在.net core如何配置，这一篇主要讲一下Nlog.Config配置文件。

------------------------我是第一条黄金分割线-----------------------

只有配置了一个或者多个Nlog配置文件， Nlog才会产生输出。可以使用XML配置Nlog

[1] 文件位置

启动的时候，系统会在各种文件中找nlog配置文件，如果找不到NLog加载失败。

标准应用程序配置文件（通常为applicationname.exe.config），应用程序目录中的applicationname.exe.nlog，应用程序目录中的nlog.config（名称敏感；使用docker-dotnet-core），nlog.dll.nlog位于nlog.dll所在的目录中（仅当在GAC中未安装nlog时），对于ASP.NET应用程序，按如下方式搜索文件：，标准Web应用程序文件web.config，web.nlog与web.config位于同一目录中，应用程序目录中的nlog.config，nlog.dll.nlog位于nlog.dll所在的目录中（仅当在GAC中未安装nlog时），另请参见显式nlog配置加载（包括有关xamarin android的assets文件夹的详细信息）。

[2] 文件布局

nlog配置的格式是XML格式，并且可以嵌入到Visual studio 的项目配置文件中，例如： app.config或web.config ，也可以是独立的xml，例如Nlog.config

1.要嵌入到项目配置文件中，请在配置部分下添加nlog-section元素，然后添加nlog元素:

</configSections>

...

<nlog>

...

</nlog>

</configuration>

2.作为单独的xml 文件，根元素应该是 nlog ：

...

</nlog>

XML命名空间的使用是可选的，但在Visual Studio中启用IntelliSense。nlog config在不使用命名空间时不区分大小写，在使用命名空间时区分大小写。

[3] 顶层元素

你可以将以下元素用作nlog的子元素。目标和规则在任何配置中都是必需的，其他的都是可选的，并且在高级场景中很有用。

targets – 定义日志目标/输出

rules – 定义日志路由规则

extensions – 从*.dll文件加载nlog扩展名

include– 包括外部配置文件

variable – 设置配置变量的值

ps：最简单的设置，就是一个目标元素<target> 和一个消息路由规则（记录器）<rules>

[4] Target 元素

target元素定义日志文件目标，每个target都用target元素表示，每个元素需要两个属性：

name – target名字

type – 目标输出类型– 例如 "File", "Database", "Mail". 如果使用命名空间了，那么元素前面应该 xsi:type.

除了这些属性之外，目标通常接受其他参数，这会影响诊断跟踪的写入方式。每个目标都有一组不同的参数，它们在Github项目的主页有详细的描述，并且它们对上下文敏感。只要配置了nlog会自动感知这些配置，并在Visual Studio中也可用。

例如 File target 接受定义文件名字作为输出文件的名称，Console target定义诊断跟踪是不是写入到标准的错误（stderr）而不是标准的输出(stdout)。

案例：Target元素包含：两个文件,一个网络目标，一个OutputDebugString目标文件

</targets>

Nlog提供了很多预先可以定义的Target，实际上创建一个target自定义也很容易请看：https://github.com/NLog/NLog/wiki/How-to-write-a-custom-target （下一篇再翻译）

[5] Rules元素

Rules会将记录器映射Target和 log levels

Rules元素有以下的属性：

name – 记录器名称筛选器-可能包括通配符（*和？）

minlevel – 记录最小的级别

maxlevel – 记录最大的级别

level – 要记录的单个级别

levels - 要记录的级别的逗号分隔列表

writeTo –要写入的target的逗号分隔列表

final – 最终规则匹配后不处理任何规则（有匹配的规则以后，不会进行处理）

enabled - 设置为false以禁用规则而不删除它

ruleName - 允许使用configuration.findruleByName和configuration.removeRuleByName进行规则查找的规则的名称。在NLOG 4.6.4中介绍

注意：虽然规则名为logger，但它不定义logger。它引用一个或多个记录器。通过将规则名称模式与记录器名称匹配，将规则映射到记录器。规则名称属性可以包含通配符（*和？）通过通配符匹配来匹配记录器名称。

*-匹配0个或更多字符

？-完全匹配1个字符

例如：

在nlog 4.6之前，只允许在模式的开头和/或结尾使用通配符（*）。

NLOG4.6+ 通配符（*和？）都允许使用

rules 规则是按顺序处理，记录器可以应用多个规则，找到匹配项后使用final停止处理规则。

规则定义哪个日志条目匹配的级别。具有其他级别的条目将与此规则不匹配。常用的说明符是minlevel。其他说明符允许更高级的配置。

如果规则包含多个声明属性的级别（级别、级别、minlevel和maxlevel），则只使用声明属性或集合的第一个级别，而忽略其余级别。

声明属性的级别按以下顺序处理：

level

levels

minlevel and maxlevel (它们有相同的优先权)

none (记录所有级别)

例如: 如果 minLevel="Warn" level="Info" 被使用,那么只有info level有效

如果规则标记为final并包含声明属性的任何级别，则final属性仅适用于指定的级别。

在一些级别属性中（level, minlevel 等）不能使用布局渲染，但是4.6+可以使用变量。

栗子：

所以你可以使用 ${gdc:myLevel}. 如果你要动态的修改这个规则, 可以通过代码进行配置：https://github.com/NLog/NLog/wiki/Configure-from-code

Rules 配置栗子

日志名为：name.space.class1 高于Debug级别属性配置的变量会被写入到f1中

记录器可以有任何名称，但在本例中，它是由命名空间“name.space”中的类“Class1”创建的。请参阅logManager.getcurrentClassLogger（）。

配置来自名为“name.space.class1”的记录器的消息，其中包含要写入“f1”目标的日志级别为调试，错误。

配置来自“name.space”命名空间中任何类的消息，以写入“f3”和“f4”目标，而不考虑级别。

配置为忽略来自name.space命名空间中任何类的消息，其级别介于debug和error（即debug、info、warn和error）之间。第一个规则选择记录器，但由于没有writeto，因此不会记录这些消息。而且，由于此规则包含“final=true”，最后一个规则不适用于与第一个规则匹配的记录器。

ps：final 的意思应该是不会处理后面的规则了？如果是false呢？可以尝试一下。

[6] 包含文件

nlog提供了一个include文件功能，这样配置就可以存储在多个文件中。

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

将ignoreerrors属性设置为true，以防止在无法加载include文件时启动失败--找不到文件，xml无效，…。使用故障排除日志记录部分记录错误。此属性是可选的，默认为false。

nlog 4.4.2，允许使用通配符（*）。

例子

更多例子: XML config <include /> example

[7] 变量

变量允许您通过访问环境信息来增强配置，并通过减少重复文本来简化配置。nlog定义可以在配置中使用的变量。此外，还可以定义和使用自定义变量。

定义一个自定义变量的例子：

变量的值可以过${varname}语法插入到属性值中。变量值甚至可以用来定义另一个变量的值。下面的示例显示如何使用预定义的变量shortdate以及如何定义和使用自定义变量logdirectory。

使用这个语法的时候，一个变量必须在使用前被定义，否则，配置初始化将失败，Nlog 4.1引入了一种变量值的新语法，查询变量布局渲染器

${var:varname}

与旧语法相比，此语法具有以下优势：

可以从API更改，删除和创建变量

可以为变量设置默认值，例如：${var:password:default=unknown}

默认情况下，配置重新加载时重置变量。要从当前配置号中获取变量，添加keepVariablesOnReload="true" 添加到nlog元素中(在nlog 4.4 中引入)

[8] 布局和布局渲染器

NLGO最强大的就是布局能力，在最简单的形式中，布局是带有由 ${ and }.分隔的嵌入标记的文本。这些标记称为布局呈现器，可以用于将上下文信息插入文本中。布局可以在许多地方使用，例如，它们可以控制在屏幕上写入或发送到文件的信息的格式，还可以控制文件名本身。这是非常强大的，我们一会儿就会看到。

让我们假设，我们希望用下面的方法对每条消息进行注释：

当前日期和时间

发出日志消息的类和方法的名称

日志级别

消息文本

非常简单：

我们可以使每个记录器的每条消息都转到一个单独的文件：

${logger}渲染器在文件名属性中使用，这会导致将每个日志消息写入名为logger name的文件。上面的示例将创建以下文件：

Name.Space.Class1.txt

Name.Space.Class2.txt

Name.Space.Class3.txt

Other.Name.Space.Class1.txt

Other.Name.Space.Class2.txt

Other.Name.Space.Class3.txt

[9] 日志级别

每个日志条目都有一个级别。每个记录器配置为包括或忽略某些级别。常见配置是指定包含该级别和更高级别的最低级别。例如，如果最低级别是INFO，则会记录INFO、WARN、ERROR和FATAL，但会忽略DEBUG和TRACE。

级别，描述：

LevelTypical Use

Fatal发生了一些不好的事情；应用程序正在关闭

Error失败；应用程序可能继续，也可能不继续。

Warn意外事件；应用程序将继续

Info正常行为，如邮件发送、用户更新配置文件等。

Debug用于调试；已执行查询，用户已验证，会话已过期

Trace用于跟踪调试；开始方法x，结束方法x

还有一个level级别 Off .这是最高级别，不用于设置，所以当日志是使用最低级别的时候，她将禁用日志记录。

[10] 自动重新配置

配置文件在程序启动时自动读取。在长时间运行的进程（如Windows服务或ASP.NET应用程序）中，有时需要临时增加日志级别而不停止应用程序。nlog可以监视日志配置文件，并在每次修改时重新读取它们。要启用此机制，只需将autoreload=“true”参数添加到配置文件中。

请注意，自动重新配置支持包含文件，因此每次更改包含的文件之一时，都会重新加载整个配置。为了使其显式化，自动重新加载不会停止/回收IIS应用程序池。

[11] 故障排除日志记录

有时我们的应用程序不会向日志文件写入任何内容，即使我们假定已经正确配置了日志记录。日志不被写入的原因有很多。最常见的问题是权限问题，通常是在ASP.NET进程中，其中asp net_wp.exe或w3wp.exe进程可能没有对要存储日志的目录的写入权限。

NLOG旨在包含日志记录可能导致的运行时异常。以下设置可以更改此行为和/或重定向这些消息。

<nlog throwexceptions=“true”/>-在配置文件中添加throwexceptions属性会导致nlog停止屏蔽异常并将其传递给调用应用程序。此属性在部署时可用于快速定位任何问题。建议在应用程序正确配置为运行时将throwExceptions设置为“false”，这样任何意外的日志记录问题都不会使应用程序崩溃。

<nlog throwconfigeexceptions=“true”/>-与throwexceptions相同，但用于配置异常。如果未设置（或为空），则这与throwExceptions的值相同。在NLOG 4.3中介绍。默认为空（与throwExceptions的值相同）

<nlog internallogfile=“file.txt”/>-添加internallogfile会导致nlog将其内部调试消息写入指定的文件。这包括日志记录期间可能引发的任何异常。　　注意：只支持少数布局，因为内部日志需要尽可能稳定。

nlog 4.6+：支持的渲染器（不带选项）：${currentdir}，${basedir}，`${tempdir} ``

nlog 4.6+：还支持环境变量：例如：“%mypath%”``

<nlog internallogtoconsole=“false|true”/>–确定是否将内部日志消息发送到控制台。

<nlog internallogtoconsoleerror=“false|true”/>–确定是否将内部日志消息发送到控制台错误输出（stderr）。

<nlog internallogtotrace=“false|true”/>–确定是否将内部日志记录消息发送到System.Diagnostics.trace，这可以在Visual Studio中轻松查看。

[14] 异步处理和装饰目标

nlog提供装饰和复合目标，通过添加以下功能修改其他目标的行为：

asynchronous processing (wrapped target runs in a separate thread)

retry-on-error

load balancing

buffering

filtering

failover (failover)

要在配置文件中定义包装器，只需将目标节点嵌套在另一个目标节点中。您甚至可以包装一个包装目标-深度没有限制。例如，要添加具有“出错时重试”功能的异步日志记录，请将其添加到配置文件中：

由于异步处理是一种常见的场景，因此nlog支持一种速记法，以便在不需要指定显式包装器的情况下为所有目标启用它。您只需在targets元素上设置async=“true”，该元素中的所有目标都将被asyncWrapper目标包装。

[12] 默认包装器

有时我们要求所有目标以相同的方式包装，例如添加缓冲和/或重试。nlog为此提供了<default wrapper/>语法。只需将这个元素放在<targets/>部分，所有目标都将自动用指定的包装器包装。注意，<default wrapper/>只适用于单个的<targets/>部分，您可以有多个部分，这样您就可以定义以类似方式包装的目标组。

在上面的示例中，我们定义了两个缓冲文件目标和三个异步和重试网络目标。

[13] 默认Target参数

与默认包装器类似，nlog提供了<default target parameters/>，使您能够指定目标参数的默认值。例如，如果不希望文件保持打开状态，可以向每个目标添加keepfileopen=“false”，如下例所示：

或者，您可以指定一个适用于<targets/>部分中所有目标的<default target parameters/>。默认参数按类型定义，并在XML文件中定义的实际属性之前应用：

[14] 内容转义

在配置文件中，一些字符需要转义。因为它是XML文件，所以< >应该用&lt；和&gt；转义。这也适用于属性值，如条件:

在布局中，我们需要转义 "}" 和 ":" 因为：

：是值分隔符。

}是布局的结尾

嵌套布局呈现器不需要转义。反斜杠也不需要转义。

${appdomain:format={1\}{0\}} (escape of })

${rot13:inner=${ndc:topFrames=3:separator=x}} (no escaping needed)

${when:when=1 == 1:Inner=Test\: Hello} (escape of :)

[15] 扩展

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

只需在<extensions/>中引用配置中的dll，如下所示。名称不应包括.dll：

从名为“nlog.dll”的nlog 4.0程序集开始，例如“nlog.customtarget.dll”，现在将自动加载。此程序集应与nlog.dll位于同一文件夹中。

以上大致，把整个Nlog的配置讲了一遍，可以自己多按照官方文档来走几下，码字不容易。

参考文档：

All (XML) config options: https://nlog-project.org/config/

Document For Nlog :https://github.com/NLog/NLog/wiki/Configuration-file#troubleshooting-logging

本站仅提供存储服务，所有内容均由用户发布，如发现有害或侵权内容，请点击举报。