RuoVea.ExLog 10.0.0.2

📋 RuoVea.ExLog

零配置、即抛即忘的 .NET 日志组件 — 基于 log4net 3.3.1 封装，提供纯静态 API，自动按日期/级别分文件写入日志。无 DI 依赖、无中间件配置，真正意义上的开箱即写。

📖 目录

• 📋 概览
• 📦 安装
• ⚡ 30 秒快速开始
• 🧩 核心场景
  • 场景一：常见日志记录
  • 场景二：异常记录与追踪
  • 场景三：结构化日志（LogMessage）
  • 场景四：自定义日志对象（GetLogger）
  • 场景五：日志格式化（LogFormat）
• ⚙️ 配置选项详解
• 🛡️ 错误处理与日志
• 🧵 线程安全
• 📊 API 完整速查
• 🗺️ 版本迁移指南

📋 概览

RuoVea.ExLog 为 .NET 8.0 / 10.0 应用程序提供开箱即用的日志记录能力，封装了 log4net 的配置与调用细节。所有日志写入均为即抛即忘（fire-and-forget）模式，主线程不会被 IO 阻塞。

 ┌───────────────────────────────────────────────────────┐
 │                    RuoVea.ExLog                        │
 ├───────────────────────────────────────────────────────┤
 │   LogFactory (静态入口)                                │
 │   ├─ Info(string)      ──▶  log/yyyy-MM-dd/Info.log   │
 │   ├─ Debug(string)     ──▶  log/yyyy-MM-dd/Debug.log  │
 │   ├─ Warn(string)      ──▶  log/yyyy-MM-dd/Warn.log   │
 │   ├─ Error(string)     ──▶  log/yyyy-MM-dd/Error.log  │
 │   ├─ Error(Exception)  ──▶  log/yyyy-MM-dd/Error.log  │
 │   ├─ Error(string, Exception)                          │
 │   └─ Error(LogMessage)                                 │
 │                                                        │
 │   Log                  LogFormat       LogMessage      │
 │   ├─ Debug(object)     ├─ ErrorFormat   ├─ OperationTime│
 │   ├─ Info(object)      ├─ WarnFormat    ├─ Url         │
 │   ├─ Warn(object)      ├─ InfoFormat    ├─ Class       │
 │   └─ Error(object)     ├─ DebugFormat   ├─ Ip          │
 │                        └─ ExceptionFormat ├─ Host       │
 │                                           ├─ Browser    │
 │   LogLevel (枚举定义, 代码中未使用)         ├─ UserName   │
 │   Error / Warning / Info / Debug          ├─ Content    │
 │                                           ├─ ExceptionInfo
 │                                           ├─ ExceptionSource
 │                                           └─ ExceptionRemark
 ├───────────────────────────────────────────────────────┤
 │  底层: log4net 3.3.1 | 仓储: NETCoreRepository        │
 │  策略: Composite Rolling | 10MB | 无限备份 | MinimalLock│
 └───────────────────────────────────────────────────────┘

设计原则

文件组织

{当前目录}/
├── log4net.config          ← 首次使用时自动生成（若缺失）
└── log/
    ├── 2026-06-23/
    │   ├── Error.log
    │   ├── Warn.log
    │   ├── Info.log
    │   └── Debug.log
    ├── 2026-06-22/
    │   ├── Error.log
    │   └── ...
    └── ...

支持的 Target Framework

📦 安装

.NET CLI

# .NET 8.0
dotnet add package RuoVea.ExLog --version 8.0.0.2

# .NET 10.0
dotnet add package RuoVea.ExLog --version 10.0.0.1

Package Manager

Install-Package RuoVea.ExLog -Version 8.0.0.2

PackageReference

<PackageReference Include="RuoVea.ExLog" Version="8.0.0.2" />

⚡ 30 秒快速开始

1. 导入命名空间

using RuoVea.ExLog;

2. 第一行日志

// <inheritdoc cref="LogFactory.Info"/>
// 无需任何配置，直接写入 Info 级别日志
LogFactory.Info("用户登录成功");

// <inheritdoc cref="LogFactory.Error(Exception)"/>
try
{
    int result = 10 / int.Parse("0");
}
catch (Exception ex)
{
    LogFactory.Error(ex);  // 自动格式化异常信息并写入 Error.log
}

3. 日志文件自动就位

首次调用任一 LogFactory 方法时，如果当前目录不存在 log4net.config，组件会自动创建。日志随即写入 log/yyyy-MM-dd/ 目录下对应的文件。

30 秒内你完成了: 安装 NuGet 包 → 引用命名空间 → 写入 Info / Error 日志 → 在 log/{日期}/ 下查看日志文件。全程零配置。

🧩 核心场景

场景一：常见日志记录

┌──────────────┐    Task.Run    ┌─────────────┐    log4net     ┌──────────────────────┐
│ LogFactory    │ ────────────▶ │ 线程池线程    │ ───────────▶ │ log/yyyy-MM-dd/      │
│ .Info(string) │   即抛即忘     │ TextInfo()   │    RollingFile │   Info.log           │
└──────────────┘               └─────────────┘               └──────────────────────┘

// <inheritdoc cref="LogFactory.Info"/>
LogFactory.Info("订单创建成功，订单号: ORD-20260623-001");

// <inheritdoc cref="LogFactory.Debug"/>
LogFactory.Debug($"请求参数校验通过: userId={userId}, amount={amount}");

// <inheritdoc cref="LogFactory.Warn"/>
LogFactory.Warn($"库存预警: SKU={sku}, 剩余库存={remaining}, 阈值={threshold}");

场景二：异常记录与追踪

┌──────────────┐
│ try-catch    │
│   Exception  │
└──────┬───────┘
       │
       ├──▶ LogFactory.Error(Exception ex)
       │    → 提取 ex.Message / ex.Source / ex.StackTrace
       │    → 格式化后写入 Error.log
       │
       ├──▶ LogFactory.Error(string title, Exception ex)
       │    → title 前置到异常信息: "{title} : {ex.Message}"
       │    → 其余同上
       │
       └──▶ LogFactory.Error(LogMessage logMessage)
            → 使用 LogFormat.ExceptionFormat() 完整格式化
            → 写入 Error.log

// <inheritdoc cref="LogFactory.Error(Exception)"/>
try
{
    var user = await GetUserFromDbAsync(userId);
}
catch (Exception ex)
{
    LogFactory.Error(ex);
    // Error.log 输出:
    // 1. 调试: >> 操作时间: 2026/6/23 14:30:00   操作人:
    // 2. 地址:
    // 3. 类名: RuoVea.ExLog.LogFactory
    // 4. 主机:   Ip  :    浏览器:
    // 5. 异常: Attempted to divide by zero.
    // 6. 来源: RuoVea.ExLog
    // 7. 实例:    at RuoVea.ExLog.LogFactory.TextError(Exception error, String title)...
    // ---------------------------------------------------------------
}

// <inheritdoc cref="LogFactory.Error(string, Exception)"/>
try
{
    await ProcessPaymentAsync(order);
}
catch (Exception ex)
{
    LogFactory.Error("支付处理失败", ex);
    // ExceptionInfo = "支付处理失败 : {ex.Message}"
}

场景三：结构化日志（LogMessage）

┌───────────────┐
│  LogMessage   │
│  (POCO)       │
│               │
│ OperationTime │──┐
│ Url           │  │
│ Class         │  │    LogFormat.ErrorFormat(logMessage)
│ Ip            │  ├──▶ LogFormat.WarnFormat(logMessage)
│ Host          │  │    LogFormat.InfoFormat(logMessage)
│ Browser       │  │    LogFormat.DebugFormat(logMessage)
│ UserName      │  │    LogFormat.ExceptionFormat(logMessage)
│ Content       │  │
│ ExceptionInfo │  │         ┌─────────────────────────────┐
│ ExceptionSrc  │  └───────▶│ 格式化字符串 → Error.log     │
│ ExceptionRmk  │           └─────────────────────────────┘
└───────────────┘

// <inheritdoc cref="LogMessage"/>
// 构造完整异常上下文并记录
var logMsg = new LogMessage
{
    OperationTime = DateTime.Now,
    Url           = "/api/orders/create",
    Class         = "OrderService.CreateOrder",
    Ip            = "192.168.1.100",
    Host          = "order-api-01",
    Browser       = "Chrome/126.0",
    UserName      = "zhangsan",
    Content       = "创建订单 ORD-20260623-001",
    ExceptionInfo = "数据库连接超时",
    ExceptionSource = "OrderDbConnection",
    ExceptionRemark = "连接字符串: Server=db-01;Database=Orders; 超时: 30s → 实际 45s"
};

// <inheritdoc cref="LogFactory.Error(LogMessage)"/>
LogFactory.Error(logMsg);
// 内部调用 LogFormat.ExceptionFormat() 格式化后写入 Error.log

❗ 性能陷阱: LogMessage 各字段不会自动填充。使用前必须手动设置 OperationTime、Url、Class 等字段。LogFactory.Error(Exception) 重载会自动提取异常信息，但 LogFactory.Error(LogMessage) 完全依赖调用方填充。

场景四：自定义日志对象（GetLogger）

// <inheritdoc cref="LogFactory.GetLogger(Type)"/>
// 按类型获取日志操作对象
public class PaymentService
{
    private readonly Log _log = LogFactory.GetLogger(typeof(PaymentService));

    public void Process(decimal amount)
    {
        _log.Info($"处理付款: {amount:C}");
        _log.Debug($"付款明细: ...");
    }
}

// <inheritdoc cref="LogFactory.GetLogger(string)"/>
// 按字符串名称获取日志操作对象
var orderLog = LogFactory.GetLogger("OrderModule");

orderLog.Warn("订单模块: 检测到重复提交");
orderLog.Error("订单模块: 回调验签失败");

通过 GetLogger 获取的 Log 对象仍然是 log4net ILog 的轻量包装，不持有线程池调度逻辑（即同步写入 log4net，而非 Task.Run 调度）。如果追求异步写入，请使用 LogFactory 的静态方法。

场景五：日志格式化（LogFormat）

// <inheritdoc cref="LogFormat.ErrorFormat"/>
var logMsg = new LogMessage
{
    OperationTime = DateTime.Now,
    Class         = "CheckoutService",
    UserName      = "lisi",
    Content       = "购物车结算失败"
};
string formatted = new LogFormat().ErrorFormat(logMsg);
// 输出:
// 1. 错误: >> 操作时间: 2026/6/23 14:30:00   操作人: lisi
// 2. 地址:
// 3. 类名: CheckoutService
// 4. Ip  :    主机:    浏览器:
// 5. 内容: 购物车结算失败
// ---------------------------------------------------------------

// <inheritdoc cref="LogFormat.ExceptionFormat"/>
// ExceptionFormat 相较于 ErrorFormat 额外输出 ExceptionInfo/Source/Remark
string exFormatted = new LogFormat().ExceptionFormat(logMsg);
// ...
// 5. 异常: ...
// 6. 来源: ...
// 7. 实例: ...
// ---------------------------------------------------------------

五种格式化方法: ErrorFormat / WarnFormat / InfoFormat / DebugFormat / ExceptionFormat。前四种输出字段相同（仅标题文字不同），ExceptionFormat 额外输出异常来源与堆栈（第 5/6/7 行）。

⚙️ 配置选项详解

log4net.config 自动生成配置

组件在静态构造函数中自动加载 log4net.config。若文件不存在，调用 LogFactory.CreaterConfig() 或任一写入方法时自动生成，内容如下：

四个 Appender 差异对比

注意: Error.log 和 Debug.log 使用纯 %message 格式（无时间戳前缀），Warn.log 和 Info.log 使用带 %date 的格式。这是代码自动生成的行为，与旧版 README 中展示的示例不同。

自定义 log4net.config

如需自定义配置（如改为 JSON 输出、增加 SQL Server Appender），只需在项目根目录放置自定义的 log4net.config 并将 CopyToOutputDirectory 设为 PreserveNewest。组件检测到文件已存在时不会覆盖。

<?xml version="1.0" encoding="utf-8" ?>
<log4net>
  <root>
    <level value="ALL"/>
    <appender-ref ref="ConsoleAppender"/>
    <appender-ref ref="ErrorLog"/>
    
  </root>
  <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread] %-5level - %message%newline"/>
    </layout>
  </appender>
  
</log4net>

🛡️ 错误处理与日志

组件自身的异常行为

进程退出前刷新日志

RuoVea.ExLog 提供 Flush / FlushAsync 方法等待所有待处理日志写入完成，推荐在应用退出前调用：

// 同步刷新（超时 5 秒）
LogFactory.Flush(timeoutMs: 5000);

// 异步刷新（适用于 ASP.NET Core 生命周期）
await LogFactory.FlushAsync(timeoutMs: 5000);

❗ 性能陷阱: 短生命周期应用（CLI 工具、Lambda 函数）退出前务必调用 Flush，否则 Task.Run 尚未执行完成的日志将永久丢失。

🧵 线程安全

整体评估

LogFactory 线程详析

// 所有公开静态方法均采用此模式：
public static void Info(string error)
{
    System.Threading.Tasks.Task.Run(() => { TextInfo(error); });
}
// ↳ 调用方立即返回，实际写入发生在未来的某个线程池线程上

⚠️ 重要: 日志写入是异步的。短生命周期应用退出前请调用 LogFactory.Flush() / FlushAsync()，避免未完成的日志丢失。

⚠️ 使用注意: Error(string title, Exception error) 在 Task.Run 调度前从 Exception.TargetSite 捕获调用类名和方法名，因此日志中能正确反映原始调用方的类型和方法。

CreaterConfig 已改用 File.WriteAllText 原子写入，消除竞态条件。建议在应用启动时（Main 或 Program.cs 最顶部）单线程调用一次：

// <inheritdoc cref="LogFactory.CreaterConfig"/>
// Program.cs 入口处单线程调用
LogFactory.CreaterConfig(); // 确保配置存在且完整

已修复: 代码中不再追加 "\r\n"，改为 log4net Layout 统一通过 %newline 控制换行，消除双重换行问题。

📊 API 完整速查

LogFactory 静态类

Log 类（ILog 包装器）

Log 的方法为同步阻塞调用。如需异步写入，请使用 LogFactory 的静态方法。

LogMessage 类

LogFormat 类

LogLevel 枚举

LogLevel 枚举在当前版本中未被任何代码引用，仅为 API 预留定义。实际日志级别由调用方选择 LogFactory 的方法名决定。

🗺️ 版本迁移指南

从旧版 README 示例代码迁移

旧版 README 中展示的方法实际不存在，迁移方式如下：

从手动 log4net 迁移

v8.0.0.x → v10.0.0.x

• API 无变化。v10.0.0.1 仅在 net10.0 TFM 上编译，所有公开 API 签名保持一致。
• 底层 log4net 依赖版本不变（3.3.1）。
• 自动生成的 log4net.config 内容不变。

📄 License

MIT License © RuoVea

🔗 相关资源: NuGet Gallery · 问题反馈