LuBan.Logging 2026.11.9.1

English | 中文

LuBan.Logging

作者: yswenli | 联系邮箱: yswenli@outlook.com | 代码仓库: https://github.com/yswenli/luban-framework

基于 Microsoft.Extensions.Logging 的文件日志 Provider，开箱即用，100MB/跨天自动滚动。

Related Projects: LuBan.Framework | LuBan.Common | LuBan.DI | LuBan.Orm | LuBan.Web.Core

为什么需要它？

• 不想依赖 log4net 的 XML 配置？
• 想要 Microsoft.Extensions.Logging 的标准 ILogger 抽象？
• 需要日志文件自动按大小或日期滚动，不用手动清理？
• 希望通过 DI 单例方式使用日志，而不是静态调用？

LuBan.Logging 提供自研文件日志 Provider，深度集成 Microsoft.Extensions.Logging，与 LuBan.Common.Logger 静态门面无缝衔接。

技术栈

安装

dotnet add package LuBan.Logging

快速预览

ASP.NET Core Web 项目

// Program.cs 或 ServiceHost 中
// 注册文件日志 Provider——内部会先调用 builder.ClearProviders()，
// 清掉 WebApplication.CreateBuilder 默认注册的 Console/Debug/EventSource，
// 框架自身日志（Microsoft.Hosting.Lifetime 等）不再输出到控制台
builder.Logging.AddLuBanFileLogger();

// 在 Build 之后注入到 static Logger
Logger.SetLogger(DiContainer.Instance.GetRequiredService<ILoggerFactory>());
Logger.SetSerializer(LuBanLoggingServiceExtensions.CreateLuBanSerializer());

控制台/Agent 项目

var services = new ServiceCollection();
services.AddLogging(builder => builder.AddLuBanFileLogger());

var sp = services.BuildServiceProvider();
Logger.SetLogger(sp.GetRequiredService<ILoggerFactory>());
Logger.SetSerializer(LuBanLoggingServiceExtensions.CreateLuBanSerializer());

通过 DI 单例使用

public class MyService
{
    private readonly ILogger<MyService> _logger;

    // ILuBanLogger 需先显式注册（见下方「DI 集成」），类型扫描不会注册该接口
    public MyService(ILuBanLogger luBanLogger)
    {
        _logger = luBanLogger.CreateLogger<MyService>();
    }

    public void DoWork()
    {
        _logger.LogInformation("工作开始");
        // ...
        _logger.LogInformation("工作完成");
    }
}

功能特性

文件日志 Provider

STJ 序列化器

日志内容使用 System.Text.Json 序列化，CreateLuBanSerializer() 直接复用 LuBan.Common 的 SerializeUtil.Serialize(indented:false, defalutVal:false, nullValue:true, camelCase:true)，因此输出为：

• WriteIndented = false — 单行 JSON，不缩进
• PropertyNamingPolicy = CamelCase — 驼峰命名
• DefaultIgnoreCondition = WhenWritingDefault — 忽略默认值（defalutVal:false 直接取该策略，null 与默认值都不写出，此组合下 nullValue:true 不起作用）
• 自定义转换器：
  • DateTimeJsonConverter — 日期格式 yyyy-MM-dd HH:mm:ss.fff
  • ExceptionJsonConverter — 异常对象（ExceptionType/Message/StackTrace/InnerException/Source，属性名由转换器写死，不随 camelCase 策略）
  • AssemblyJsonConverter — 程序集信息
  • MemberInfoJsonConverter — 成员信息

DI 集成

LuBanLogger 是 ILuBanLogger 的实现，并实现 ISingleton 标记接口。注意 LuBan.DI 的 AutoInjectAllCustomerServices() 只按实现类注册（RegisterService 不注册接口），因此扫描后可解析 LuBanLogger，但解析 ILuBanLogger 需要显式注册一次：

public interface ILuBanLogger
{
    ILogger CreateLogger(string categoryName);
    ILogger<T> CreateLogger<T>();
}

// 显式注册接口（类型扫描不会做这一步）
services.AddSingleton<ILuBanLogger, LuBanLogger>();

注意 Provider 只认 5 个固定 category（loginfo/logdebug/logwarn/logerror/logcall）：CreateLogger<T>() 得到的是类名 category，FileLoggerProvider.Write 找不到文件映射会直接丢弃，不会落盘。需要写文件请走 Logger.Info() 等静态门面。

配置选项

所有配置项均有默认值，无需配置即可使用。Provider 注册时会自动绑定配置节 LuBanLoggingOptions（IConfiguration 已注册时），configure 回调在其后执行、可覆盖配置节的值。

builder.Logging.AddLuBanFileLogger(options =>
{
    options.Enabled = true;                 // 总开关（默认 true），false 时不写任何文件
    options.Directory = "logs";             // 日志目录（默认 logs）
    options.MaxFileSizeMB = 100;            // 单文件最大大小 MB（默认 100）
    options.MaxRollBackups = 5;             // 最大备份数（默认 5）
    options.EnableConsole = false;          // Logger 是否同时输出到控制台（默认 false）
    options.EnableDb = false;               // 是否写入数据库（默认 false，供 LuBan.Orm 的日志收集使用）
    options.Categories["logdebug"] = false; // 按 category 单独开关（默认 loginfo/logdebug/logwarn/logerror/logcall 全开）
    options.LogLimit = new LogLimitConfig   // 数据库日志容量与过期（EnableDb 时生效）
    {
        ApiLogMaxSize = 10240,              // API 日志最大条数（默认 10240）
        ApiLogExpiredSeconds = 604800,      // API 日志过期秒数（默认 604800，即 7 天）
        ErrorLogMaxSize = 1024,             // 错误日志最大条数（默认 1024）
        ErrorLogExpiredSeconds = 604800     // 错误日志过期秒数（默认 604800）
    };
});

与 LuBan.Common.Logger 的关系

LuBan.Common.Logger 是静态门面类，提供 Logger.Info()、Logger.Error() 等静态方法。它内部委托 5 个 ILogger 实例（按 category name 区分），通过 SetLogger(ILoggerFactory) 在启动时注入。

LuBan.Logging 负责创建 ILoggerFactory 并注册文件日志 Provider，然后在启动时调用 Logger.SetLogger() 和 Logger.SetSerializer() 完成注入。

LuBan.Logging（Provider 注册 + 序列化器）
       ↓ SetLogger/SetSerializer
LuBan.Common.Logger（静态门面，按 category 分发到 5 个 ILogger）
       ↓ ILogger.LogInformation
FileLoggerProvider → RollingFileWriter → logs/info.txt

日志文件输出示例

logs/info.txt（WriteIndented = false，单行输出）：

{"created":"2026-07-31 14:30:00.000","serviceName":"MyService","level":0,"description":"订单模块\t订单 10086 创建成功"}

logs/error.txt：

{"created":"2026-07-31 14:30:01.000","serviceName":"MyService","level":1,"description":"支付模块","exception":{"ExceptionType":"System.Net.Http.HttpRequestException","Message":"连接超时","StackTrace":"   at System.Net.Http...","Source":"MyService"}}

许可证

Copyright (c) yswenli.

Licensed under the Apache License 2.0.