Apache log4net 3.5.0 介绍与核心概念详解

目标：讲清 Apache log4net 3.5.0 的项目定位、核心架构（Repository/Logger/Appender/Layout/Filter）、级别与 Threshold 语义，并给出与 NLog、Serilog 的选型对比。概念与示例均已在 Ubuntu 22.04 + .NET 8 实测通过。

一、环境信息

逐项说明：log4net 是纯 .NET 托管库，.NET Framework/.NET 6+/Mono 皆可运行；本篇所有行为均在 .NET 8 控制台程序上验证，NuGet 包 log4net 3.5.0 恢复自 api.nuget.org。

二、log4net 概述

2.1 项目定位与历史沿革

Apache log4net 是 Apache Logging Services 旗下针对 .NET 平台的日志框架，从 Java 世界的 log4j 1.x 移植而来，完整保留了 Logger 层次、Appender、Layout、Filter 的四件套模型与 XML 配置体系。对从 Java 转向 .NET 的团队，或者需要在 .NET 上沿用 log4j 心智模型的老项目，log4net 是最平滑的选择。

log4net 诞生于 2001 年左右（源于 Neowauk 项目的移植），2004 年进入 Apache 孵化器，2007 年成为 Apache 顶级项目。它长期服役于大量企业级 .NET 应用，是 .NET 生态资历最深的日志框架之一。3.x 系列开始全面适配 .NET 现代运行时，3.5.0 是当前的最新稳定版，支持 net8.0 目标框架并在 Linux 上完全可用（实测验证：控制台输出、文件滚动、Filter 均正常）。

2.2 3.5.0 版本要点

NuGet 引入 3.5.0 后，实测环境信息如下（项目文件内容）：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="log4net" Version="3.5.0" />
  </ItemGroup>
</Project>

逐项解说：3.5.0 以单一托管包分发，无任何原生依赖；net8.0 下可空引用检查开启时代码需注意 API 的可空标注（实测中 GetRepository(Assembly.GetEntryAssembly()) 会产生 CS8604 警告，用 ! 操作符标注即可）。与 2.x 相比，3.x 收紧了对旧运行时的支持并清理了部分废弃 API，配置语法保持兼容——2.x 时代的 log4net.config 基本可以无缝迁移。

三、核心架构

3.1 日志处理流水线

业务代码 log.Info(msg)
  → Logger 按有效级别判断（isEnabledFor）
  → 构造 LoggingEvent（时间戳、线程、Level、异常、上下文属性）
  → Logger 关联的每个 Appender 依次执行 Filter 链
  → Layout 将事件渲染为字符串
  → Appender 写往目标（控制台/文件/事件日志/网络）

与 log4j 同源的五步流水线：级别决定"要不要记"，Filter 决定"这个端要不要"，Layout 决定"长什么样"，Appender 决定"去哪里"。

3.2 Repository 与 Logger 层次

log4net 特有概念 Repository（日志仓库）：每个程序集默认拥有独立仓库，各仓库有自己的配置与 root Logger，多程序集应用可以分仓库隔离配置。常用 API（实测验证）：

ILog log = LogManager.GetLogger(typeof(Program));
ILoggerRepository repository = LogManager.GetRepository(System.Reflection.Assembly.GetEntryAssembly()!);
Console.WriteLine("全局 Threshold = " + repository.Threshold.Name);

实测输出：

日志输出完毕，全局 Threshold = ALL

逐项解说：ILog 是日志接口，LogManager.GetLogger 按传入类型名（含命名空间）创建/复用 Logger；repository.Threshold 是仓库级总闸，未在配置中显式设置时默认 ALL（实测输出 ALL 证实）。

Logger 层次规则：

实测验证（层次示例，三层 Logger）：OrderService.Dao 配置为 INFO 后，其 DEBUG 被拦截；UserService.Dao 未单独配置则继承 root 的 DEBUG，INFO 正常输出：

[ERROR] Dao - Dao 子 logger：订单 1001 落库失败
[INFO ] Dao - 另一分支 UserService.Dao 的 INFO 输出
---- 层次继承输出结束 ----

3.3 Level 与 Threshold

log4net 内置级别从低到高：ALL、TRACE、DEBUG、INFO、WARN、ERROR、FATAL、OFF。三道闸门语义：

特别注意实测发现：层次示例中 root 级别为 DEBUG，父 Logger OrderService 的 FATAL 消息本来可通过级别检查，但被 Appender 上 LevelRangeFilter 的 levelMax=ERROR 拦截——Filter 检查发生在级别检查之后，两道闸门彼此独立。

3.4 Appender 输出目标

log4net 内置 Appender 覆盖各类输出场景（type 属性为配置中的全限定类名）：

💡 技术拓展：同步与异步是 Appender 的关键分野。log4net 的 Console/File/Rolling 系列 Appender 在调用线程内同步写出，简单可靠但不抗磁盘抖动； buffering（BufferingForwardingAppender 或 ForwardingAppender+bufferSize）可以把事件攒批再转发给下游 Appender，达到接近异步的吞吐。本文实测以同步 Console/Rolling 为主，rolling 压测 300 条瞬时完成，常规服务的同步开销可接受。

3.5 Layout 日志布局

💡 技术拓展：Pattern 与结构化输出的取舍——PatternLayout 行式文本可读性强、grep 友好，但字段边界靠分隔符；需要机器解析时可用 XmlLayout 或 AdoNetAppender 参数化字段。实测本文采用 PatternLayout 的 %date [%thread] %-5level %logger - %message%newline 模板，兼顾可读与可切分。log4net 没有官方 JSON Layout，结构化 JSON 需自定义 Layout 或改用 Serilog。

3.6 Filter 过滤器

Appender 内部 Filter 链，返回 DECIDE 枚举（Deny/Neutral/Accept）。常用 Filter：

实测验证：LevelMatchFilter(levelToMatch=WARN, acceptOnMatch=true)+DenyAllFilter 链下，INFO/WARN/ERROR 三条只有 WARN 输出（白名单写法）；LevelRangeFilter(levelMin=DEBUG, levelMax=ERROR) 把 FATAL 拦在 Appender 之外。

3.7 上下文与对象渲染

四、功能特性

1. 全平台运行：.NET Framework、.NET 6/7/8、Mono 一套代码，实测 net8.0 控制台、文件滚动、Filter 全部正常。
2. 分仓库隔离：每个程序集一个 Repository，类库可以自带配置而不污染宿主。
3. 运行期重载：配置文件支持 watch，进程不重启即可改级别（XmlConfigurator.ConfigureAndWatch）。
4. 丰富的 Appender：控制台/文件滚动/Windows 事件日志/SMTP/ADO.NET/UDP 等开箱即用。
5. 环境变量与属性注入：配置中 %property{...} 与 GlobalContext 可动态注入部署参数（如节点名）。
6. 异常链完整：log.Error(msg, exception) 输出完整堆栈（实测 Error 带异常时堆栈逐行打印）。
7. Apache-2.0 许可、零第三方依赖，NuGet 一键引入。

五、适用场景

六、同类选型对比

log4net、NLog、Serilog 是 .NET 生态三大日志框架，对比结合实测与官方资料：

选型建议：

1. 已有 log4net 存量或团队有 log4j 背景——留在 log4net，升级 3.5.0 即可。
2. 新项目要结构化日志、丰富 sink、与 ASP.NET Core 深度集成——Serilog。
3. 想要 XML 配置 + 比 log4net 更现代的 API——NLog。
4. 多框架混部、统一 XML 运维习惯——log4net/NLog 都合适，Serilog 配置习惯不同需评估。

七、常见问题（FAQ）

Q1：log4net 3.5.0 支持 .NET 8 吗？ A：支持。实测 net8.0 控制台项目 dotnet add package log4net --version 3.5.0 后，控制台输出、文件滚动、Filter 全部正常。3.x 系列就是面向现代 .NET 的维护线。

Q2：repository.Threshold 为什么输出 ALL？ A：Repository 级 Threshold 未在配置中显式设置时默认 ALL，即不设总闸。实测输出 全局 Threshold = ALL；要收紧总闸可在配置根节点设置 threshold 属性。注意 Threshold 对象的文本值通过 .Name 获取（实测中误写 .Level 会编译报 CS1061）。

Q3：GetRepository(Assembly.GetEntryAssembly()) 报可空警告怎么办？ A：net8.0 项目默认开启 Nullable，GetEntryAssembly() 返回值可能为 null，触发 CS8604。确认非空的入口场景用 null 包容操作符（GetEntryAssembly()!）或先判空再调用，本文实测采用前者。

Q4：子 Logger 设了 INFO，为什么父 Logger 的 FATAL 也没了？ A：分两种情况：若是 FATAL 真消失，检查该 Logger 所挂 Appender 上是否有 LevelRangeFilter 且 levelMax 低于 FATAL——实测 levelMax=ERROR 时 FATAL 被 Filter 拦截，与 Logger 级别无关。级别检查与 Filter 检查是两道独立闸门。

Q5：日志文件写到了哪里？为什么不是程序运行目录？ A：实测大坑：File 属性写相对路径时，log4net 基于应用程序基目录（bin/Debug/net8.0）解析，不是当前工作目录。内部调试（log4net debug="true"）明确显示 Searched for existing files in [.../bin/Debug/net8.0/logs]。生产环境务必写绝对路径，或用 %property 注入的部署目录拼绝对路径。

Q6：如何在不停服的情况下改日志级别？ A：用 XmlConfigurator.ConfigureAndWatch(new FileInfo(...)) 加载配置，log4net 会监视文件变更并自动重载。注意 ConfigureAndWatch 在 Linux 下的文件监视依赖 FileSystemWatcher，跨平台行为一致。

Q7：异常堆栈怎么输出？ A：log.Error("消息", exception) 重载自动携带异常，实测输出消息后跟完整堆栈（System.Exception: Connection refused 等）。PatternLayout 默认 %message 不含堆栈，堆栈由 Appender 自动追加，或用 %exception 转换符控制位置。

Q8：%logger{name} 这种写法为什么报错？ A：实测报 log4net:ERROR NamedPatternConverter: Precision option "name" not a decimal integer.——%logger 的精度参数必须是数字（%logger{1} 输出最后一段，%logger{2} 输出最后两段）。想取短名用 %logger{1} 或别名 %c。

Q9：log4net 有官方 JSON Layout 吗？ A：没有。需要 JSON 就自定义 Layout（继承 LayoutSkeleton 渲染 JSON 字符串），或改用 AdoNetAppender 参数化字段、XmlLayout 过渡。这是与 NLog/Serilog 生态差距最大的点，结构化需求强烈时建议后者。

Q10：类库项目里该不该自带 log4net.config？ A：log4net 按程序集分仓库，类库可以自管配置，但更推荐类库只声明 ILog、由宿主统一配置——双配置容易导致日志重复或丢失。确需隔离时用 LogManager.CreateRepository 显式建仓并在文档中说明。

八、参考链接

1. Apache log4net 官方主页：https://logging.apache.org/log4net/
2. log4net 手册（特性与配置总览）：https://logging.apache.org/log4net/release/manual/
3. NuGet 包页（log4net 3.5.0）：https://www.nuget.org/packages/log4net/
4. log4net 配置手册（Appender/Layout/Filter 全参数）：https://logging.apache.org/log4net/release/config-reference.html
5. Apache Logging Services：https://logging.apache.org/
6. log4net GitHub 镜像：https://github.com/apache/logging-log4net