NLog 教程

内容

• 安装NLog
• 配置NLog输出的Targets
• 写入日志信息
  • 日志等级
  • 布局和布局渲染器
  • 日志最佳实践
• 封装器
• 故障排除

安装NLog

ASP.NET Core 用户最好先 follow Getting started with ASP.NET Core

NLog可以在NuGet中下载.

如果仅仅安装 NLog.Config 包，会一并安装 NLog 和 NLog.Schema 两个包，这将使得启动配置和智能感知。

使用 GUI 或 在程序包管理控制台中使用以下命令

Install-Package NLog.Config

好了，你现在可以编译和运行你自己的应用了，它能使用NLog的功能了.

配置NLog输出的Targets

如果配置了一个（或者更多）NLog targets , NLog 仅会产出对应项.

NLog 可以使用一个 NLog.config 的 XML 配置文件去配置你的应用程序（文件的属性需修改为：始终复制），下面是一个简单 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">

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

注: 其中 targets 表示写入的方式，上方 logfile 表示使用txt文件的方式记录，logconsole 表示在控制台中记录（在控制台中直接输出），rules 表示写入方式对应的规则

也可以使用代码的方式进行配置，例如如下的代码：

var config = new NLog.Config.LoggingConfiguration();

var logfile = new NLog.Targets.FileTarget() { FileName = "file.txt", Name = "logfile" };
var logconsole = new NLog.Targets.ConsoleTarget() { Name = "logconsole" };

config.LoggingRules.Add(new NLog.Config.LoggingRule("*", LogLevel.Info, logconsole));
config.LoggingRules.Add(new NLog.Config.LoggingRule("*", LogLevel.Debug, logfile));

NLog.LogManager.Configuration = config;

也可以参考 Configuration File 或者 Configuration API

详细信息: Targets

写入日志信息

如何获取记录器并向日志记录器写入消息的示例:

var logger = NLog.LogManager.GetCurrentClassLogger();
logger.Info("Hello World");

如果已经正确的配置了NLog targets，上面的代码会输出信息到配置的targets中.

logger 有一个name，它可以在logging-rules(参见上面的配置示例中的name="*")用于重定向到需要的targets。

当使用 NLog.LogManager.GetCurrentClassLogger() 时，它会创建一个名字为调用类名称（包括命名空间）的 logger .还可以通过使用指定一个显式名称. NLog.LogManager.GetLogger("MyLogger").

logger 可以使用不同的 LogLevels ，它可以在logging-rules（参见上面的配置示例中的 minLevel）配置，用户有相关的信息被重定向到 targets 中:

logger 没有绑定到特定的目标。写入到一个logger 的消息可以根据logging-rules中配置，从而可以写入到多个目标中。保持这种分离可以让你在代码中保留日志记录，并且可以通过在一个地方更新配置来轻松地更改日志的编写方式和位置。还可以查看过滤日志消息。

日志等级

每一个记录的信息都有一个对应的日志等级，表示这个记录信息的重要程度或详细程度。NLog 可以根据日志消息的名称和日志级别来路由日志消息。

NLog 支持以下的 记录日志等级：

• Trace - 非常详细的日志，包含最详尽的信息，例如协议的有效载荷. 该日志等级通常仅在开发过程中被使用；
• Debug - 调试信息，详尽信息次于 Trace ，在生产环境中通常不启用；
• Info - 信息消息， 通常在生产环境中通常启用；
• Warn - 警告信息，通常用于非关键问题，这些问题可以恢复，或者是暂时的故障；
• Error - 错误信息 - 多数情况下记录Exceptions（异常）信息；
• Fatal - 非常严重的错误！

public class MyClass
{
  private static NLog.Logger logger = NLog.LogManager.GetCurrentClassLogger();

  public void MyMethod1()
  {
    logger.Trace("Sample trace message");
    logger.Debug("Sample debug message");
    logger.Info("Sample informational message");
    logger.Warn("Sample warning message");
    logger.Error("Sample error message");
    logger.Fatal("Sample fatal error message");

    // alternatively you can call the Log() method
    // and pass log level as the parameter.
    logger.Log(LogLevel.Info, "Sample informational message");
  }
}

布局和布局渲染器

布局和布局渲染器 可以配置日志消息如何写入NLog targets.

下面展示了一个大多数 NLog targets 使用的简单布局方式 SimpleLayout :

<target name="logfile" xsi:type="File" fileName="file.txt" layout="${longdate}|${level:uppercase=true}|${logger}|${message}" />

也可以进行相应的配置，以获取更详尽的信息：

<target name="logfile" xsi:type="File" fileName="file.txt" layout="${longdate}|${level:uppercase=true}|${logger}|${threadid}|${message}|${exception:format=tostring}" />

更详尽信息，参考 Layout Renderers

你也可以使用更复杂的布局，而不是简单的布局:

• CsvLayout
• JsonLayout

更详尽信息，参考: Layouts

日志最佳实践

1. 每个类中，Logger 应该被设置成一个静态变量
   每创建一个 Logger 都会有一定的性能损耗，因为它必须获取锁和分配对象
   因此建议像这样创建logger:

namespace MyNamespace
{
  public class MyClass
  {
    private static NLog.Logger logger = NLog.LogManager.GetCurrentClassLogger();
  }
}

2. Logger 应该处理字符串格式化
   避免预先执行字符串分配或字符串连接，而是让日志记录器执行格式化。这将允许NLog推迟格式化并减少开销。

因此，建议您这样执行日志:

logger.Info("Hello {0}", "Earth");

3. Logger 应该记录异常
   避免将异常作为格式化参数，而是将其显式地作为第一个参数提供。这将帮助NLog目标提供更好的日志记录。

try
{
}
catch (Exception ex)
{
    logger.Error(ex, "Something bad happened");
}

4. 从 NLog.config XML配置文件中验证配置
   默认情况下，NLog 允许记录所有异常，因此，日志记录的问题不会导致应用程序中断。但是为更多的应用程序记录日志是至关重要的，所以如果 NLog 配置文件的实例错误，那将是致命的.

增加 throwConfigExceptions="true" 会使 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"
      throwConfigExceptions="true">
</nlog>

类似的有 throwExceptions="true", 但它不能在生产环境中使用，因为它会对应用程序造成破坏. 它被设计用在单元测试、本地故障排除中.详见Troubleshooting Configuration

5. Remember to Flush
   当应用停止运行时，NLog 默认会自动尝试刷新. Microsoft Windows 给.Net应用程序在被终止前执行关机(通常是2秒)的时间。如果一个 NLog配置了需要网络传输的 NLog Tagets （Http、Mail、Tcp）运行在Linux/Windows，那么执行一个手动的 Flush/Shutdown 是一个明智之举.

NLog.LogManager.Shutdown(); // 刷新并关闭内部线程和计时器。

运行在Mono/Linux 的 .NET 应用在进入应用程序关闭阶段前，必需去停止线程和计时器. 如果未执行完成会导致未处理的异常和分割错误，以及其他不可预知的行为。

封装器

NLog 支持特殊类型的 targets ，这些类自己本身不做任何日志记录，但是会修改其它 loggers 的行为. 这些loggers被称为封装器. 一般常用的是:

• AsyncWrapper - 提供异步方式缓冲执行目标写入，可以提高性能；
• BufferingWrapper - 简单批处理日志信息. 可能仅在某些日志事件发生时才发送批处理（例如 异常信息）；
• FallbackGroup - 提供错误回滚;
• RetryingWrapper - 提供错误重试操作;

详见 : Target Wrappers

AsyncWrapper 提供一个便捷的快捷设置方式，在配置文件中添加 async="true" 即可：

<?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 async="true">
        <target name="logfile" xsi:type="File" fileName="file.txt" />
    </targets>

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

这样设置之后，所有写入文件的日志将以异步的方式，可以提高调用线程的响应能力。

参考资料:

• NLog Tutorial
• NLog类库使用探索——详解配置