简介面向C# Winform初学者与需要快速补齐日志模块的开发者这份日志输出例程源码演示了系统事件与操作行为的双通道记录方式程序启动、关闭等系统事件以及界面上的具体操作既会在窗口中实时显示也会写入后台日志文件日志按日期每天生成独立文件反复打开程序不会覆盖已有记录。压缩包共36个文件约745KB以9个cs源码文件为核心配合sln与csproj工程文件、config配置、resx资源及少量txt说明和exe示例结构适合直接导入Visual Studio运行、阅读与二次修改。已有2123人学习下载可作为课程设计、工具类软件或小型管理系统的日志功能参考通过现成代码可快速理解日志写入、窗口显示与按日归档的实现思路减少从零搭建日志模块的调试成本。1. 一个 WinForm 客户端栽在日志上这份 C# 例程补的是哪三个洞C# WinForm 项目里日志输出基本是最后一天才补的活儿界面上要能看到滚动的系统日志硬盘上要留一份能翻旧账的操作日志崩溃时还得靠它定位。这份例程源码做的事情就是把这三件事放进一个能跑起来的小工程——一个日志门面、几个输出通道、一套线程安全的写入流程。适合两类人刚接手工单系统、检测客户端这类带界面的桌面项目还在拿 MessageBox 当记录手段的新手以及写过日志但被跨线程刷新、文件被占用、中文乱码折腾过的老手可以拿它当骨架照着业务量把参数调一遍。2. 拆骨架门面、条目、通道三层怎么分工为什么不用现成框架例程能直接跑但真正有价值的是分层方式。WinForm 项目里日志代码最容易写成一团:窗体里直接File.AppendAllText异常处理里再MessageBox.Show最后日志和业务代码混在一起没法拆。这份例程用三层把耦合拆开每一层都单独可替换这也是能直接迁进已有工程的原因。2.1 门面、条目、通道三个类各管一件事门面是静态类Log业务代码只认它调用形式是Log.Info(模块名, 内容)。条目是LogEntry把时间、级别、线程号、来源模块、正文、异常对象打包成一个不可变的数据结构。通道是ILogSink文件是一个通道界面是一个通道调试输出又是一个通道彼此不知道对方存在。条目的格式化必须尽早固定下来因为日志一旦落盘就是长期资产格式中途改会让前后文件没法统一 grep。例程用的是定宽 竖线分隔时间、级别、线程号、来源各占固定位置正文放最后异常堆栈另起一行。这样用 Excel 按|分列、用findstr按列过滤都不难。public enum LogLevel { Debug 0, Info 1, Warn 2, Error 3, Fatal 4 } public sealed class LogEntry { public DateTime Time { get; set; } public LogLevel Level { get; set; } public int ThreadId { get; set; } public string Source { get; set; } // 模块名MainForm、DbSync、PrintService public string Message { get; set; } public Exception Error { get; set; } public string ToLine() { var sb new StringBuilder(256); sb.Append(Time.ToString(yyyy-MM-dd HH:mm:ss.fff)).Append( | ) .Append(Level.ToString().PadRight(5)).Append( | ) .Append(ThreadId.ToString().PadLeft(3)).Append( | ) .Append((Source ?? -).PadRight(12)).Append( | ) .Append(Message); if (Error ! null) sb.Append(Environment.NewLine).Append(Error); // 堆栈另起一行不破坏首行结构 return sb.ToString(); } }逻辑上ToLine()把所有格式化收敛到一个方法里界面通道和文件通道共用同一份输出排查时看到的内容和落盘的内容完全一致,不会出现界面上有、文件里没有的情况。参数上PadRight(5)的级别宽度和PadRight(12)的来源宽度要按你项目里最长的级别名和模块名调宁可留白也别让某一列挤掉后面的竖线时间用fff毫秒精度是刻意的串口通信、打印队列这类场景里相邻两条日志常在同一秒内发生秒级精度排序会失真。2.2 级别与通道的分配矩阵不是所有日志都该进同一个地方。界面上的记录用户看着烦文件里的 DEBUG 又没人看。例程的默认分配如下可以照着改级别文件通道界面通道说明Debug写不写报文、SQL、耗时只在排查版开启Info写写操作日志主体开机、登录、提交单据Warn写写可继续执行的异常如重试成功Error立即刷盘写并高亮需要人介入的失败Fatal立即刷盘写并弹提示进程级崩溃通常由全局异常钩子写入这里要区分两个概念很多项目把它们混在一个文件里后期根本没法查。系统日志记录的是运行状态——服务启动、数据库连接耗时、定时任务执行、未处理异常操作日志记录的是业务动作——谁在什么时候对哪张单子做了什么。两者写入频率、保留周期、检索维度都不一样系统日志按天滚动、保留七天就够操作日志往往要留半年以上还得能按单号、按操作人翻。例程里两者共用一个ILogSink接口但落地时建议拆成两个文件通道通过Source前缀区分比如操作日志统一用op.开头。这一点在后面的第 6 章会展开。2.3 把例程跑起来初始化顺序决定第一条日志会不会丢新建一个 WinForms 项目.NET Framework 4.7.2 或 .NET 6/8 的 WinForms 都行例程里的写法两边通用把日志相关的几个文件放进项目然后按下面的顺序初始化。[STAThread] static void Main() { var logDir Path.Combine( Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), MyApp, logs); var form new MainForm(); // 先建窗体RichTextBox 句柄才有宿主 Log.Init(LogLevel.Debug, new DailyFileSink(logDir), // 通道一按天滚动落盘 new RichTextSink(form.LogBox)); // 通道二界面追加 Log.Info(App, 进程启动日志目录 logDir); Application.Run(form); }顺序是有讲究的窗体必须先构造RichTextSink才能拿到RichTextBox的引用日志初始化必须在Application.Run之前否则主窗体Load里写的第一条日志会因为门面还是空对象而被静默丢弃。Log.Write里那句if (_pump null) return;是刻意的防御——日志系统自己没准备好时宁可丢日志也不能抛异常把启动流程带崩。验证只需要三步编译运行随便点两下界面按钮然后去%LOCALAPPDATA%\MyApp\logs看有没有生成app-yyyyMMdd.log用记事本打开确认中文正常、每条日志一行的结构完整再故意在按钮事件里抛一个throw new InvalidOperationException(test)看堆栈是不是被完整写进了文件而不是只留一句“未将对象引用设置到对象的实例”。提示第一次跑通之后先把日志目录改成只读试一次。如果程序启动就崩、连错误提示都没有说明初始化路径上还有没被 try 包住的 IO 调用这在客户现场是真会遇到的场景。3. 跨线程写日志BeginInvoke、队列削峰与一份能抄的日志泵WinForm 日志出问题八成出在这一章。业务线程串口回调、Task.Run、BackgroundWorker、定时器写日志日志再往界面上刷中间任何一环处理不当都是界面卡死或者跨线程异常。这一章把三种写法和它们的边界说清楚。3.1 直接 AppendText 为什么会炸WinForm 控件有线程亲和性非创建线程访问RichTextBox.Text会抛InvalidOperationException: 线程间操作无效。新手的第一反应是加CheckForIllegalCrossThreadCalls false这行代码确实能让异常消失但它只是把检查关掉了底层窗口句柄仍然在被两个线程同时操作,结果是随机崩溃、界面花屏、日志串行——这类问题在开发机上复现不出来到客户现场才发作。正确的做法是把写入动作封送到 UI 线程。Invoke是同步的调用方会一直阻塞到 UI 线程执行完BeginInvoke是投递到消息队列后立刻返回。日志场景一律用BeginInvoke因为日志是“尽力送达”的旁路功能不能反过来阻塞业务线程。用Invoke还有一个隐蔽的死锁UI 线程正在Wait一个后台任务后台任务里写日志调Invoke两边互等整个界面就冻住了。还有一个细节是句柄。窗体关闭时RichTextBox的句柄会被销毁此时后台线程还在写日志BeginInvoke会抛InvalidOperationException。必须判断IsDisposed和IsHandleCreated并且用 try-catch 兜住——这是退出阶段日志报错的主要来源。3.2 队列加后台泵把 IO 从业务线程上摘下来即使用了BeginInvoke每条日志都投递一次消息也不是好设计。界面线程的消息队列会被日志塞满用户点击的响应就排到后面去了。更麻烦的是文件写入StreamWriter.WriteLine看起来快但缓冲区满时会同步写磁盘在机械硬盘或者网络盘上是几十毫秒级别如果在串口接收回调里直接写丢包是必然的。例程的做法是生产者消费者业务线程只做一件事把LogEntry塞进有界队列单独一个后台线程从队列取批量分发给各个通道。这样业务线程的日志开销被压到一次入队通常几微秒磁盘 IO 和界面刷新都在后台线程完成。队列必须有界。无界队列在日志风暴时会吃光内存而有界队列满时的策略要明确丢弃并计数。丢日志比卡死主线程可接受得多但要记下丢了多少条否则事后排查会发现日志中间断了一截却不知道为什么。3.3 日志泵的完整实现与两个关键参数public sealed class AsyncLogPump : IDisposable { private readonly BlockingCollectionLogEntry _queue; private readonly ListILogSink _sinks; private readonly Thread _worker; private long _dropped; public AsyncLogPump(IEnumerableILogSink sinks, int capacity 20000) { _sinks sinks.ToList(); // 底层用 ConcurrentQueue容量满了 TryAdd 直接返回 false不做阻塞等待 _queue new BlockingCollectionLogEntry(new ConcurrentQueueLogEntry(), capacity); _worker new Thread(Consume) { IsBackground true, Name log-pump }; _worker.Start(); } public long Dropped Interlocked.Read(ref _dropped); public void Post(LogEntry entry) { if (!_queue.TryAdd(entry)) Interlocked.Increment(ref _dropped); } private void Consume() { var batch new ListLogEntry(256); while (true) { try { // 200ms 内没有新日志说明空闲借机刷盘 if (!_queue.TryTake(out var first, 200)) { FlushAll(); if (_queue.IsCompleted) break; continue; } batch.Add(first); // 一次最多取 256 条攒批减少锁竞争和系统调用 while (batch.Count 256 _queue.TryTake(out var more)) batch.Add(more); foreach (var e in batch) foreach (var sink in _sinks) { try { sink.Write(e); } catch { /* 单个通道失败不能拖垮整个日志系统 */ } } batch.Clear(); } catch (ObjectDisposedException) { break; } catch (InvalidOperationException) { break; } } } private void FlushAll() { foreach (var sink in _sinks) { try { sink.Flush(); } catch { } } } public void Dispose() { _queue.CompleteAdding(); // 通知消费线程不会再有新日志 _worker.Join(2000); // 最多等 2 秒把残留写盘 FlushAll(); _queue.Dispose(); } }逻辑说明CompleteAdding配合IsCompleted是一次优雅停机——窗体关闭时调用Dispose消费线程会把队列里剩下的日志写完再退出不会出现“最后几条错误日志不见了”的情况。Join(2000)的超时是必须的如果某个通道卡在写网络盘上不能让整个进程退出流程无限等下去。每个sink.Write单独 try-catch 也是刻意的界面通道因为句柄销毁抛异常时文件通道不能跟着挂掉。参数说明capacity默认 20000按每秒日志量和磁盘速度调。普通业务客户端每秒几十条20000 足够扛住几秒的磁盘抖动如果是采集类程序每秒上千条要么把容量提到 10 万要么把Debug级别关掉。批次上限 256 是经验和实测折中——太小起不到攒批效果太大则单条 Error 日志要等整批处理完才落盘实时性变差。TryTake的 200ms 超时决定空闲刷盘频率也就是崩溃时最多可能丢 200ms 内的日志对日志完整性要求高的场景把它改到 50ms代价是磁盘唤醒次数变多。3.4 UI 通道的批量刷新与行数上限界面通道的两个杀手是重绘次数和无界增长。RichTextBox每AppendText一次就触发一次布局和重绘1000 条日志就是 1000 次界面必然卡顿。解决办法是给 UI 通道也加一层缓冲后台线程攒一批UI 线程一次AppendText把整批文本拼进去。public sealed class RichTextSink : ILogSink { private readonly RichTextBox _box; private readonly int _maxChars; public RichTextSink(RichTextBox box, int maxChars 400_000) { _box box; _maxChars maxChars; // 按字符数限容比按行数判断便宜 } public void Write(LogEntry entry) { if (_box.IsDisposed || !_box.IsHandleCreated) return; if (_box.InvokeRequired) { try { _box.BeginInvoke(new ActionLogEntry(Append), entry); } catch (InvalidOperationException) { /* 句柄已销毁丢弃 */ } } else Append(entry); } private void Append(LogEntry entry) { if (_box.TextLength _maxChars) _box.Clear(); // 超限直接清空比逐行删除快得多 _box.AppendText(entry.ToLine() Environment.NewLine); _box.SelectionStart _box.TextLength; _box.ScrollToCaret(); } public void Flush() { } }这里用TextLength而不是Lines.Length做容量判断因为Lines每次访问都会切分整个文本几千行时开销明显。_maxChars 400000大约对应 3000 到 5000 行具体看单行长度。清空策略是简单粗暴的整块清空对“界面只是给人看最近发生了什么”的定位完全够用如果业务要求界面上能往前翻就得换成Select(0, 某行起点)再SelectedText 的删头方式代价是每次删除都会触发一次重排日志高频时反而更卡。4. 落盘这关按天滚动、缓冲刷盘与中文编码的六个参数文件通道是最容易“看起来能用、关键时刻掉链子”的部分。写不进去、写得慢、跨天不换文件、打开是乱码,这四类问题占了实际故障的绝大多数。这一章把每个参数为什么这么设讲透。4.1 文件命名与滚动策略按天、按大小还是两者都要单文件无限增长是绝对不能接受的一个跑三个月的客户端日志文件几个 GB记事本根本打不开查找也无从下手。滚动策略有三种常见选型策略命名示例适用场景代价按天app-20240513.log桌面客户端、班次制系统单日量极大时单文件仍然很大按大小app-20240513.003.log高频采集、服务端需要额外维护序号和当前大小按天按大小app-20240513_002.log日志量大又想按天归档实现复杂度最高例程默认用按天因为桌面项目的日志量通常在每天几 MB 到几十 MB按天切分后既能用日期直接定位又能配合一个清理任务删掉七天前的文件。判断是否换文件时有一个坑不能缓存一个DateTime.Now在构造函数里必须每条日志到达时用entry.Time判断。否则程序跨天运行工控机常年不关机是常态第二天还在往昨天的文件里写。public sealed class DailyFileSink : ILogSink { private readonly string _dir; private readonly object _gate new object(); private StreamWriter _writer; private DateTime _currentDate; public DailyFileSink(string dir) { _dir dir; Directory.CreateDirectory(_dir); } public void Write(LogEntry entry) { lock (_gate) // 文件句柄不是线程安全的必须串行 { RollIfNeeded(entry.Time); _writer.WriteLine(entry.ToLine()); } } private void RollIfNeeded(DateTime now) { if (_writer ! null now.Date _currentDate) return; _writer?.Flush(); _writer?.Dispose(); _currentDate now.Date; var path Path.Combine(_dir, $app-{now:yyyyMMdd}.log); // FileShare.ReadWrite 允许日志查看工具在程序运行时打开同一个文件 var fs new FileStream(path, FileMode.Append, FileAccess.Write, FileShare.ReadWrite); _writer new StreamWriter(fs, new UTF8Encoding(false)) { AutoFlush false }; } public void Flush() { lock (_gate) { _writer?.Flush(); } } }逻辑说明lock (_gate)保护的不只是StreamWriter还有“先判断日期、再换文件”这个复合动作。多个线程同时发现跨天如果不加锁会重复打开文件句柄前一个句柄泄漏且继续持有文件锁。FileMode.Append保证重启后是追加而不是覆盖这一点比FileMode.Create安全得多。参数说明FileShare.ReadWrite是关键参数。默认的FileShare.None意味着程序运行时别人打不开这个日志文件用户双击查看会提示“文件正被另一进程使用”很多人因此以为程序出问题了。改成ReadWrite后可以边跑边看代价是如果你在记事本里改了这个文件并保存可能与程序写入的内容互相覆盖——所以只读查看没问题不要编辑。4.2 AutoFlush 的两难崩溃时少丢几行还是每条都落盘AutoFlush true意味着每次WriteLine都立刻 flush 到操作系统进程崩溃也不丢。但它把缓冲的意义完全抹掉了日志量大时每条一次系统调用性能下降非常明显。AutoFlush false依赖StreamWriter的内部缓冲默认 1KB 左右和上面日志泵的空闲刷盘正常退出、跨天滚动、队列空闲时都会 flush只有进程被强杀任务管理器结束进程、断电时才可能丢最后几 KB。折中方案是分级Error和Fatal级别写完立刻 flushInfo及以下走缓冲。实现上给ILogSink.Write之外再加一个Flush()在日志泵里判断级别foreach (var e in batch) { foreach (var sink in _sinks) sink.Write(e); // 严重级别不等待立刻落盘 if (e.Level LogLevel.Error) foreach (var sink in _sinks) sink.Flush(); }对绝大多数桌面业务系统这个策略够用了。真正要求“一条都不能丢”的场景比如涉及金额的操作日志做法不是靠 AutoFlush而是先把日志落到本地 SQLite 或者单独的事务性文件再由后台线程归档成文本——文件系统本身不提供事务语义靠Flush保证不了断电不丢。4.3 编码与 BOM中文变问号的三个来源日志里出现????或者锟斤拷来源通常有三个。第一是StreamWriter没指定编码默认用了Encoding.Default在中文系统上是 GB2312/GBK换一台英文系统或者用 UTF-8 工具打开就全乱。第二是显式写了Encoding.UTF8这会带上 BOM文件开头多出三个不可见字节某些日志采集工具和脚本解析时会把它当成正文的一部分第一行永远匹配不上。第三是读取端用了错误的编码文件本身是对的看的人用错工具。正确写法就是new UTF8Encoding(false)写 UTF-8 但不写 BOM。例程里用的就是这个。如果日志要交付给第三方或者被 Python 脚本解析这一点尤其重要——open(path, encodingutf-8)遇到 BOM 会在首行开头留下\ufeff一个看似莫名其妙的 bug。注意如果项目里已经有历史日志是 GBK 的不要一次性全改 UTF-8那会导致新旧文件混杂、统一检索失效。可行的做法是文件名里带上编码标记或者干脆按日期分界旧文件只读保留。4.4 日志目录选错程序装完就写不进去开发时日志写在bin\Debug\logs一切正常。装到客户机上放到C:\Program Files\下普通用户权限对这个目录没有写权限Directory.CreateDirectory直接抛UnauthorizedAccessException。更坏的情况是有人用管理员权限跑过一次目录被创建出来了之后普通用户运行就一直在写失败。正确做法是写到用户可写的位置Environment.SpecialFolder.LocalApplicationData下的应用子目录或者%ProgramData%多用户共用日志时用后者但首次创建目录需要提权。绝对不要用Application.StartupPath除非你能确认安装目录可写。另一个坑是网络盘和漫游配置文件把日志写进Roaming目录会导致登录时同步大量文件登录变慢所以用LocalApplicationData。目录创建也要包在 try 里。日志系统初始化失败不应该让主程序起不来退化成只写调试输出Debug.WriteLine也比崩掉强。这一点在客户的精简系统、被安全软件锁目录的机器上都验证过。5. 排查清单五条把日志系统自己搞崩的踩坑记录日志模块的 bug 有个特点它自己出错时你没有任何日志可看。下面五条是这类问题里出现频率最高的。5.1 现象日志文件删不掉提示被占用原因StreamWriter没有Dispose或者程序异常退出时没走Dispose路径文件句柄一直悬着。还有一个隐蔽情况是滚动时只Flush没Dispose旧 writer句柄泄漏一天泄漏一个。解决把Dispose挂在窗体FormClosing上调用日志泵的Dispose日志泵再调所有 sink 的Dispose滚动时严格Flush→Dispose→ 新建顺序不能反。清理旧文件的定时任务遇到IOException要静默跳过第二天再删不要弹框。5.2 现象日志一多界面就假死点按钮没反应原因每条日志一次BeginInvokeUI 消息队列被日志消息塞满用户的点击和重绘排在后面。这和“跨线程异常”是两回事异常已经解决了但体验仍然崩。解决UI 通道加批量缓冲后台线程每 100 到 200ms 把攒下的行拼成一个字符串一次AppendText送进去。另外检查ScrollToCaret()的调用频率它每次都触发滚动和重绘是隐藏的性能杀手批量写入时只在最后调用一次。5.3 现象中文日志部分变问号部分正常原因不同通道用了不同编码。文件通道指定了 UTF-8界面通道没问题但某处用了File.AppendAllText(path, text)没传编码走了系统默认。同一个文件被两种编码交替写入就成了混合编码的怪物。解决全项目只允许一个地方创建StreamWriter所有写文件都走这个 sink。用grep -r AppendAllText扫一遍代码把散落的写文件调用全部收编。5.4 现象跨天后日志还写在昨天的文件里原因滚动判断用了构造函数里缓存的DateTime.Now或者用了进程启动时间。工控机、收银机常年不关机跨天是必然事件。解决判断依据必须来自当前日志条目的entry.Time并且在每次Write时都判断。如果系统时间被 NTP 往回校now.Date可能比_currentDate小此时也要触发滚动否则会一直往一个“未来日期”的文件里写。5.5 现象异常日志只有一行“未将对象引用设置到对象的实例”原因写日志时只传了ex.Message没传ex对象。Message对NullReferenceException这类异常毫无信息量堆栈和内部异常全丢了。解决统一用Log.Error(source, message, ex)让LogEntry.ToLine()里用ex.ToString()而不是ex.Message。ToString()会带上异常类型、消息、堆栈和InnerException链。另外在AppDomain.CurrentDomain.UnhandledException和Application.ThreadException两个钩子里都要接上前者抓非 UI 线程的崩溃后者抓 UI 线程的——只接一个的话另一类崩溃会静默退出什么记录都没有。6. 从系统日志到操作审计加三个字段就能按单据号翻旧账系统日志解决了“程序出了什么事”但客户提的需求往往是“上个月那张单子是谁改的价”。这两类查询的维度完全不同前者按时间后者按业务主键。改动量其实很小在LogEntry上加三个字段就够——Operator操作人、BizNo单据号或设备编号、TraceId一次操作的串联标识可以用Guid.NewGuid().ToString(N).Substring(0, 8)。有了BizNo操作日志就能单独落一个文件文件名按业务类型分比如op-order-20240513.log有了TraceId一次“点击保存 → 校验 → 写库 → 打印”的完整链路能串起来看排查“为什么这单没打印出来”比翻时间线快十倍。再进一步把操作日志同时写一份到本地 SQLite建表时给BizNo和Time各建一个索引客户端上就能做一个“日志查询”页面按单号模糊匹配这是很多交付项目里最省钱的一个加分项。字段类型用途BizNoTEXT建索引按单据号/设备号精确或前缀查询OperatorTEXT审计追责登录后写入全局上下文TraceIdTEXT建索引一次操作的链路串联从点击到落库有一个限制要提前说清楚本地文件日志不适合做跨机器的集中审计。多台客户端各写各的要汇总就得靠共享目录或者上报服务前者在网络抖动时会拖慢写入后者需要额外的服务端。如果客户只是要“能查”本地 SQLite 完全够如果是要合规留痕、集中检索那就该上正经的日志收集链路这份例程的通道接口正好留了扩展点——写一个HttpSink实现ILogSink就行业务代码一行不用改。我自己吃过一次亏早期图省事操作日志和系统日志共用一个文件级别全是 Info结果客户来查“谁删了这条记录”我在几千行报文和连接池日志里翻了两个小时。从那以后凡是带业务单据的项目我都在LogEntry里强制塞BizNo和Operator两个字段写日志时这两个值为空就直接抛断言——宁可开发期报错也不要交付后靠人肉 grep。希望帮到你。本文还有配套的精品资源点击获取