简介这是一套面向.NET桌面开发者的软件自动更新解决方案适用于WinForm、WPF等客户端程序的版本迭代场景。方案核心思路是依据文件列表比对哈希值对本地文件执行下载替换、删除与新增操作最终启动软件本体经测试可稳定实现自动更新适合需要为自研客户端搭建升级机制的中级开发者参考。资源包共394个文件约23.49MB以79个dll动态库、35个cs源码文件、3个csproj工程文件与3个sln解决方案为主辅以xml配置、nupkg包、pdb调试符号及resx资源文件构成较完整的工程结构。目前已有2140人学习下载。需要特别说明的是作者已明确标注该项目停止维护、不推荐使用因此更适合作为更新逻辑与哈希校验思路的学习样本而非直接投产的成品方案读者可从中借鉴文件比对与增量替换的实现方式再结合自身项目重构升级模块。1. 从一次线上事故说起Winform/WPF 自动更新到底难在哪去年帮朋友处理过一个挺典型的线上事故一个 Winform 客户端用户量不大但分布很散某次发版后陆续有人反馈打开就闪退。排查了半天才发现是自动更新逻辑把主程序 exe 替换到一半时进程被占用文件写不进去结果新旧文件混在一起程序自然起不来。这类问题在 Winform 和 WPF 桌面应用里太常见了——Web 端发个版刷新一下就行桌面端要考虑文件占用、权限、断点续传、回滚每一步都是坑。这次要拆的是一套基于文件哈希比对的自动更新方案覆盖 Winform、WPF 这类传统桌面客户端。它的核心思路不复杂服务端维护一份文件清单含每个文件的哈希值客户端启动时拉取清单逐文件比对本地哈希只下载有差异的部分然后执行替换、新增、删除操作最后拉起主程序。相比整包下载这种方式流量小、更新快尤其适合那种主程序几百兆但每次只改几个 DLL 的场景。需要先说明的是这个项目作者已经停止维护所以下面我讲的是把它当作一套可参考的实现思路来拆而不是推荐你直接拿去上生产。适合读这篇的人正在给 Winform/WPF 做更新模块的 C# 开发者、被整包下载太慢困扰的客户端团队、以及想搞清楚哈希比对更新到底怎么落地的人。如果你只是想找个开箱即用的更新框架那这篇更多是帮你建立判断标准——知道哪些环节必须自己兜底。2. 哈希比对更新的原理与文件清单设计2.1 为什么用哈希比对而不是版本号比对很多团队做更新第一反应是比版本号服务端存一个 version.txt客户端读本地版本不一致就整包下载。这方案在早期能用但很快会撞墙一是整包下载流量浪费严重一个 200MB 的客户端只改了一个配置文件也要全量拉二是版本号本身不可信用户手动改过文件、更新中断过、装过补丁版本号还是旧的但文件其实已经变了。哈希比对解决的就是文件到底变没变这个问题。服务端为每个文件算一个哈希常见用 MD5 或 SHA256客户端拿到清单后对本地同名文件算同样的哈希一致就跳过不一致才下载。这样即使版本号没变只要文件内容变了也能识别出来反过来版本号变了但某文件没动也不会重复下载。选 MD5 还是 SHA256 要看场景。MD5 计算快对几万个文件的清单生成友好但理论上存在碰撞风险SHA256 更安全但慢一些。桌面更新这种场景文件内容是自己可控的MD5 够用我一般会选 MD5 换速度。如果对完整性要求极高比如涉及授权文件再上 SHA256。2.2 文件清单的数据结构清单是整个方案的地基设计不好后面全是坑。一份合格的清单至少要有这些字段字段类型说明FilePathstring相对路径如bin/App.Core.dllHashstring文件内容的哈希值Sizelong文件字节数用于校验下载完整性LastWriteTimeDateTime最后修改时间辅助判断ActionenumAdd / Update / DeleteAction字段容易被忽略但很关键。删除操作必须显式声明否则客户端永远不知道该删哪些旧文件时间一长目录里全是历史残留。我见过一个项目更新了两年bin 目录里堆了上百个废弃 DLL最后靠人工清理。清单一般用 JSON 或 XML 存JSON 更轻。下面是一个生成清单的脚本示例服务端打包后跑一遍即可// 生成文件清单遍历发布目录计算每个文件的哈希 public static ListFileItem BuildManifest(string publishDir) { var list new ListFileItem(); var baseUri new Uri(publishDir Path.DirectorySeparatorChar); foreach (var file in Directory.GetFiles(publishDir, *, SearchOption.AllDirectories)) { // 跳过更新器自身和临时文件避免自我覆盖 var name Path.GetFileName(file); if (name.Equals(Updater.exe, StringComparison.OrdinalIgnoreCase)) continue; if (name.EndsWith(.tmp) || name.EndsWith(.log)) continue; var relative baseUri.MakeRelativeUri(new Uri(file)).ToString(); list.Add(new FileItem { FilePath Uri.UnescapeDataString(relative).Replace(/, \\), Hash ComputeMd5(file), Size new FileInfo(file).Length, LastWriteTime File.GetLastWriteTimeUtc(file), Action FileAction.Update }); } return list; } private static string ComputeMd5(string path) { using (var md5 MD5.Create()) using (var stream File.OpenRead(path)) { var hash md5.ComputeHash(stream); return BitConverter.ToString(hash).Replace(-, ).ToLowerInvariant(); } }这段代码有几个细节值得说。baseUri.MakeRelativeUri用来算相对路径比字符串截取靠谱能正确处理子目录。跳过Updater.exe是必须的——更新器正在运行不能把自己也列进待替换清单否则更新到一半自己没了。过滤.tmp和.log是防止把运行时产生的垃圾文件打进清单。ComputeMd5用流式读取而不是File.ReadAllBytes大文件时内存占用差别很大。哈希统一转小写避免大小写不一致导致比对失败——这个坑我踩过服务端生成大写、客户端算小写结果每次更新都全量下载。2.3 客户端比对流程客户端拿到清单后核心逻辑是三分类本地没有的要新增本地有但哈希不同的要更新本地有但清单里没有的要删除。删除这一步最容易被漏掉也最容易出事后面避坑章节会细讲。// 客户端比对把清单和本地文件做三分类 public static UpdatePlan Compare(ListFileItem manifest, string localDir) { var plan new UpdatePlan(); var manifestPaths new HashSetstring(StringComparer.OrdinalIgnoreCase); foreach (var item in manifest) { manifestPaths.Add(item.FilePath); var localPath Path.Combine(localDir, item.FilePath); if (!File.Exists(localPath)) { plan.ToAdd.Add(item); // 本地缺失新增 continue; } var localHash ComputeMd5(localPath); if (!localHash.Equals(item.Hash, StringComparison.OrdinalIgnoreCase)) { plan.ToUpdate.Add(item); // 哈希不一致更新 } } // 本地有但清单没有的标记删除 foreach (var file in Directory.GetFiles(localDir, *, SearchOption.AllDirectories)) { var relative GetRelativePath(localDir, file); if (!manifestPaths.Contains(relative) !IsProtected(relative)) { plan.ToDelete.Add(relative); } } return plan; }IsProtected是个白名单用来保护用户数据、配置文件、日志目录不被误删。这个设计很重要——更新逻辑再严谨也不能碰用户自己的东西。常见做法是把config/、data/、logs/这类目录排除在删除范围外。比对完成后UpdatePlan里就是这次要做的全部操作。下载阶段可以并发但替换阶段必须串行且加锁这是后面要讲的重点。3. 下载、替换与进程拉起的完整实现3.1 下载策略并发、断点与校验清单比对完接下来是把ToAdd和ToUpdate里的文件下载下来。这里有几个决策点。第一是并发数。单线程下载慢但并发太高会打满带宽、拖垮服务端。我一般设 4 到 8 个并发用SemaphoreSlim控制。第二是断点续传大文件下载中断后从头再来很浪费可以用 HTTP 的 Range 头做续传。第三是下载后必须校验哈希网络传输可能损坏文件不校验的话替换进去就是坏文件。// 并发下载 哈希校验失败重试两次 public static async Task DownloadAll(UpdatePlan plan, string serverUrl, string localDir, int maxConcurrency 6) { var semaphore new SemaphoreSlim(maxConcurrency); var tasks new ListTask(); foreach (var item in plan.ToAdd.Concat(plan.ToUpdate)) { await semaphore.WaitAsync(); tasks.Add(Task.Run(async () { try { var url ${serverUrl}/{item.FilePath.Replace(\\, /)}; var tempPath Path.Combine(localDir, item.FilePath .tmp); Directory.CreateDirectory(Path.GetDirectoryName(tempPath)); await DownloadWithRetry(url, tempPath, item.Hash, retry: 2); } finally { semaphore.Release(); } })); } await Task.WhenAll(tasks); } private static async Task DownloadWithRetry(string url, string tempPath, string expectedHash, int retry) { for (int i 0; i retry; i) { try { using (var client new HttpClient()) using (var resp await client.GetAsync(url, HttpCompletionOption.ResponseHeadersRead)) { resp.EnsureSuccessStatusCode(); using (var fs new FileStream(tempPath, FileMode.Create, FileAccess.Write)) { await resp.Content.CopyToAsync(fs); } } // 下载完立刻校验不通过就当失败重试 if (ComputeMd5(tempPath).Equals(expectedHash, StringComparison.OrdinalIgnoreCase)) return; } catch when (i retry) { /* 最后一次不吞异常 */ } } throw new IOException($下载校验失败: {url}); }关键点是先下到.tmp临时文件校验通过后再改名替换。这样即使下载中途失败也不会污染正式文件。DownloadWithRetry里把校验放在下载之后、返回之前校验不过就继续循环重试重试耗尽才抛异常。HttpCompletionOption.ResponseHeadersRead这个参数容易被忽略它让响应头一到就开始读流而不是等整个响应体缓冲完大文件时内存占用差别明显。3.2 替换阶段为什么必须用独立更新器这是整个方案最容易翻车的地方。如果更新逻辑跑在主程序里替换主程序 exe 或它加载的 DLL 时文件被进程占用File.Copy直接抛IOException。Windows 不允许替换正在运行的可执行文件。标准解法是拆出一个独立的更新器进程Updater.exe。主程序启动时先检查更新有更新就启动 Updater 并退出自己Updater 完成替换后再把主程序拉起来。这样主程序退出后文件锁释放替换才能成功。// 主程序侧发现更新后启动更新器并退出 public static void LaunchUpdater(UpdatePlan plan) { var updaterPath Path.Combine(AppDomain.CurrentDomain.BaseDirectory, Updater.exe); var planFile Path.Combine(Path.GetTempPath(), update_plan.json); File.WriteAllText(planFile, JsonConvert.SerializeObject(plan)); var psi new ProcessStartInfo { FileName updaterPath, Arguments $\{planFile}\ \{AppDomain.CurrentDomain.BaseDirectory}\, UseShellExecute false }; Process.Start(psi); Environment.Exit(0); // 主程序必须退出释放文件锁 }Environment.Exit(0)这行不能省也不能用Application.Exit()之类的温和退出——必须确保进程彻底结束文件句柄全部释放。更新器侧则要等主程序真正退出后再动手// 更新器侧等主程序退出再执行替换 static void Main(string[] args) { var planFile args[0]; var targetDir args[1]; var plan JsonConvert.DeserializeObjectUpdatePlan(File.ReadAllText(planFile)); // 等待主程序完全退出最多等 30 秒 WaitForMainProcessExit(TimeSpan.FromSeconds(30)); // 先备份再替换失败可回滚 var backupDir Path.Combine(Path.GetTempPath(), update_backup_ DateTime.Now.Ticks); Directory.CreateDirectory(backupDir); try { foreach (var item in plan.ToUpdate.Concat(plan.ToAdd)) { var target Path.Combine(targetDir, item.FilePath); var temp target .tmp; if (File.Exists(target)) { var backup Path.Combine(backupDir, item.FilePath); Directory.CreateDirectory(Path.GetDirectoryName(backup)); File.Copy(target, backup, true); // 备份旧文件 } File.Copy(temp, target, true); // 替换 File.Delete(temp); } foreach (var rel in plan.ToDelete) { var target Path.Combine(targetDir, rel); if (File.Exists(target)) File.Delete(target); } } catch (Exception ex) { Rollback(backupDir, targetDir); // 出错回滚 LogError(ex); return; } // 替换完成拉起主程序 Process.Start(Path.Combine(targetDir, App.exe)); }WaitForMainProcessExit用Process.GetProcessesByName轮询或者更稳的做法是主程序退出前写一个已退出标记文件更新器等这个文件出现。轮询简单但不够可靠标记文件更稳。备份目录用时间戳命名避免多次更新互相覆盖。回滚逻辑就是把备份目录里的文件拷回去虽然简单但关键时刻能救命。3.3 更新器自身的更新问题有个绕不开的问题Updater.exe 自己怎么更新它正在运行没法替换自己。常见做法是给更新器也留一个.new版本更新器启动时先检查有没有Updater.exe.new有的话把自己复制成临时文件、用临时文件重启再替换正式的 Updater.exe。这个逻辑有点绕但必须处理否则更新器永远停留在第一版。另一个做法是把更新器做得足够简单、足够稳定几乎不需要更新把变化都放在主程序里。我倾向于后者——更新器代码越少越好逻辑越简单越不容易出 bug。4. 避坑指南哈希更新最容易翻车的五个地方4.1 现象更新后程序启动报找不到 XXX.dll原因删除逻辑把不该删的文件删了。最常见的是清单生成时漏了某些文件比如动态加载的插件、运行时生成的配置客户端比对时发现本地有但清单没有直接删掉。解决删除操作必须走白名单只删清单里显式标记为Delete的文件不要用清单里没有就删这种激进策略。清单生成时也要确保覆盖所有发布产物包括那些不常改的依赖。4.2 现象每次启动都提示有更新反复下载同一个文件原因哈希比对大小写不一致或者换行符差异。服务端在 Linux 上生成清单客户端在 Windows 上算哈希如果文件是文本且换行符不同\nvs\r\n哈希必然不一致。解决哈希统一转小写比对文本文件在打包时就统一换行符清单生成和客户端校验用同一套哈希算法和编码。4.3 现象更新到一半断电/断网程序再也起不来原因替换阶段没有原子性文件替换到一半中断新旧文件混杂。解决所有下载先落.tmp校验通过才改名替换前备份旧文件更新器启动时先检查有没有未完成的更新比如存在.tmp或备份目录有的话先回滚再重试。4.4 现象更新器启动后主程序没退出替换失败原因主程序用了Application.Exit()但还有后台线程没结束进程没真正退出文件锁还在。解决主程序启动更新器后必须Environment.Exit(0)强制退出更新器侧要轮询确认主进程真的没了再动手别急着替换。4.5 现象部分用户更新后权限报错写不进 Program Files原因程序装在C:\Program Files下普通用户没有写权限替换文件时抛UnauthorizedAccessException。解决更新器请求管理员权限在 manifest 里声明requireAdministrator或者把更新目录放到用户可写的%LocalAppData%下。前者会弹 UAC后者要改安装路径各有取舍得根据产品形态选。5. 进阶把更新做成可验证、可回滚的闭环前面讲的都是能跑通但生产环境要求更高——你得能验证更新是否成功、失败能否回滚、出问题能否定位。这一章讲几个我实际用下来觉得值的技巧。第一个是更新日志。更新器每做一步都写日志下载了哪些文件、替换了哪些、删了哪些、耗时多少。日志落到%LocalAppData%\YourApp\update.log出问题时让用户发过来比猜强一百倍。日志要滚动别无限增长。第二个是更新结果回执。更新器完成替换、拉起主程序后主程序启动时读一个update_result.json里面记录上次更新的结果成功/失败/回滚。如果发现上次是失败回滚的可以提示用户或上报服务端。这样你能知道有多少用户更新失败而不是等他们来投诉。第三个是灰度。清单里可以加一个Channel字段服务端按用户 ID 或设备 ID 返回不同的清单先给 5% 的用户推新版本观察几天没问题再全量。桌面端没有 Web 端那么灵活的灰度能力但靠清单分流也能做到。第四个是哈希算法的可替换。别把 MD5 写死在代码里抽一个IHashProvider接口将来要换 SHA256 或者加盐都方便。我见过一个项目哈希算法写死在十几个地方后来要换算法改到崩溃。验证更新是否成功最直接的办法是更新后重新比对一遍清单——如果所有文件哈希都一致说明更新完整。这个自检可以放在更新器最后一步不通过就触发回滚。多花几秒但能避免看起来更新成功了其实有文件没替换这种隐蔽问题。从那以后我每次做更新模块都会强制走一遍断网中断 权限不足 文件占用这三个异常场景的测试跑通了才敢发版。桌面更新的坑大多不在正常流程而在这些边角情况。希望帮到你。本文还有配套的精品资源点击获取