聆途笔记

C# NLog配置教程：从入门到精通

NLog是.NET平台下功能强大且高性能的日志记录框架，被广泛应用于各种规模的应用程序中。本教程将详细介绍NLog的配置方法，帮助您快速掌握这一强大的日志工具。

一、NLog基础安装

1.1 安装NuGet包

在项目中通过NuGet安装NLog：

dotnet add package NLog
dotnet add package NLog.Extensions.Logging  # 针对ASP.NET Core项目

1.2 基本使用示例

using NLog;
using NLog.Config;
using NLog.Targets;

// 基础配置
var config = new LoggingConfiguration();
var consoleTarget = new ConsoleTarget("console");
config.AddTarget(consoleTarget);
config.AddRule(LogLevel.Info, LogLevel.Fatal, consoleTarget);

LogManager.Configuration = config;
var logger = LogManager.GetCurrentClassLogger();

logger.Info("Hello, NLog!");

二、NLog配置文件详解

2.1 配置文件位置与命名

NLog默认会自动加载以下位置的配置文件：

  • NLog.config (应用程序目录)
  • NLog.dll.nlog (NLog程序集目录)

2.2 完整配置文件示例

<?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"
      autoReload="true"
      throwExceptions="false"
      internalLogLevel="Off"
      internalLogFile="c:\temp\nlog-internal.log">

  <!-- 定义变量 -->
  <variable name="logDirectory" value="${basedir}/logs"/>
  <variable name="logFormat" value="${longdate}|${level:uppercase=true}|${logger}|${message}${exception:format=tostring}"/>

  <!-- 定义目标 -->
  <targets async="true">
    <!-- 控制台输出 -->
    <target name="console" xsi:type="ColoredConsole"
            layout="${logFormat}"
            errorStream="true"/>

    <!-- 文件输出 -->
    <target name="file" xsi:type="File"
            fileName="${logDirectory}/${shortdate}.log"
            layout="${logFormat}"
            maxArchiveFiles="30"
            archiveAboveSize="10485760"
            archiveEvery="Day"/>

    <!-- 数据库输出 -->
    <target name="database" xsi:type="Database">
      <connectionString>Server=.;Database=Logs;Integrated Security=SSPI;</connectionString>
      <commandText>
        INSERT INTO Logs (TimeStamp, Level, Logger, Message, Exception)
        VALUES (@timeStamp, @level, @logger, @message, @exception);
      </commandText>
      <parameter name="@timeStamp" layout="${date:format=yyyy-MM-dd HH\:mm\:ss.fff}"/>
      <parameter name="@level" layout="${level}"/>
      <parameter name="@logger" layout="${logger}"/>
      <parameter name="@message" layout="${message}"/>
      <parameter name="@exception" layout="${exception:tostring}"/>
    </target>
  </targets>

  <!-- 定义规则 -->
  <rules>
    <logger name="Microsoft.*" minlevel="Info" writeTo="file" final="true"/>
    <logger name="*" minlevel="Debug" writeTo="console,file,database"/>
  </rules>
</nlog>

三、常用Targets配置详解

3.1 文件目标(File Target)

<target name="logfile" xsi:type="File"
        fileName="${logDirectory}/${shortdate}.log"
        layout="${longdate}|${level}|${logger}|${message}"
        maxArchiveFiles="30"
        archiveAboveSize="10485760"
        archiveEvery="Day"
        concurrentWrites="true"
        keepFileOpen="true"
        encoding="utf-8"/>

关键参数说明：

  • maxArchiveFiles：最大归档文件数
  • archiveAboveSize：文件超过此大小(字节)时归档
  • archiveEvery：按时间归档的频率
  • concurrentWrites：允许多线程并发写入
  • keepFileOpen：保持文件打开状态提升性能

3.2 控制台目标(Console Target)

<target name="console" xsi:type="ColoredConsole"
        layout="${logFormat}"
        errorStream="false"
        useDefaultRowHighlightingRules="true">
  <highlight-row condition="level == LogLevel.Error" foregroundColor="Red"/>
  <highlight-row condition="level == LogLevel.Warn" foregroundColor="Yellow"/>
</target>

3.3 数据库目标(Database Target)

<target name="database" xsi:type="Database">
  <connectionString>${configsetting:item=ConnectionStrings.LogDb}</connectionString>
  <commandText>
    INSERT INTO Logs (Application, TimeStamp, Level, Message, Exception)
    VALUES (@Application, @TimeStamp, @Level, @Message, @Exception)
  </commandText>
  <parameter name="@Application" layout="${appsetting:item=AppName}"/>
  <parameter name="@TimeStamp" layout="${date:format=yyyy-MM-dd HH\:mm\:ss.fff}"/>
  <parameter name="@Level" layout="${level}"/>
  <parameter name="@Message" layout="${message}"/>
  <parameter name="@Exception" layout="${exception:format=tostring}"/>
</target>

四、高级布局(Layout)配置

4.1 常用布局渲染器

渲染器说明示例
${longdate}完整日期时间2023-08-15 14:30:45.1234
${level}日志级别INFO, ERROR
${logger}记录器名称Namespace.Class
${message}日志消息用户登录成功
${exception}异常信息System.NullReferenceException
${all-event-properties}所有日志事件属性
${callsite}调用位置(类和方法)MyApp.Controllers.Home.Index
${machinename}机器名DEV-SERVER-01
${processid}进程ID1234
${threadid}线程ID5

4.2 自定义布局示例

<layout>${date:format=yyyy-MM-dd HH\:mm\:ss} [${level:uppercase=true}] ${logger:shortName=true} - ${message} ${exception:format=tostring}</layout>

五、日志过滤规则(Rules)

5.1 基本规则配置

<rules>
  <!-- 特定命名空间的日志单独处理 -->
  <logger name="Microsoft.*" minlevel="Warn" writeTo="file" final="true"/>

  <!-- 特定类的日志单独处理 -->
  <logger name="MyApp.DataAccess.*" minlevel="Debug" writeTo="database"/>

  <!-- 默认规则 -->
  <logger name="*" minlevel="Info" writeTo="console,file"/>
</rules>

5.2 规则属性说明

属性说明
name记录器名称模式，支持通配符(*)
minlevel最低日志级别
maxlevel最高日志级别
level精确匹配的日志级别
levels匹配多个日志级别(逗号分隔)
writeTo目标名称(多个目标用逗号分隔)
final设为true时，匹配此规则后不再处理后续规则
enabled是否启用此规则

六、ASP.NET Core集成

6.1 基本集成配置

var builder = WebApplication.CreateBuilder(args);

// 添加NLog服务
builder.Logging.ClearProviders();
builder.Host.UseNLog();

var app = builder.Build();

6.2 在控制器中使用

public class HomeController : Controller
{
    private readonly ILogger<HomeController> _logger;

    public HomeController(ILogger<HomeController> logger)
    {
        _logger = logger;
    }

    public IActionResult Index()
    {
        _logger.LogInformation("访问首页");
        _logger.LogWarning("示例警告消息");
        return View();
    }
}

6.3 配置appsettings.json

{
  "NLog": {
    "throwConfigExceptions": true,
    "extensions": [
      { "assembly": "NLog.Web.AspNetCore" }
    ],
    "variables": {
      "logDirectory": "C:/Logs/${appsetting:item=AppName}"
    }
  }
}

七、高级功能配置

7.1 异步日志处理

<targets async="true">
  <target name="asyncFile" xsi:type="AsyncWrapper" queueLimit="10000" overflowAction="Discard">
    <target xsi:type="File" fileName="${logDirectory}/async.log" />
  </target>
</targets>

7.2 日志缓冲

<target name="buffered" xsi:type="BufferingWrapper" bufferSize="100">
  <target xsi:type="File" fileName="${logDirectory}/buffered.log" />
</target>

7.3 条件过滤

<target name="conditional" xsi:type="FilteringWrapper" condition="length(message) > 100">
  <target xsi:type="File" fileName="${logDirectory}/long-messages.log" />
</target>

八、性能优化技巧

  1. 启用异步写入：<targets async="true">
  2. 保持文件打开：keepFileOpen="true"
  3. 限制归档数量：maxArchiveFiles="30"
  4. 使用缓冲：BufferingWrapper
  5. 避免过度日志：合理设置日志级别
  6. 减少布局复杂度：简化layout配置

九、常见问题解决

9.1 日志文件未生成

  • 检查文件路径权限
  • 确认NLog.config文件位置正确
  • 启用内部日志诊断问题：
  <nlog internalLogLevel="Trace" internalLogFile="c:\temp\nlog-internal.log">

9.2 性能问题

  • 启用异步写入
  • 减少不必要的日志目标
  • 提高最小日志级别

9.3 配置不生效

  • 确认配置文件名正确
  • 检查配置XML格式是否正确
  • 确认没有代码中覆盖配置

十、最佳实践建议

  1. 环境分离：为开发、测试和生产环境配置不同的日志级别和目标
  2. 结构化日志：使用${event-properties}记录结构化数据
  3. 敏感信息：避免在日志中记录密码等敏感信息
  4. 日志轮转：配置合理的归档策略防止磁盘占满
  5. 监控配置：对关键应用配置日志监控告警

十一、NLog扩展功能

11.1 自定义Target

[Target("MyCustomTarget")]
public class MyCustomTarget : TargetWithLayout
{
    protected override void Write(LogEventInfo logEvent)
    {
        string logMessage = RenderLogEvent(Layout, logEvent);
        // 自定义处理逻辑
    }
}

注册自定义Target：

<extensions>
  <add assembly="MyAssembly"/>
</extensions>

11.2 自定义LayoutRenderer

[LayoutRenderer("custom-value")]
public class CustomLayoutRenderer : LayoutRenderer
{
    protected override void Append(StringBuilder builder, LogEventInfo logEvent)
    {
        builder.Append(DateTime.Now.Ticks);
    }
}

十二、总结

NLog作为.NET平台下成熟的日志框架，提供了丰富的功能和灵活的配置选项。通过本教程的学习，您应该能够：

  1. 理解NLog的基本概念和架构
  2. 熟练配置各种日志目标和规则
  3. 掌握NLog与ASP.NET Core的集成方法
  4. 应用高级功能优化日志系统
  5. 解决常见的配置和使用问题

在实际项目中，建议根据应用规模和需求选择合适的配置方案，并定期审查日志策略以确保其持续满足运维和开发需求。

进一步学习资源：

a_a_a

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注