LumLog 1.1.0

LumLog

面向生产环境的极简异步文件日志库，实现 Microsoft ILogger 抽象，支持高并发写入、按天滚动、写日志回调扩展。

目标框架： .NET Standard 2.0 · .NET 8.0 · .NET 9.0 · .NET 10.0

特性

• 极简设计：核心代码量少，无反射，依赖轻量
• 跨平台兼容：单 NuGet 包同时支持 .NET Framework 4.6.1+、.NET Core / .NET 5+ 及 .NET 8 / 9 / 10
• 异步高并发：基于 System.Threading.Channels，生产者不阻塞，后台线程串行写盘
• 文件句柄缓存：同一路径复用 StreamWriter，减少 IO 开销
• 按天滚动：日志文件 {BaseDirectory}/log/{directory}/{yyyyMMdd}.log
• Microsoft 抽象：实现 ILogger、ILoggerProvider、ILoggerFactory
• 全局配置：运行时总开关、最低日志级别、手动 Flush
• 写日志回调：独立 Channel 异步执行，可用于 SQL 同步、远程推送；回调出错不影响主日志
• AOT 友好（net8.0 / net9.0 / net10.0）：适合 Native AOT 场景

安装

dotnet add package LumLog

或 NuGet 包管理器：

Install-Package LumLog

框架兼容性

NuGet 包内置四个目标，按消费者项目自动匹配最优版本：

lib/netstandard2.0/LumLog.dll
lib/net8.0/LumLog.dll
lib/net9.0/LumLog.dll
lib/net10.0/LumLog.dll

关于 AOT

netstandard2.0 是 API 契约，不是运行时，不能作为 AOT 发布目标。AOT 项目引用 LumLog 时，NuGet 会自动选用 net8.0 / net9.0 / net10.0 版本参与原生编译。LumLog 无反射，在对应 TFM 下可正常 AOT 发布。

快速开始

方式一：配合 DI / Host（推荐）

using Lum.Log;
using Microsoft.Extensions.Logging;

// Program.cs / Startup.cs
builder.Logging.AddProvider(new LogProvider("myApp"));

// 业务代码 — 使用标准 ILogger 抽象
public class MyService
{
    private readonly ILogger<MyService> _logger;

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

    public void Run() => _logger.LogInformation("服务启动");
}

方式二：独立使用 LogFactory（不依赖 DI）

using Lum.Log;
using Microsoft.Extensions.Logging;

using (var factory = new LogFactory("myApp"))
{
    ILogger logger = factory.CreateLogger("MyClass");
    logger.LogWarning("独立运行");
}

方式三：.NET Framework 示例

using Lum.Log;
using Microsoft.Extensions.Logging;

var factory = new LogFactory("myApp");
ILogger logger = factory.CreateLogger("MyClass");
logger.LogError("发生错误");
LogHelper.Flush(); // 应用退出前手动刷新

方式四：Native AOT（.NET 8 / 9 / 10）

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <PublishAot>true</PublishAot>
</PropertyGroup>

using Lum.Log;
using Microsoft.Extensions.Logging;

var factory = new LogFactory("myApp");
ILogger logger = factory.CreateLogger("MyApp");
logger.LogInformation("AOT 发布");
LogHelper.Flush();

日志路径与格式

单条日志格式：

[2026-06-05 14:30:00.1234] [Information] (MyService) 服务启动

配置

以下均为 LogHelper 上的全局静态配置，对所有 Logger 实例生效。

using Lum.Log;
using Microsoft.Extensions.Logging;

// 全局总开关（false = 不写文件、不触发回调，IsEnabled 恒为 false）
LogHelper.Enabled = true;

// 最低日志级别（低于此级别的日志被忽略）
// Debug 编译默认 Trace；Release 编译默认 Information
LogHelper.MinLevel = LogLevel.Warning;

// 手动刷新缓冲区（不关闭日志引擎，适合退出前或关键操作后）
LogHelper.Flush();

Enabled 与 MinLevel 的关系：

• Enabled = false → 所有级别均不记录
• Enabled = true → 由 MinLevel 决定过滤，如设为 Warning 则 Information 及以下被忽略

进程正常退出时会自动 flush 并关闭日志引擎。

写日志回调

回调是 LumLog 的扩展能力，不在 ILogger 标准接口上。在应用启动时注册一次，即可监听所有经 LumLog 写出的日志。

注意

• 回调只覆盖 LumLog 自身的输出；若 Host 中还注册了 Console、Debug 等其他 Provider，那些日志不会进入回调
• 回调注册在 LogHelper 静态 API 上，与业务层使用的 ILogger 抽象无关

using Lum.Log;

LogWriteCallback myCallback = (message, logLevel, category, logDirectory, logFileName) =>
{
    // message       — 完整格式化日志行
    // logLevel      — 如 "Information"
    // category      — 如 "MyService"
    // logDirectory  — 目录，含末尾 \，如 D:\app\log\myApp\
    // logFileName   — 如 20260605.log

    // 示例：写入数据库 / 推送远程
    // var fullPath = logDirectory + logFileName;
    // SaveToDb(message);
};

LogHelper.RegisterWriteCallback(myCallback);

// 取消注册
LogHelper.UnregisterWriteCallback(myCallback);

与 ILogger 配合使用：

builder.Logging.AddProvider(new LogProvider("myApp"));
LogHelper.RegisterWriteCallback(myCallback);   // 启动时注册

// 业务层只用 ILogger，无需引用 LumLog
logger.LogInformation("hello");  // 写文件 + 触发回调

回调在独立后台线程执行；若回调抛出异常，错误信息会写入主日志，不影响文件写入。

禁用日志

// 方式一：全局关闭（推荐，可随时恢复）
LogHelper.Enabled = false;

// 方式二：使用空实现（IsEnabled 恒为 false，零开销）
ILogger logger = LogHelper.InvalidLog;

API 概览

LogFactory.AddProvider 不支持添加外部 Provider；多 Provider 场景请使用 LogProvider + DI。

依赖

net8.0 / net9.0 / net10.0 目标使用对应运行时内置实现，无额外传递依赖。

要求

许可证

MIT License — 见 LICENSE.txt

链接

• GitHub: https://github.com/LdotJdot/LumLog
• NuGet: https://www.nuget.org/packages/LumLog