# vane.logging **Repository Path**: netcasewqs/vane.logging ## Basic Information - **Project Name**: vane.logging - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-19 - **Last Updated**: 2026-11-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Vane.Logging 轻量、高性能的 .NET 日志组件库,**零外部依赖**。派发模型沿用 logger → appender → layout 三段式,底层换成结构体日志条目、零分配渲染与源生成器。 > **版本** 1.0.0 · **目标框架** .NET 8.0 / 10.0 / 11.0 · **许可证** MIT > 源码仓库: ## 特性 - **零分配渲染** —— `LogEntry` 值语义结构体 + 栈缓冲 / `ArrayPool` 复用,热路径不产生 GC - **零装箱派发** —— 源生成器把结构化参数装进泛型参数袋,穿过整条派发链 - **源生成器双后端** —— `[Log]` 注入 `ILog` 字段,`[LoggerMessage]` 生成强类型方法,一份声明同时适配本库与 `Microsoft.Extensions.Logging` - **结构化输出** —— JSON / CLEF 单行直出,JSON 键名可对齐 ECS / OTel - **9 种 Appender** —— `Console`、`Debug`、`Trace`、`None`、`File`、`AsyncFile`、`Udp`、`AdoNet`、`BufferWriter` - **8 种过滤器 + 11×7 滚动** —— 级别、前缀、正则、属性等组合过滤;文件滚动 11 种模式、目录滚动 7 种模式 - **跨进程共享写** —— 多进程写同一文件按行原子追加,不会互相穿插 - **编译期诊断** —— `LLG0001`–`LLG0016` 覆盖装载入口、布局模式与高开销插值 ## 快速开始 ### 安装 ```bash dotnet add package Vane.Logging # 锁定版本时加 --version 1.0.0 # 接入 ASP.NET Core / Microsoft.Extensions.Logging 时再加 dotnet add package Vane.Logging.Mel ``` 源生成器随包以 Analyzer 形式自动引入,无需单独安装。 ### 五行开始记录 ```csharp using Vane.Logging; LogManager.InitializeFromFile(); // 读 log.config.xml;无配置则丢弃日志,不落盘不报错 var log = LogManager.GetLogger(); log.Info("应用启动"); LogManager.Shutdown(); // 退出前调用,排空异步缓冲 ``` `GetLogger()` 的 Logger 名取类型全限定名;需要自定义名字时用 `LogManager.GetLogger("Order.Service")`。 ### 源生成器:声明一次,方法自动生成 ```csharp using Vane.Logging; [Log] public partial class OrderService { public void Create(int orderId) => log.InfoFormat("订单创建 {0}", orderId); // 字段 log 由生成器注入 // [LoggerMessage] 由方法名推断级别,生成带级别短路与零装箱参数的实现 [LoggerMessage(LogLevel.Warn, "慢查询 {Sql} 耗时 {Elapsed}ms")] public partial void LogSlowQuery(string sql, long elapsed); } ``` > 走**项目引用**而非 NuGet 包时,源生成器不会自动传递,消费方需自挂 > ``,否则 `[LoggerMessage]` 会报 `CS8795`。 ### 配置文件 默认读取程序目录下的 `log.config.xml`,缺失时按 xml → json → ini 探测同名配置;也支持环境变量与纯代码配置。 ```xml file console ``` Pattern 布局共 26 个占位符(`%timestamp`、`%level`、`%logger`、`%message`、`%exception` …),`%%` 转义为字面量 `%`,支持 `[%-5level]` 这类对齐修饰。 ## 文档 | 文档 | 内容 | |---|---| | [使用手册](https://gitee.com/netcasewqs/vane.logging/blob/main/docs/Vane.Logging使用手册.md) | 核心概念 / 配置详解 / Appender 全属性 / 占位符全表 / 源生成器 / 性能设计 / 选型对比 / log4net 迁移 | | [配置参考](https://gitee.com/netcasewqs/vane.logging/blob/main/CONFIGURATION.md) | 加载机制 / 三格式完整示例 / Schema 校验 / 已知限制 | | [MEL 集成指南](https://gitee.com/netcasewqs/vane.logging/blob/main/docs/MEL集成指南.md) | 注册 API 全景 / 生命周期 / 级别与名称映射 / Scope / 热重载 | | [编译期诊断码](https://gitee.com/netcasewqs/vane.logging/blob/main/docs/DIAGNOSTICS.md) | LLG0001–LLG0016 逐条说明与触发条件 | | [MiniLog 迁移指南](https://gitee.com/netcasewqs/vane.logging/blob/main/docs/MiniLog迁移指南.md) | 旧包更名的对照表与迁移自检 | | [基准报告](https://gitee.com/netcasewqs/vane.logging/blob/main/BENCHMARK_REPORT.md) | 与 NLog / Serilog / log4net / MS Logging 的横向数据 | | [变更日志](https://gitee.com/netcasewqs/vane.logging/blob/main/CHANGELOG.md) | 1.0.0 首发记录 | ## 从源码构建 ```bash dotnet build Vane.Logging.slnx -c Release dotnet test Vane.Logging.slnx -c Release dotnet pack src/Vane.Logging/Vane.Logging.csproj -c Release ``` 核心库与生成器开启 `TreatWarningsAsErrors`,三个 TFM(net8.0 / net10.0 / net11.0)要求 0 警告 0 错误。发版流程见 [RELEASE.md](https://gitee.com/netcasewqs/vane.logging/blob/main/RELEASE.md)。 ## 许可证 MIT,见 [LICENSE](https://gitee.com/netcasewqs/vane.logging/blob/main/LICENSE)。