简介这份实例是一个基于C#控制台应用ConsoleApp1的log4net集成教程面向需要在.NET开发环境中快速搭建日志记录机制的开发者可有效解决日志级别控制、输出目的地配置和格式自定义等问题。资源共包含218个文件压缩包大小约43.32MB以dll类库、xml/config配置文件、cs源代码及sln工程文件为主同时带nupkg包与构建辅助文件整体覆盖了项目运行和调试所需的完整结构。目前已有1309人学习下载。实例详细演示了通过NuGet引用log4net、在程序入口加载XML配置、使用ILog接口输出DEBUG、INFO等不同级别日志的操作路径并说明了如何基于不同的Appender与布局模式扩展输出目标。示例项目结构清晰包含独立的配置文件和典型的日志输出类便于对照实际代码理解配置与调用之间的关系也能为后续接入异步记录、多线程安全及日志归档等高级特性打下基础。1. 日志框架选型为什么在C#项目中我仍会优先考虑log4net在.NET生态里聊日志很多人第一反应是NLog、Serilog这些后起之秀甚至微软官方的ILogger抽象层也已经很成熟。但如果你去翻老牌工业软件、上位机控制系统、WinForms桌面工具这些项目的源码会发现log4net依然是出现频率最高的那个。这不是情怀而是它在特定场景下确实有不可替代的优势。log4net最早源自Java世界大名鼎鼎的log4j2001年移植到.NET平台后一直维护到今天。它的核心模型极其稳定Logger日志记录器、Appender输出目的地、Layout输出格式、Filter过滤规则四个概念各司其职。这种设计的直接好处是配置文件一旦写好业务代码里你只需要关注log.Info()还是log.Error()完全不用操心日志最终写到文件、数据库还是Windows事件查看器里。我在实际项目中帮别人接手过一个用log4net跑了好几年的设备数据采集系统日志文件累计超过20GB按天滚动、自动清理旧文件整套机制运行得稳如老狗几乎没有出过幺蛾子。这让我对它的稳定性非常有信心。如果你的项目是工业控制、医疗设备、金融客户端这类“上线后不能随便重启”的场景log4net成熟、保守、文档丰富的特点就是巨大的加分项。当然如果你是在做一个全新的微服务、Web API项目我更倾向于使用Serilog配合结构化日志。但如果你需要快速给传统桌面应用或单体服务加上一套可靠的文件日志log4net依然是非常务实的选择。这篇文章我会从NuGet引入、配置文件编写、代码集成到高级排错完完整整走一遍实际可用的步骤。2. 环境准备与基础配置30分钟跑通第一个log4net日志2.1 通过NuGet引入log4net包不管你是用Visual Studio、VS Code还是Rider第一步都是在项目里引入log4net的程序集。我习惯用包管理器控制台执行Install-Package log4net如果你用的是.NET 6的SDK风格项目也可以直接编辑csproj文件添加下面的PackageReferenceItemGroup PackageReference Includelog4net Version2.0.15 / /ItemGroup这里多说一句版本选择。截至我写这篇文章的时间log4net 2.0.x是稳定主线2.1.x也已经有预览版流出但社区生产环境用得最多的还是2.0.15。如果不是有特殊需求我建议直接锁定2.0.15因为这个版本在.NET Framework 4.5和.NET Core/.NET 5/6/7/8上都验证过踩坑成本最低。2.2 理解log4net的三层核心结构配置log4net之前必须先理解它那套经典的“三权分立”模型否则看配置文件会越看越晕Logger负责在代码里发出日志请求通常在每个类里通过LogManager.GetLogger()获取。它只决定“我要记录什么级别的事件”。Appender负责决定日志“写到哪”。文件、控制台、数据库、邮件、网络Socket都各有对应的Appender实现。Layout负责决定日志“长什么样”。比如PatternLayout可以自定义时间戳、线程ID、类名这些字段的输出格式。Logger和Appender之间通过logger节点和root节点关联root是所有Logger的默认父节点。如果你不给某个Logger单独配置Appender它会沿着继承链向上找最终落到root节点配置的Appender上。这个机制是log4net最精妙的设计之一省去了很多重复配置。2.3 编写一个生产级log4net配置文件我直接给出一个我在多个项目里用过、经过生产验证的配置大家可以根据自己的需求微调?xml version1.0 encodingutf-8 ? log4net !-- 根Logger默认级别为Debug所有未单独配置的Logger都继承这个设置 -- root level valueDebug / appender-ref refRollingFileAppender / appender-ref refConsoleAppender / /root !-- 第三方库的日志级别可以单独调高避免刷屏 -- logger nameMicrosoft level valueWarn / /logger !-- 按日期和大小滚动的文件输出器 -- appender nameRollingFileAppender typelog4net.Appender.RollingFileAppender file typelog4net.Util.PatternString valueLogs/app_%date{yyyyMMdd}.log / appendToFile valuetrue / rollingStyle valueComposite / datePattern valueyyyyMMdd / maxSizeRollBackups value30 / maximumFileSize value10MB / lockingModel typelog4net.Appender.FileAppenderMinimalLock / staticLogFileName valuefalse / layout typelog4net.Layout.PatternLayout conversionPattern value%date{yyyy-MM-dd HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline / /layout /appender !-- 控制台输出器主要用于调试阶段 -- appender nameConsoleAppender typelog4net.Appender.ConsoleAppender layout typelog4net.Layout.PatternLayout conversionPattern value%date{HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline / /layout /appender /log4net上面这个配置里有几个细节值得展开讲讲。文件名用PatternString实现按日期命名。file typelog4net.Util.PatternString valueLogs/app_%date{yyyyMMdd}.log /这一行的作用是把日期动态拼进文件名里这样每天会生成一个新的日志文件比如app_20250614.log而不是所有日志堆在同一个文件里。rollingStyle设为Composite意思是我同时启用“按日期滚动”和“按大小滚动”。当天的日志文件超过10MB时自动切换一个新文件日期切换时也会生成新文件。maxSizeRollBackups30表示最多保留30个备份文件加上当前文件共31个超过后自动删除最老的避免磁盘被日志塞满。lockingModel使用MinimalLock是很多人忽视但很重要的设置。默认的ExclusiveLock会锁定日志文件一旦程序崩溃文件可能被锁死导致无法删除或查看。MinimalLock在每次写入时才获取锁写完后立即释放虽然频繁开关文件有一点性能损耗但在桌面应用场景中这个损耗微乎其微换来的是文件可随时移动、删除、归档的便利性非常值得。2.4 在程序入口处完成log4net初始化配置写好之后很多人会卡在“为什么我的代码里调用了log.Info()却什么都没输出”这一步。原因是log4net不会自动扫描配置文件你必须在程序启动时手动加载配置。传统做法是在AssemblyInfo.cs或Program.cs的入口处加一行XmlConfigurator.Configure()然后通过log4net的配置文件来指定要读取的配置文件路径。我推荐直接在项目属性里把log4net.config文件的“复制到输出目录”设为“始终复制”然后在启动代码里这样写using log4net; using log4net.Config; // 在Main方法的最开始执行 XmlConfigurator.Configure(new FileInfo(Path.Combine(AppDomain.CurrentDomain.BaseDirectory, log4net.config)));如果你使用的是WinForms或WPFMain方法在Program.cs里如果是ASP.NET Core建议在Program.cs的Main开头完成。只需执行一次整个进程就都能使用log4net了。提示如果初始化之后还是没日志优先检查配置文件的“复制到输出目录”属性是否是“始终复制”。这是新手最容易踩的坑没有之一。3. 业务代码集成在C#代码里优雅地记录日志3.1 获取Logger实例的两种姿势配置搞定了接下来写代码。log4net的LogManager.GetLogger()可以有多种用法我见过有同行在每一个类里都写相同的代码获取logger。为了代码整洁我习惯在一个公共静态类里统一暴露logger比如public static class Log { private static readonly ILog log LogManager.GetLogger(typeof(Log)); public static void Debug(string message) log.Debug(message); public static void Info(string message) log.Info(message); public static void Warn(string message) log.Warn(message); public static void Error(string message) log.Error(message); public static void Error(string message, Exception ex) log.Error(message, ex); public static void Fatal(string message, Exception ex) log.Fatal(message, ex); }调用的时候就非常清爽任意类里直接写Log.Info(设备连接成功IP地址192.168.1.10端口502); Log.Error(读取传感器数据失败, ex);另一种做法是在每个类里单独获取带类名的loggerprivate static readonly ILog log LogManager.GetLogger(typeof(DeviceService));这种做法的好处是日志输出里会自动带上类名方便排查问题到底出在哪个类。两种方式各有优劣如果项目规模不大、模块边界清晰统一封装成Log静态类完全够用如果系统庞大复杂建议还是按类区获取logger排查问题的效率会高很多。我在实际工作中更倾向于按类获取因为日志输出中的%logger占位符能直接暴露问题的位置在多线程、多模块场景下非常有用。3.2 日志级别怎么选Debug/Info/Warn/Error/Fatal各有用途log4net共定义了五个级别从低到高分别是DEBUG、INFO、WARN、ERROR、FATAL。每个级别对应一个输出方法log.Debug()、log.Info()、log.Warn()、log.Error()、log.Fatal()。这里有个关键概念如果配置里level valueInfo /那么任何Debug级别的日志请求都会被过滤掉不会被Appender处理。这个机制意味着你可以通过修改配置文件的level值来动态控制日志的详细程度而不需要改任何代码。比如生产环境可以设为Warn只保留警告和错误排查现场问题时改成Debug重启程序就能看到详细信息。很多新人容易在这个地方犯迷糊把业务逻辑相关的重要信息用Debug级别输出结果生产环境里啥都查不到。我的建议是Debug记录方法出入参、循环内部状态、临时调试信息Info记录关键业务节点如系统启动、用户登录、订单创建Warn记录非致命但值得关注的情况如重试、降级、配置缺失Error记录未处理异常、操作失败、外部服务不通Fatal记录进程无法继续运行、数据库连接彻底断开等严重故障实际操作中Info和Error的区分度是最重要的。我见过有项目把所有异常都打成Error结果错误日志里一天几千行真正需要关注的崩溃反而被淹没了。越少越珍贵的规则在日志领域同样适用。3.3 记录异常信息的最佳实践输出异常时我强烈建议把整个异常对象作为第二个参数传给log4net而不是手写ex.Message拼成字符串。下面我对比两种写法// 不推荐的写法只记录异常消息丢失堆栈和内部异常信息 Log.Error(调用数据服务失败 ex.Message); // 推荐的写法传入完整异常对象日志里包含堆栈和InnerException Log.Error(调用数据服务失败, ex);第二种写法在日志文件中会输出异常类型、完整堆栈跟踪以及所有内部异常信息排错时价值巨大。即使你只是想记录一条消息也建议用log.Error(message, ex)的形式因为log4net的布局里可以单独用%exception占位符控制异常信息的展示格式。3.4 使用log4net的调试输出log4net.Debug开关还有一个容易被忽略的好用开关log4net.Debug。当你怀疑log4net本身出了问题比如配置文件没加载、Appender配置错误时可以在配置文件的log4net节点内部加上log4net debugtrue或者在代码里设置log4net.Util.LogLog.InternalDebugging true;开启后log4net会把自身运行时的诊断信息输出到控制台包括配置文件解析失败的具体原因。这个开关排查问题时太救命了记得在实际交付前关掉避免刷屏。4. 进阶玩法自定义日志字段、异步写入与多文件输出4.1 用PatternLayout精细控制日志格式PatternLayout的conversionPattern是log4net最灵活的格式控制项熟悉它等于掌握日志布局的“格式化字符串”。我常用的转换符列在下方转换符含义示例输出%date{格式}时间戳支持自定义格式2025-06-14 10:30:22.125%thread线程ID排查多线程问题必备15%level日志级别INFO%loggerLogger名称通常为类全名MyApp.DeviceService%message日志消息内容具体业务信息%exception异常堆栈详情异常完整信息%newline换行符\r\n%-5level级别左对齐并占5位对齐输出更好看INFO我比较推荐下面这个格式兼顾可读性和信息量%date{yyyy-MM-dd HH:mm:ss.fff} [%thread] %-5level %logger - %message%newline4.2 让日志输出不再卡UI异步AppenderWinForms和WPF程序里如果业务线程把大量日志写到磁盘UI线程可能出现卡顿。这时候可以考虑异步Appender我用得比较多的是log4net.Async这个第三方扩展库它实现了一个AsyncAppender把所有日志写入操作放进后台线程池主线程调用log.Info()后立即返回。使用方法不复杂先通过NuGet安装log4net.Async然后修改配置文件把原来直接引用RollingFileAppender的地方改成先引用AsyncAppender再由它转发给真正的文件Appenderappender nameAsyncFileAppender typeLog4Net.Async.AsyncAppender appender-ref refRollingFileAppender / /appender然后把root节点里对RollingFileAppender的引用替换成appender-ref refAsyncFileAppender /。这里有个细节异步Appender的本质是“先写内存缓冲再由后台线程落盘”所以如果进程突然崩溃或强制结束缓冲里未写入的日志可能丢失。使用前要想清楚能否承受这个风险我的习惯是在Error和Fatal级别出现时除了异步Appender输出再额外接一个同步的邮件或数据库Appender保证严重错误不丢。4.3 按业务模块拆分日志文件系统功能复杂时把所有日志混在一个文件里很难快速定位。log4net支持模块化日志分离只需在配置文件里再定义一个Appender并把它和特定名字的Logger绑定即可。比如我希望所有数据库操作相关的日志写到db_log.txtlogger nameMyApp.DataAccess level valueDebug / appender-ref refDatabaseFileAppender / /logger appender nameDatabaseFileAppender typelog4net.Appender.RollingFileAppender file valueLogs/db_log.txt / appendToFile valuetrue / rollingStyle valueDate / datePattern valueyyyyMMdd / layout typelog4net.Layout.PatternLayout conversionPattern value%date [%thread] %-5level %logger - %message%newline / /layout /appender然后代码里获取logger时传入的类名需要跟配置匹配private static readonly ILog dbLog LogManager.GetLogger(MyApp.DataAccess);这样dbLog产生的日志全部进db_log.txt而其他logger继续走根节点的默认配置。业务中我常用这个思路做“操作审计日志”“通信原始报文日志”“业务异常日志”的分离排查问题时效率倍增。4.4 记录关键业务数据时的性能与安全考量log4net写入日志是I/O操作频繁记录大文本或者高吞吐场景性能问题就出来了。我在一个高频数据采集项目里测过直接同步写文件单线程每秒钟最多处理两千多条日志再往上就会出现写入延迟。解决方案除了上文说的异步Appender还有一个容易被忽略的优化合理降低日志输出量。我会在业务代码中增加一个“日志等级开关”比如用log.IsDebugEnabled判断当前是否开启了Debug级别没开启就跳过一些昂贵的字符串拼接操作if (log.IsDebugEnabled) { log.Debug($读取到第{i}包数据长度{buffer.Length}内容{BitConverter.ToString(buffer)}); }这样做有两个好处一是避免在日志级别未开启时白白执行字符串拼接、BitConverter.ToString这类耗时操作二是代码里的日志逻辑更清晰不会因为调试语句影响正常业务流程。另外日志内容涉及敏感信息时要格外小心。我在项目中会专门写一个脱敏辅助方法记录用户信息、连接字符串、SQL语句时自动把密码、Token等字段替换成***。这个习惯在新人写的日志里尤其欠缺别等出了事故再回头补。5. 实战排错log4net常见问题与解决方案速查5.1 日志文件根本没生成如何排查这是我在技术社区里被问得最多的问题。如果你的代码调用了log4net.Config.XmlConfigurator.Configure()配置文件路径也对但运行后日志文件就是没出现按下面顺序排查检查配置文件复制到输出目录的属性。Visual Studio里右键点击log4net.config文件选择属性把“复制到输出目录”改为“始终复制”。这是最常犯的错误。检查配置文件格式是否合法。XML解析失败时log4net会静默失败建议先开启log4net.Debug输出让内部错误显形。检查Logs目录权限。如果程序运行在服务账户下可能没有权限在Program Files或系统盘的某个目录创建文件夹。解决办法是改用%AppData%或Path.Combine(AppDomain.CurrentDomain.BaseDirectory, Logs)这样的路径。检查Logger名称是否匹配。如果配置里给某个logger设了名字但代码里GetLogger传入的是别的名字可能会造成日志记录不到预期Appender里。我碰到过最奇葩的一次日志文件生成了但一片空白排查了半天发现是Windows Defender把日志文件锁住了进程写入失败。后来在RollingFileAppender里把lockingModel改成MinimalLock问题迎刃而解。5.2 日志重复输出的问题明明只配置了一次Appender日志却出现了两条。通常原因是root节点和某个logger节点同时引用了同一个Appenderlog4net默认不阻止这种“叠加输出”它会把日志同时发送给根logger和子logger各自引用的Appender于是同一条消息被写了两次。解决办法有两种方案一确认root和子logger引用的是不同Appender各管各的。方案二如果确实希望子logger完全覆盖根logger不给子logger单独配置Appender只配置级别这样消息会沿继承链向上传递给根logger输出一次。5.3 日志文件被其他进程锁定无法查看或删除这是文件型日志的经典痛点。程序运行中日志文件被占用你用记事本打开有时能看但删除或重命名就报“文件正在被另一进程使用”。前面提到的MinimalLock模式能大幅缓解这个问题。它的原理是每次写入时获取文件锁写入后立即释放而不是在程序启动时就独占资源。代价是频繁打开关闭文件有一点性能损耗但对绝大多数业务系统来说完全在可接受范围内。如果必须使用ExclusiveLock默认模式那在处理日志文件之前一定要先停止应用程序或服务否则文件会被锁定无法操作。5.4 多线程环境下日志丢失或乱序log4net本身是线程安全的Logger和Appender的实现都对并发做了处理理论上不会丢失日志。但如果你用了异步Appender日志顺序可能被打乱因为多个线程同时往Buffer里塞消息后台线程再逐条取出写入文件顺序不一定和调用顺序一致。解决思路有两个一是给异步Appender的Buffer设大一点并结合批量取出的配置减少乱序概率二是对顺序要求极高的日志比如设备通信报文使用同步的FileAppender并确保调用logger的入口处有合适的锁或者按逻辑串行执行。5.5 配置文件更改后重启不生效log4net的配置默认在初始化时加载一次之后修改配置文件不会自动生效。如果希望动态监控配置文件变更、随时热更新日志级别可以在XmlConfigurator.Configure()中传入Watch参数XmlConfigurator.ConfigureAndWatch(new FileInfo(log4net.config));这样程序会启动一个后台线程监视配置文件一旦文件被修改log4net自动重新加载配置。这个功能在排查线上问题时特别好用临时把日志级别调成Debug定位完再改回Info连程序都不用重启。代价是文件监视会占用少量系统资源但我个人认为收益远大于开销。6. 收官分享日志规范与长期维护的几条建议写代码和写日志本质上是两种不同的思维。代码是写给机器执行的日志是写给人查的。我见过太多项目上线时日志功能一切正常半年后日志文件里全是无意义的调试信息真正的错误反而被淹没。把日志当成系统的第一公民来对待长期维护的人会感谢你。我给自己定过几条简单的日志规范控制得还不错每个类只创建一个logger实例字段声明为private static readonly。业务关键节点必须记录Info级别日志包含上下文信息订单号、设备ID、请求流水号。方法入口不轻易记录Debug日志除非方法逻辑实在复杂难以排查。异常捕获后不要默默吞掉至少要记录Error级别日志。高频循环内部的日志必须做“节流”或“抽样”避免日志文件爆炸。log4net这个库已经陪伴.NET开发者二十多年它的设计理念虽然带着上个时代的影子但稳定可靠。如果你愿意花半小时把配置文件琢磨透彻在后续开发的几年里它会在无数个深夜帮你定位那些让人头疼的诡异问题。最后再说一个我常干的细节操作日志文件里加一行启动分隔线。程序每次启动时先记录类似 系统启动 的Info日志这样翻日志时一眼就能知道哪几行是一次启动产生的排查启动阶段的问题会轻松很多。这个小习惯我延续了很多年也推荐给看到这里的朋友。本文还有配套的精品资源点击获取