简介：log4net-1.2.10 是 Apache 软件基金会推出的经典 .NET 日志记录框架，面向需要在开发、调试、运维阶段记录运行信息的 .NET 开发者。该版本同时提供源码与 DLL 文件，既能直接引用到项目中，也便于阅读源码理解其配置、Appender、Layout 及线程安全等实现机制。压缩包为 RAR 格式，大小约 6.79 MB，体量精简，适合快速集成到 ASP.NET、Windows 服务、WPF/WinForms 等各类应用程序，目前已有 270 人观看学习。资料内容涵盖核心特性、XML/代码/属性文件等配置方式、DEBUG 到 FATAL 多级别日志记录方法，以及从初始化到调用的完整示例代码，还介绍了调试定位、性能分析、异常捕获、系统监控和审计合规等典型应用场景。对于想提升系统可维护性、构建审计日志或排查线上问题的开发者，这份资源能提供可直接落地的配置参考与源码级学习路径，帮助在项目中灵活定制日志输出目标与格式。
1. 从 log4net 1.2.10 开始接手一个老项目
接手一个 .NET Framework 老系统，最让人心里没底的往往不是核心业务，而是日志模块。log4net 1.2.10 是这类老项目里出镜率最高的一款日志库，功能完整、配置灵活，但也把“配置文件玄学”这口黑锅背了很多年。很多新手被它看似复杂的 XML 吓退，老手也偶尔被文件锁定和版本冲突翻车。这篇笔记从一线工程师角度，把 log4net 1.2.10 的配置骨架、接入步骤、常见坑和进阶玩法完整过一遍，适合刚接手老项目的开发者，也适合想快速搭一套稳定日志方案的人。
2. 先看清 log4net 1.2.10 的骨架：Appender、Layout、Filter 与 Logger
log4net 的抽象模型设计得相当克制，核心是四个角色：Logger 负责接收调用方的日志请求，Appender 决定写到哪，Layout 决定写成什么样，Filter 决定哪些日志能通过。这个设计思路和主流日志框架一脉相承，学会这一套，以后再看其他日志库的配置也能快速迁移。
2.1 Logger 是入口，Appender 是出口
在 log4net 中，调用方不会直接 new 一个 Logger，而是通过LogManager.GetLogger获取ILog实例。GetLogger 的参数决定 logger 名称，log4net 按照层级关系管理这些名称，可以用类的全名，也可以用业务模块名。logger 之间存在继承关系，名称用点号分隔，比如MyApp和MyApp.Helper，后者的日志默认会冒泡到前者的 Appender，除非显式关闭 additivity。
Appender 才是真正干活的人。FileAppender 把日志写进文件，ConsoleAppender 把日志打到控制台，AdoNetAppender 把日志存进数据库。一个 Logger 可以挂多个 Appender，同时往文件和数据库写；也可以给同一个 Appender 配置 Filter，实现精细的日志分流。
2.2 Layout 决定日志长什么样
Layout 负责把日志事件序列化成字符串。最常见的 PatternLayout 使用 conversion pattern 来描述每一行日志的格式。%d表示时间，%level表示日志级别，%logger表示 Logger 名称，%message表示要记录的正文，%newline表示换行。改变 pattern 就能得到完全不同的日志排版，所以团队里通常会把模式串固化为统一约定。
2.3 Filter 决定日志是否被丢弃
Filter 在 Appender 内部执行。最常用的是 LevelRangeFilter，指定levelMin和levelMax来控制该 Appender 接受哪个级别的日志。还有 LevelMatchFilter、StringMatchFilter，适合做定向过滤。Filter 的执行顺序是从上到下，一旦有 filter 返回 deny，日志就被丢弃，后续 filter 不会再参与判断。
下面给一个最小但完整的配置，把 Logger、Appender、Layout 连起来：
<log4net debug="false"> <appender name="FileAppender" type="log4net.Appender.FileAppender"> <file value="logs/app.log" /> <appendToFile value="true" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%d{yyyy-MM-dd HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline" /> </layout> </appender> <root> <level value="DEBUG" /> <appender-ref ref="FileAppender" /> </root> </log4net>这段配置定义了一个 FileAppender，写入路径是 logs/app.log，appendToFile 为 true 表示不覆盖已有文件。PatternLayout 里%-5level表示级别左对齐 5 个字符，%thread可以输出线程名，便于多线程排查。root 节点是全局入口，level 设为 DEBUG 表示所有级别都允许进入，然后引用 FileAppender。
注意 1.2.10 对 XML 大小写敏感，type 属性、value 属性都不能写错，否则 log4net 会在初始化时静默跳过这个 Appender，日志直接进黑匣子。
3. 把 log4net 1.2.10 装进项目：引用、初始化与第一行日志
这一章解决实际操作问题：怎么把 DLL 放进去、怎么初始化、怎么写第一行日志。老项目里最常见的问题不是 API 不会用，而是配置没有被正确加载。
3.1 引用 DLL 的两种路子
第一种是在 IDE 的解决方案管理器里右键引用，直接选中 log4net.dll。1.2.10 时代很多项目组喜欢把第三方 DLL 放在解决方案的 lib 目录，方便源码管理和编译机还原。这种方式的优点是路径直观，缺点是 DLL 版本容易失控，bin 目录里可能同时存在多个版本的 log4net.dll。
第二种是用包管理器控制台执行命令：
Install-Package log4net -Version 1.2.10包管理器会自动把对应程序集加到 bin 目录。相比手动拖 DLL，这种方式便于统一版本，缺点是部分老项目的 .NET Framework 版本过低时，需要额外确认包的目标框架是否兼容。1.2.10 对应的程序集一般能支持较老框架，但确认一遍总没错。
3.2 初始化配置的三种常见姿势
log4net 不会自动找配置文件，必须显式初始化。最常见的姿势是在 AssemblyInfo.cs 里加特性：
[assembly: log4net.Config.XmlConfigurator(ConfigFile = "log4net.config", Watch = true)]配置文件名写 log4net.config，文件要放在启动目录或项目根目录，同时保证“复制到输出目录”为“始终复制”。Watch = true 表示文件变更后自动重载，排查问题时可省去反复重启。
第二种姿势是在代码启动入口调用：
log4net.Config.XmlConfigurator.Configure( new FileInfo(AppDomain.CurrentDomain.BaseDirectory + "log4net.config"));这种做法适合配置路径不固定、需要根据环境变量切换的场景，比特性方式更可控。接老项目时我通常用这种，因为它能明确看到是否加载成功，出错时也容易定位。
第三种姿势是把配置直接写进 app.config 或 web.config，在 configSections 里声明 log4net：
<configSections> <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net" /> </configSections>然后<log4net>节点直接放在 configuration 节点下。这样少一个配置文件，但站点配置和日志配置耦合在一起，后续维护时改日志会影响整个配置文件。我一般只在小型工具项目里用这种写法。
3.3 在代码里获取 Logger 并写出第一行日志
Logger 的获取和使用非常固定：
private static readonly ILog log = LogManager.GetLogger(typeof(Program)); static void Main(string[] args) { log.Info("应用启动，参数数量：" + args.Length); log.Debug("调试信息：" + DateTime.Now); try { // 业务逻辑 } catch (Exception ex) { log.Error("业务执行失败", ex); throw; } }GetLogger(typeof(Program)) 会以类全名作为 logger 名，在日志里直接看到是哪个类在打印，排查问题非常方便。log.Info 与 log.Debug 是不同级别，级别低于 root 配置的会被直接丢弃。Error 重载支持传入异常对象，log4net 会把堆栈完整输出，这一点在处理线上问题很关键。
4. 照着这份配置就能跑：模式串、多输出与日志轮换
配置不是越复杂越好，关键是让开发时看得清、上线后够用。这一章给出可以直接抄走的多场景配置，以及每个参数到底在控制什么。
4.1 PatternLayout 模式串：从入门到够用
模式串是 log4net 的排版语言，掌握它就能控制日志格式。下面是最常用的一组占位符：
| 占位符 | 含义 | 示例 |
|---|---|---|
| %d | 时间 | 2025-01-01 12:00:00 |
| %level | 日志级别 | INFO |
| %logger | Logger 名称 | MyApp.Program |
| %thread | 线程名 | 1 |
| %message | 日志正文 | 应用启动 |
| %exception | 异常堆栈 | 堆栈内容 |
| %newline | 换行 |
最常见的组合是%d{yyyy-MM-dd HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline。花括号里写时间格式，fff 输出毫秒，方便分析耗时问题。%-5level里的减号表示左对齐，没有它时不同长度的级别名会错位。
注意 1.2.10 中的 PatternLayout 对未知占位符非常宽容，不会直接报错，而是把占位符原样输出。所以格式不对时，先确认占位符拼写，再去查日志配置文件是否被正确加载。
4.2 ConsoleAppender 加 FileAppender 多路输出
开发调试时想同时在控制台看到日志，线上又必须落文件，一个 Logger 挂两个 Appender 就能满足：
<log4net> <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender"> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%d{HH:mm:ss} %level %logger - %message%newline" /> </layout> </appender> <appender name="FileAppender" type="log4net.Appender.FileAppender"> <file value="logs/app.log" /> <appendToFile value="true" /> <encoding value="utf-8" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%d{yyyy-MM-dd HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline" /> </layout> </appender> <root> <level value="DEBUG" /> <appender-ref ref="ConsoleAppender" /> <appender-ref ref="FileAppender" /> </root> </log4net>root 里列出两个 appender-ref，一条日志会同时进入两个 Appender。控制台格式用了更紧凑的 HH:mm:ss，文件格式保留完整日期和线程，这样开发时扫一眼就能定位，线上出问题也有足够信息。encoding 指定 UTF-8，避免中文日志在部分环境里变成乱码。
这里还要注意 FileAppender 不会自动创建多级目录，如果 logs 目录不存在，日志初始化就可能失败。启动前先把目录建好，或者用 Directory.CreateDirectory 兜底。
4.3 按日志级别拆分文件，避开过度过滤
日志全写进一个文件，时间长了会很难查。常见做法是 INFO 和 ERROR 分文件：
<appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender"> <file value="logs/all.log" /> <appendToFile value="true" /> <rollingStyle value="Date" /> <datePattern value="yyyyMMdd" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%d{yyyy-MM-dd HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline" /> </layout> </appender> <appender name="ErrorFileAppender" type="log4net.Appender.FileAppender"> <file value="logs/error.log" /> <appendToFile value="true" /> <threshold value="ERROR" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%d{yyyy-MM-dd HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline" /> </layout> </appender>threshold 是 Appender 级别的快速过滤，比 Filter 更轻量。把 ErrorFileAppender 的 threshold 设为 ERROR，只有 ERROR 及以上级别的日志才写进 error.log，排查故障时不用在几百 MB 的 all.log 里翻。注意 threshold 与 root 的 level 是两层控制，root 决定日志能不能进入日志体系，threshold 决定进入某个 Appender 后是否被接受，两者要配合设计。
5. 常见问题与避坑：log4net 1.2.10 的经典翻车现场
log4net 1.2.10 本身很稳定，真正让开发者头疼的是接入方式和运行环境。以下问题我都真实遇到过，每一条都按“现象 → 原因 → 解决”的顺序写清楚。
5.1 现象一：配置了 Appender，但日志就是不出
现象：代码里调了 log.Info，控制台和文件都没有任何输出，程序也不报错，日志模块像黑匣子一样。
原因：最常见的有两个。一是配置文件名不在启动目录，XmlConfigurator 找不到文件，整个配置被跳过；二是配置文件里 type 值写错或节点顺序不对，LogManager 初始化时用了空配置，自然没有输出。
解决：先打开 log4net 内部调试开关，在 log4net 根节点上加 debug="true"：
<log4net debug="true">初始化日志会输出到控制台，明确告诉你配置文件是否加载、每个 Appender 是否创建成功。另外，确认 log4net.config 是否被复制到输出目录，右键查看文件属性，“复制到输出目录”选“始终复制”。如果项目用 app.config 或 web.config，还要确认 configSections 里已经声明 log4net section。这两步是我排查日志问题的第一动作。
5.2 现象二：日志文件被锁，导致覆盖或丢失
现象：长时间运行后日志文件无法删除或重命名，进程退出前一直被占用；多个进程写同一个文件时，后启动的进程写不进去。
原因：FileAppender 默认的锁定模型是独占锁定，进程拿到文件后会一直占着句柄，直到进程退出。多个进程或站点应用共享日志文件时，这种模式会互相干扰。
解决：把锁定模型改成 MinimalLock：
<appender name="FileAppender" type="log4net.Appender.FileAppender"> <file value="logs/app.log" /> <lockingModel type="log4net.Appender.FileAppender+MinimalLock" /> </appender>MinimalLock 每次写日志时打开文件，写完立即关闭，多个进程可以轮流写同一个文件。代价是每次写入都涉及打开和关闭的开销，高频日志场景会出现 I/O 放大。如果只是单进程写日志，保持默认锁定模型反而更稳，没必要为了“看起来高级”去改动。
5.3 现象三：运行时提示找不到程序集或版本不匹配
现象：项目编译通过，启动时抛 System.IO.FileLoadException，提示 log4net 的版本不匹配；或者同一解决方案里不同项目引用了不同版本，运行时相互覆盖。
原因：log4net 官方程序集带强名称签名，引用版本和最终加载版本不一致时，运行时不会自动兼容。早年间手动拷 DLL 很常见，不同目录放了两份不同版本的 log4net.dll，bin 里到底加载哪个很看运气。
解决：在 app.config 或 web.config 的 runtime 节点加重定向：
<runtime> <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <dependentAssembly> <assemblyIdentity name="log4net" publicKeyToken="669e0ddf0bb1aa2a" culture="neutral" /> <bindingRedirect oldVersion="0.0.0.0-1.2.10.0" newVersion="1.2.10.0" /> </dependentAssembly> </assemblyBinding> </runtime>如果整个解决方案统一用 1.2.10，这条重定向基本一劳永逸。还要彻底排查项目里是否混入了其他版本的 log4net.dll，搜索整个源码目录和 bin 目录，逐一核对文件版本，这才是根因。
5.4 现象四：滚动日期不生效，日志文件增长停不下来
现象：配置了 RollingFileAppender，datePattern 写的是 yyyyMMdd，但运行好几天后日志还是一个文件，旧日志没有按天拆分。
原因：滚动只在日志事件发生时检查，如果某段时间完全没有日志写入，log4net 不会主动生成当天的新文件。datePattern 与滚动周期不匹配时，判断也会失效。
解决：确认 datePattern 的粒度与滚动周期一致。按天滚动用 yyyyMMdd 或 yyyy-MM-dd，按小时滚动用 yyyyMMddHH。同时注意跨天时第一笔日志才触发滚动，如果系统在凌晨确实没有流量，文件会在早上第一笔日志写入时才完成切换。如果业务上必须零点生成新文件，log4net 本身不做这种调度，需要外部定时器触发一次空写。
6. 进阶技巧：滚动策略、异步日志与验收检查
这章把前面的配置组合成一套可复用的生产方案，同时回答一个实际问题：日志量上来之后，配置该怎么调，性能怎么验证。
6.1 RollingFileAppender 滚动策略的参数组合
生产环境建议直接用 RollingFileAppender，按天加大小双条件滚动：
<appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender"> <file value="logs/app.log" /> <appendToFile value="true" /> <rollingStyle value="Composite" /> <datePattern value="yyyyMMdd" /> <maxSizeRollBackups value="10" /> <maximumFileSize value="100MB" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%d{yyyy-MM-dd HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline" /> </layout> </appender>rollingStyle 有三个可选值：Date 只按日期滚动，Size 只按大小滚动，Composite 表示两者都考虑。maximumFileSize 使用 KB/MB 单位，maxSizeRollBackups 表示保留的旧日志份数，超过后最旧的文件会被删除，存储成本可控。遇到“文件无限增长”的问题，绝大多数是因为 maxSizeRollBackups 没配，或者 rollingStyle 只写了 Date。
6.2 异步记录：避免日志拖慢业务线程
log4net 1.2.10 官方包没有内置异步 Appender，业务线程直接写日志时，文件 I/O 会阻塞调用线程。高并发下大量日志会把接口响应时间拉高。我接老项目时常用一个简单的异步包装：
public class AsyncLogWriter : IDisposable { private readonly ILog _logger; private readonly ConcurrentQueue<string> _queue = new ConcurrentQueue<string>(); private readonly CancellationTokenSource _cts = new CancellationTokenSource(); private readonly Thread _worker; public AsyncLogWriter(ILog logger) { _logger = logger; _worker = new Thread(FlushLoop) { IsBackground = true }; _worker.Start(); } public void Info(string message) { _queue.Enqueue(message); } private void FlushLoop() { while (!_cts.IsCancellationRequested) { while (_queue.TryDequeue(out string item)) { _logger.Info(item); } _cts.Token.WaitHandle.WaitOne(1000); } } public void Dispose() { _cts.Cancel(); _worker.Join(2000); _cts.Dispose(); } }核心思路是业务线程入队后立即返回，后台线程每 1 秒批量取一次写入。这个方法能把日志 I/O 从业务线程上卸掉，但队列是无界的，日志吞吐超过后台消费能力时队列会膨胀。重日志场景要改成有界队列，并在队满时降级丢弃或改用更大的缓冲。IsBackground 线程不会阻止进程退出，进程结束前必须显式调用 Dispose，把最后一批日志刷出去，否则会有丢失窗口。
6.3 验收检查：不重启也能确认日志在跑
配置完成的验证不能只看“有没有文件生成”，我习惯按下面这个清单过一遍：
- 用 DEBUG 级别启动，确认 Debug 日志能写入；
- 观察模式串里的时间格式，毫秒位是否按预期显示；
- 同时验证 Info 和 Error 两个级别，确认 threshold 过滤生效；
- 手动删掉当前日志文件，确认程序能重建，而不是直接锁死报错；
- 短时间写入两万条日志，观察文件大小和耗时是否有异常。
压测时可以加一个简单的计时模块，比如 Stopwatch 统计写入耗时，方便对比异步和同步模式的差距。
这套检查我每次接手老项目都会做。以前有一次线上日志文件被其他监控进程占用，整个服务卡死，查下来是锁定模型互相冲突。从那以后，我强制给每个接入 log4net 1.2.10 的项目都跑一遍“锁定模型检查加验收清单”，宁可启动时慢十分钟，也不愿意线上出问题时连日志都看不到。希望帮到你。
本文还有配套的精品资源，点击获取
