MiniLog.Extensions.Logging 1.0.1

MiniLog

轻量、高性能的 .NET 日志组件库，零外部依赖。API 形态借鉴 log4net / NLog 的派发模型（Logger → Appender → Layout），但在底层采用结构体日志条目、零分配渲染与源生成器，定位为「现代、低 GC 压力、可替代 MS Logging 的高性能日志框架」。

核心技术亮点：

• 零分配渲染 —— LogEntry 值语义结构体 + ReusableDelegateWriter + ValueStringBuilder（栈缓冲 / ArrayPool），热路径零 GC

• 零装箱派发 —— 源生成器经 ILogArgumentBag 泛型参数袋把结构化参数穿过整条派发链，启用路径不装箱

• ANSI 彩色分级控制台 —— 可选、EnableColors 默认关、跨平台、不依赖 Console 全局颜色状态

• 源生成器双后端 —— [Log]（注入 ILog 字段）+ [LoggerMessage]（强类型零装箱），一份声明通吃 MiniLog 与 Microsoft.Extensions.Logging

• 8 种 Appender + 8 种过滤器 + 11×7 文件/目录滚动

版本: 1.0.0（GA）| 目标框架: .NET 8.0 / .NET 10.0 | 许可证: MIT

状态：首个正式稳定版（GA）。可从源码构建或引用本地包使用；包名 MiniLog 经核查在 nuget.org 可用、无冲突。

源码仓库：https://gitee.com/netcasewqs/MiniLog

🚀 快速导航

目录

• 开发背景

• 一、特性一览

• 二、快速开始

• 三、与其他开源日志库对比

• 四、配置

• 布局模式校验器（编译期 LLG 诊断）

• 编译期诊断码总表（LLG0001–LLG0015）

• 五、Appenders 输出目标

• 六、性能定位

• 七、文档导航

• 八、许可证

一、特性一览

二、快速开始

2.1 安装

MiniLog 已发布到 NuGet，直接引用包即可。源生成器 MiniLog.Generators（含 [Log] / [LoggerMessage] 生成与布局模式校验分析器）随包自动以 Analyzer 形式引入，无需单独安装。

# 核心库（.NET 8.0 / .NET 10.0 双目标框架）
dotnet add package MiniLog

# 可选：接入 ASP.NET Core / Microsoft.Extensions.Logging 时再装此包
dotnet add package MiniLog.Extensions.Logging

要求：.NET 8.0 或 .NET 10.0 SDK。 包 ID：MiniLog（核心库）、MiniLog.Extensions.Logging（MEL 适配器）。两者均为 MIT、零外部依赖。

尚未发布或本地开发 / 贡献时，可用源码引用或本地生成包：

# 方式 A：项目引用（含源生成器，自动以 Analyzer 引入）
dotnet add reference ../src/MiniLog/MiniLog.csproj

# 方式 B：本地生成 NuGet 包后引用
dotnet pack src/MiniLog/MiniLog.csproj -c Release   # 产物 bin/Release/MiniLog.1.0.0.nupkg

2.2 静态门面（最简，5 行开始记录）

using MiniLog;

// 程序启动时调用一次：默认查找 log.config.xml，缺失时按 xml→json→ini 自动探测同名配置，
// 均无则回退到 Logs/Log.txt
LogManager.Initialize();

var log = LogManager.GetLogger<Program>();   // Logger 名默认取类型简单名 "Program"
log.Info("应用启动");
log.Warn("磁盘剩余空间偏低");

// 程序退出前调用一次，确保异步 Appender 缓冲落盘
LogManager.Shutdown();

一个完整的控制台最小示例（Program.cs）：

using MiniLog;

LogManager.Initialize();              // 读取 log.config.xml（或同目录 xml/json/ini）
try
{
    var log = LogManager.GetLogger<Program>();
    log.Info("应用启动");
    log.Error("出错了", new Exception("演示异常"));
}
finally
{
    LogManager.Shutdown();            // 优雅关闭，刷新异步文件缓冲
}

2.3 源生成器 [Log]（Lombok 风格，推荐）

[Log]                                   // 编译期注入：private static readonly ILog log;
public partial class OrderService       // 默认字段名 log；默认 Logger 名 = 简单类名 "OrderService"
{
    public void Process(int id) => log.Info("处理订单 " + id);
}

// 覆盖注入的 Logger 名（默认用类的简单名，不含命名空间）
[Log(Name = "MyApp.Order")]
public partial class OrderService2 { /* ... */ }

// 逐类覆盖默认字段名（库默认已是 log，此处演示可改）
[Log(FieldName = "Logger")]
public partial class OrderService3 { /* ... */ }

默认注入字段名为 log（库新建无历史包袱，已从 Log 改为小写）；可用 [Log(FieldName="...")] 逐类覆盖。[Log(Name="...")] 可覆盖注入的 Logger 名，[LoggerMessage] 同样支持。

2.4 源生成器 [LoggerMessage]（强类型、零装箱）

[LoggerMessage] 标记 partial 方法，生成器为其补全实现：入口先判定级别 IsXxxEnabled，级别关闭时零分配直接返回；热路径参数经结构化参数袋零装箱直写，兼顾性能与强类型。

[Log]                                       // 注入 log 字段；本类 [LoggerMessage] 方法自动复用它
public partial class OrderService
{
    // 字段模式：无 ILog 首参，生成的实现直接使用类的 log 字段
    [LoggerMessage(LogLevel.Info, "处理订单 {Id} 金额 {Amount}")]
    public partial void LogOrderProcessed(int id, decimal amount);

    // 显式 ILog 首参模式：按传入的 ILog 派发（可用于 MEL 的 ILogger）
    [LoggerMessage(LogLevel.Error, "保存失败 {Id}")]
    public partial void LogSaveFailed(ILog log, int id);
}

// 调用处（与手写日志等价，但无装箱、带级别短路）
var svc = new OrderService();
svc.LogOrderProcessed(1001, 29.9m);

级别可省略，由方法名推断（LogInfo/LogWarn/LogError…）；也可 [LoggerMessage(LogLevel.Warn, "...")] 显式指定。[LoggerMessage] 既可单独使用（生成器自动注入 log 字段），也可与 [Log] 同用（复用已注入字段）。

2.5 配置文件 + Fluent Builder

var mgr = LogManager.CreateLogManager(b => b
    .UseConsoleAppender()
    .UseFileAppender("file", new FileAppenderOptions
    {
        FileDirectory = "Logs", FileName = "app", Extension = ".log",
        RollingMode = FileRollingMode.DailyAndSize, ExpiredDays = 30,
    })
    .UseRoot(LogLevel.Warn, "console")
    .UseLogger("MyApp.Data", LogLevel.Info, "console", "file"));
LogManager.SetLogManager(mgr);

更多用法（ILog 接口速查、结构化日志、彩色控制台、MEL 集成、源生成器）见 MiniLog 使用手册。

2.6 从源码构建与测试

仓库无 .sln 解决方案文件，直接按项目构建（目标 .NET 8.0 / .NET 10.0 双 TFM）：

dotnet build src/MiniLog/MiniLog.csproj -c Release
dotnet build src/MiniLog.Generators/MiniLog.Generators.csproj -c Release
dotnet test  test/MiniLog.Tests/MiniLog.Tests.csproj -c Release
dotnet test  test/MiniLog.Extensions.Logging.Tests/MiniLog.Extensions.Logging.Tests.csproj -c Release
dotnet pack  src/MiniLog/MiniLog.csproj -c Release   # 产出 NuGet 包

双门禁（提交门槛）：MiniLog / MiniLog.Generators 开启 -warnaserror，Debug 与 Release 下 net8.0 / net10.0 必须 0 警告 0 错误；两套测试全绿才算闭环。贡献前请本地跑齐上述命令。

三、与其他开源日志库对比

MiniLog 与 log4net / NLog / Serilog / MS.Extensions.Logging 定位有本质差异：它保留传统派发模型（Logger → Appender → Layout），但在底层用零分配渲染与源生成器实现数量级性能领先。

3.1 能力矩阵（主流 5 库）

3.2 性能定位

固定消息：MiniLog(26.8µs) << MS(102µs) << Serilog(869µs) << NLog(16.5ms) ≈ log4net(17.6ms)
异步文件：MiniLog(98µs) << NLog(1.6ms) ≈ MS(1.8ms) << log4net(2.4ms) << Serilog(9.8ms)
级别关闭：MiniLog源生成(7.5µs/0B) < MS LoggerMessage(11.5µs/0B) << MS 原生(仍分配 640KB)

• vs log4net / NLog：传统派发模型但非文件模式快 600×+，零分配，现代 API。

• vs Serilog：Serilog 结构化日志与 Sink 生态最丰富；MiniLog 在性能与分配上显著占优。

• vs MS.Extensions.Logging：真实负载下更快且零分配语义打平；MiniLog 通过 MiniLog.Extensions.Logging 直接作为 MS Provider 接入，兼得两者。

完整能力矩阵、性能三段排名与选型建议见 使用手册·对比章节。

四、配置

MiniLog 支持 XML / JSON / INI 三种格式 + Fluent Builder。默认查找 AppDomain.CurrentDomain.BaseDirectory/log.config.xml，缺失时按 xml→json→ini 优先级自动探测同目录同名配置，均无则回退到 Logs/Log.txt。

最简 XML 示例：

<?xml version="1.0" encoding="utf-8"?>
<log SupportsExpiredFileDetector="true" ExpiredFileCheckInterval="30">
  <Appenders>
    <Appender Type="Console" Name="console" Level="Info" />
    <Appender Type="File" Name="file" Level="Debug">
      <File FileDirectory="Logs" FileName="app" Extension=".log"
            RollingMode="DailyAndSize" MaxFileSize="50" ExpiredDays="30" />
    </Appender>
  </Appenders>
  <Loggers>
    <Logger Name="MyApp.Data" Level="Debug">
      <Appenders><Appender>file</Appender></Appenders>
    </Logger>
  </Loggers>
  <Root Level="Warn">
    <Appenders><Appender>console</Appender></Appenders>
  </Root>
</log>

常用占位符：%timestamp/%thread/%level/%logger/%message/%exception/%newline/%appdomain/%username/%identity/%file/%line/%method/%location/%eventid/%scope/%property/%stacktrace（共 22 个）。

完整配置参考（加载机制、三格式选型、顶层选项、Appender 全属性、File / AdoNet 选项、Logger·Root、滚动模式、三格式完整示例、Fluent Builder、Schema 验证、已知问题）见 MiniLog 使用手册·配置详解 与 CONFIGURATION.md。

五、Appenders 输出目标

共 8 种，均线程安全：

选型：低并发用 File，高并发用 AsyncFile。完整 8 种配置与 AdoNet 异步参数见 使用手册·Appenders。

六、性能定位

6.1 基准快照（.NET 8.0，BenchmarkDotNet）

固定消息（10K 次循环总耗时）：

异步文件（1K 条）：

源生成器级别关闭（10K 次）：

横向基准中 MS Logging 未挂载任何 Provider，Log() 在 IsEnabled 即短路为纯 no-op（102µs 是「什么都不做」的代价）。真实项目 MS 必挂 Provider，开销会上升。详细设计与并发/过滤基准见 使用手册·性能设计 与 BENCHMARK_REPORT.md。

6.2 零分配黄金路径

要让日志调用达成热路径零堆分配（对应基准：固定消息 42µs/万条零分配、参数袋 Span 物化 8.8µs/零分配、UDP 新 26ns/零分配；并发 40 万消息 16/18 零 GC），遵循：

1. 用结构化 API 代替字符串插值：logger.Log(new LogEntry { ... }) 或源生成器 Log<TBag>（编译期 FormatTo 零分配直写）；避免 logger.Info($"User {id}")（每次分配插值字符串，基准 560KB/万条）。
2. 渲染物化走 Span 直写：Appender 内部默认 WriteToAndClear(TextWriter) 直写（零分配）；仅确需字符串时才调 GetStringAndClear（基准 96KB/千次）。
3. 结构化字段用 %property：经 LogEntry.Properties["k"] = v 设置，%property{k} 渲染；PropertyCount == 0 短路零开销。
4. 高吞吐降载用采样：配置 SamplingFilterOptions，无锁零分配按比例丢弃。

完整四层基准（热方法 / 端到端 / 并发零分配 / 解析）与零回退论证见 BENCHMARK_REPORT.md。

布局模式校验器（编译期 LLG 诊断）

MiniLog 内置一个 Roslyn 分析器（MiniLog.Generators），在编译期校验赋值给 AppenderOptions.Pattern / AdoNetParameter.Layout（含 WithPattern(...) / WithLayout(...) 入参、常量折叠与插值字面段）的布局模式串，把 %token 拼写 / 格式错误拦在构建前，而非运行时解析失败。经 NuGet 包引入时分析器自动随包进入 analyzers/dotnet/cs，消费方编译期即得校验；配置文件（XML / JSON / INI）字面量则由 ConfigurationBinder 运行期探针以 Trace 警告兜底。

保留字（LLG0006 建议集）：ISO8601 / DATE / ABSOLUTE / COMPACT；精确匹配或任意 .NET 格式（如 yyyy-MM-dd）合法、不触发。

// 编译期即报错，而非运行时才发现布局串写错
new AppenderOptions { Pattern = "%levl %logger" };        // ⚠ LLG0002 未知 'levl'（是否指 'level'?）
new AppenderOptions().WithPattern("%date{yyyy-MM-dd");      // ⚠ LLG0003 未闭合
new AppenderOptions { Pattern = "%property{}" };            // ⚠ LLG0004 空选项
new AppenderOptions { Pattern = "%level{x}" };              // ⚠ LLG0005 'level' 不接受选项
new AppenderOptions { Pattern = "%date{ISO860}" };          // ⚠ LLG0006 疑似 'ISO8601'

// 配置文件（经 NuGet 分析的消费方亦生效，IDE 实时波浪线 + 构建警告）
<Appender Pattern="%levl %level" />                        // ⚠ 未知占位符 'levl'（是否指 'level'?）

有意不做（编译期不可判定）：非常量动态值（变量、含非 const 孔的插值）、%date{非法格式} 格式合法性、%property{不存在的键} 键存在性 —— 交由运行时解析兜底。

七、文档导航

八、许可证

MIT —— 详见 LICENSE（仓库根目录）。