简介：这是一套面向.NET桌面开发者的软件自动更新解决方案源码包，适用于WinForm、WPF等客户端程序的版本迭代场景。方案核心思路是依据文件列表比对哈希值，对本地文件执行下载替换、删除与新增操作，最终启动软件本体，经作者测试可稳定实现自动更新，适合需要为自研客户端搭建升级模块的中高级开发者参考。压缩包共394个文件，约23.49MB，以79个dll动态库、35个cs源码文件、78个xml配置与文档、24个nupkg包及若干pdb、resx、csproj、sln等工程文件为主，完整保留了可编译的项目结构与依赖，便于直接还原工程并二次改造。目前已有2140人学习下载。需要提醒的是，作者已明确标注项目停止维护、不推荐使用，读者可将其作为更新机制与哈希校验思路的学习样本，结合自身技术栈重新实现，而非直接投入生产环境。
1. 桌面端自动更新为什么总在客户现场翻车
WinForm 和 WPF 这类桌面程序，交付方式跟 Web 完全两码事。Web 你发个版，用户刷新就是最新；桌面程序发出去，装在上千台内网机器上，有的还跑在没外网、没管理员权限的环境里，更新这件事就成了长期折磨。我见过太多项目，第一版靠「发个压缩包让用户自己覆盖」撑着，等到客户数量上来，运维电话就被打爆：有人覆盖到一半断电，程序起不来；有人只换了 exe 没换依赖 dll，一运行就报找不到程序集；还有人装了新版，配置文件被旧版覆盖，连接串全丢了。
软件自动更新要解决的核心就三件事：怎么知道有新版本、怎么把新版本安全拿到本地、怎么在不破坏用户数据的前提下完成替换并重启。WinForm 和 WPF 在这件事上共享同一套思路，差别主要在 UI 呈现和启动时机。这篇笔记按我实际落地的顺序讲：先定更新策略和版本清单，再写检查逻辑，然后处理下载与替换，最后把回滚和灰度这些容易忽略的环节补上。适合正在做桌面交付、被更新问题反复消耗的 C# 开发者，新手能照着搭出最小可用版本，熟手可以对照边界条件查漏。
2. 自动更新的三种落地形态与选型依据
2.1 全量替换、增量补丁、独立更新器怎么选
桌面自动更新按实现复杂度分三档，选错了后面全是坑。
全量替换是最朴素的做法：每次发版打一个完整 zip，客户端下载后解压覆盖。优点是逻辑简单、不依赖差分工具；缺点是包大，一个带 WPF 资源字典和图片的客户端轻松上百 MB，内网带宽紧张时用户体验很差。适合发版频率低（月级）、包体可控的项目。
增量补丁只下发变化的文件，靠文件哈希比对生成差量清单。带宽省得多，但要求你有一套可靠的构建产物比对流程，否则容易出现「补丁打上去文件版本对不上」的玄学问题。适合发版频繁、包体大的项目。
独立更新器（Updater）是把更新逻辑从主程序里拆出来，单独一个 exe。主程序启动时先拉起更新器，更新器检查、下载、替换，完成后启动主程序。这么做的好处是：主程序正在运行的文件被占用时无法自我覆盖，而更新器是独立进程，可以安全替换主程序目录下的文件。这是 WinForm/WPF 生产环境里最稳的形态，我一般首选它。
| 形态 | 包体开销 | 实现难度 | 适用场景 |
|---|---|---|---|
| 全量替换 | 大 | 低 | 低频发版、小包体 |
| 增量补丁 | 小 | 高 | 高频发版、大包体 |
| 独立更新器 | 中 | 中 | 生产环境通用 |
2.2 版本清单文件该放哪些字段
不管哪种形态，服务端都要维护一份版本清单（manifest），客户端拉取后决定要不要更新。清单字段设计直接决定后面逻辑顺不顺。我常用的字段如下：
| 字段 | 类型 | 说明 |
|---|---|---|
| version | string | 语义化版本，如 2.3.1 |
| minVersion | string | 低于此版本必须强制更新 |
| packageUrl | string | 全量包地址 |
| packageHash | string | 包的 SHA256，校验完整性 |
| files | array | 增量模式下每个文件的相对路径与哈希 |
| forceUpdate | bool | 是否强制更新 |
| releaseNote | string | 更新说明，展示给用户 |
minVersion这个字段很多人不加，结果遇到必须强制升级的破坏性变更时没法处理。packageHash是防下载损坏和防篡改的第一道关，别省。
2.3 检查时机：启动检查还是定时轮询
检查时机决定用户感知。常见做法有两种：启动时检查一次，以及运行中定时轮询。
启动检查最简单，用户打开程序就知道有没有新版，适合大多数内部系统。定时轮询适合长时间不关闭的客户端（比如挂在工位上的看板程序），但要注意别在用户正在操作时弹窗打断，我一般把轮询结果先缓存，等用户空闲或下次启动再提示。
WPF 项目里如果用了 MVVM，检查逻辑放在 ViewModel 之外的独立服务类里，通过command或事件通知界面，别把网络请求写进 ViewModel，否则单元测试很难写。WinForm 项目里同理，检查逻辑封装成独立类，窗体只负责展示。
3. 用 C# 写一个能跑通的版本检查与下载模块
3.1 版本比较：别用字符串直接比大小
版本号比较是第一个容易翻车的地方。"2.10.0" > "2.9.0"用字符串比较会得到错误结果，因为字符'1'小于'9'。必须按段拆成整数比。
// 语义化版本比较：逐段转 int 比较，避免字符串比较的坑 public static int CompareVersion(string v1, string v2) { var parts1 = v1.Split('.').Select(p => int.TryParse(p, out var n) ? n : 0).ToArray(); var parts2 = v2.Split('.').Select(p => int.TryParse(p, out var n) ? n : 0).ToArray(); int len = Math.Max(parts1.Length, parts2.Length); for (int i = 0; i < len; i++) { int a = i < parts1.Length ? parts1[i] : 0; int b = i < parts2.Length ? parts2[i] : 0; if (a != b) return a.CompareTo(b); } return 0; // 相等 }逻辑说明：把2.10.0拆成[2,10,0]，逐段转整数比较，缺位补 0。这样2.10.0和2.9.0比出来是正数，符合预期。参数上要注意版本号里如果混了-beta这类后缀，int.TryParse会失败，我上面用out var n兜底成 0，正式项目里建议把预发布标识单独解析，别混在主版本段里。
3.2 拉取清单并判断是否需要更新
// 从服务端拉取版本清单，与本地版本比较 public async Task<UpdateInfo> CheckUpdateAsync(string manifestUrl, string localVersion) { using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(10) }; // 加时间戳参数，绕过 CDN 或代理缓存 var url = $"{manifestUrl}?t={DateTimeOffset.UtcNow.ToUnixTimeSeconds()}"; var json = await http.GetStringAsync(url); var manifest = JsonSerializer.Deserialize<UpdateInfo>(json); if (CompareVersion(manifest.Version, localVersion) <= 0) return null; // 已是最新 // 低于最低支持版本，强制更新 manifest.ForceUpdate = manifest.ForceUpdate || CompareVersion(localVersion, manifest.MinVersion) < 0; return manifest; }逻辑说明：HttpClient设 10 秒超时，避免网络不通时界面卡死。URL 拼时间戳是为了绕过中间层缓存，这个坑我在内网代理环境里踩过——清单更新了但客户端一直拿到旧缓存。CompareVersion返回小于等于 0 说明本地不落后，直接返回 null。强制更新判断里，只要本地版本低于minVersion，无论服务端forceUpdate是什么都强制。
参数说明：manifestUrl建议走 HTTPS；Timeout按内网实际情况调，太短会误判超时，太长用户等得烦。
3.3 下载、校验、替换的完整流程
下载要带进度回调，替换要处理文件占用。核心流程是：下载到临时目录 → 校验哈希 → 关闭主程序 → 更新器替换 → 重启。
// 下载更新包并校验 SHA256 public async Task<bool> DownloadAsync(string url, string savePath, string expectedHash, IProgress<double> progress) { using var http = new HttpClient(); using var resp = await http.GetAsync(url, HttpCompletionOption.ResponseHeadersRead); resp.EnsureSuccessStatusCode(); var total = resp.Content.Headers.ContentLength ?? -1L; await using var src = await resp.Content.ReadAsStreamAsync(); await using var dst = File.Create(savePath); var buffer = new byte[81920]; long read = 0; int n; while ((n = await src.ReadAsync(buffer)) > 0) { await dst.WriteAsync(buffer.AsMemory(0, n)); read += n; if (total > 0) progress?.Report((double)read / total); } dst.Close(); // 校验哈希，防止下载损坏或被篡改 using var sha = SHA256.Create(); await using var fs = File.OpenRead(savePath); var hash = Convert.ToHexString(await sha.ComputeHashAsync(fs)); return hash.Equals(expectedHash, StringComparison.OrdinalIgnoreCase); }逻辑说明：用ResponseHeadersRead先拿到响应头再流式读取，避免大文件一次性读进内存。缓冲区 81920 字节是 .NET 流复制的常用值，兼顾吞吐和内存。下载完立刻算 SHA256 和清单里的值比对，不一致就丢弃重下。参数上expectedHash必须来自可信清单，别从同一个下载源拿，否则校验形同虚设。
替换阶段的关键是：主程序退出前把更新器进程拉起来，更新器等待主进程退出后替换文件。WinForm/WPF 里可以用Process.Start启动更新器，然后Application.Current.Shutdown()或Application.Exit()。
4. 更新器进程与文件替换的避坑清单
4.1 文件被占用导致替换失败
现象：更新器替换 dll 时报「文件正被另一进程使用」。
原因：主程序虽然调了退出，但进程还没完全结束，或者有后台线程、日志句柄没释放。
解决：更新器启动后先轮询等待主进程退出（按进程名或 PID），确认退出后再替换；替换前对目标文件做一次可写检测，失败就重试几次。日志文件、数据库连接这类句柄，主程序退出前要显式关闭。
4.2 更新到一半断电，程序起不来
现象：客户现场断电，重启后程序报错无法启动。
原因：直接覆盖原文件，替换到一半中断，目录里新旧文件混杂。
解决：采用「先解压到新目录，再切换」的策略。把新版本解压到app_new，全部就绪后把app改名成app_old，app_new改名成app，最后删app_old。目录改名是原子操作，比逐个文件覆盖安全得多。这就是后悔药，出问题还能切回app_old。
4.3 配置文件被新版覆盖
现象：更新后用户的连接串、授权信息全没了。
原因：全量包把config目录一起打包覆盖了。
解决：打包时排除用户数据目录（配置、日志、缓存），更新器替换时也跳过这些路径。清单里明确区分「程序文件」和「用户数据」，只替换程序文件。
4.4 内网无外网导致检查失败
现象：客户端在纯内网环境，检查更新一直超时。
原因：清单地址配的是公网域名。
解决：清单和包都部署在内网可达的服务器上，地址走内网 IP 或内网域名。如果确实需要跨网，提前和运维确认网络策略，别等上线才发现。
4.5 强制更新把用户锁死
现象：强制更新后下载失败，用户既用不了旧版也升不了新版。
原因：强制更新逻辑没留退路，下载失败直接退出程序。
解决：强制更新也要保证「下载成功才阻止使用」，下载失败时给出明确提示和重试入口，必要时允许临时使用旧版并记录告警。别把用户逼到死角。
5. 灰度发布与回滚：让更新可控的两个技巧
5.1 用清单里的灰度字段控制放量
全量推送风险大，一个 bug 可能让所有客户端同时挂掉。我一般会在清单里加一个灰度字段，按客户端标识（机器名哈希或用户 ID 哈希）决定是否推送。
// 按客户端标识哈希做灰度：只有落在比例内的客户端才收到更新 public static bool InGrayScale(string clientId, int percent) { if (percent >= 100) return true; if (percent <= 0) return false; // 用稳定哈希，保证同一客户端每次判断结果一致 using var md5 = MD5.Create(); var bytes = md5.ComputeHash(Encoding.UTF8.GetBytes(clientId)); int bucket = BitConverter.ToInt32(bytes, 0) & 0x7FFFFFFF; return bucket % 100 < percent; }逻辑说明：对客户端标识做 MD5，取前四字节转成正整数，对 100 取模得到 0-99 的桶号，小于灰度比例就命中。用稳定哈希是为了让同一台机器每次判断结果一致，否则用户一会收到更新一会收不到，体验很怪。参数percent从 5 开始，观察一两天没问题再逐步放大到 100。
5.2 保留上一版本目录做快速回滚
回滚能力是自动更新方案成熟度的分水岭。做法很简单：替换时把旧目录改名保留而不是删除，新版本启动后如果连续几次启动失败（比如启动时写个心跳标记，成功启动后清除），更新器就自动切回旧目录。
// 启动失败计数：连续失败达到阈值则触发回滚 public static void MarkStartupAttempt(string appDir) { var flag = Path.Combine(appDir, "startup.flag"); int count = File.Exists(flag) ? int.Parse(File.ReadAllText(flag)) : 0; count++; File.WriteAllText(flag, count.ToString()); if (count >= 3) { // 触发回滚：把 app_old 换回来 Rollback(appDir); } } // 启动成功后清除标记 public static void MarkStartupSuccess(string appDir) { var flag = Path.Combine(appDir, "startup.flag"); if (File.Exists(flag)) File.Delete(flag); }逻辑说明：程序启动时先调MarkStartupAttempt累加计数，初始化完成、主窗口显示后调MarkStartupSuccess清除。如果连续三次都没走到成功那一步，说明新版有问题，Rollback把app_old换回来。阈值 3 是我常用的值，太小容易误判（比如用户手动杀进程），太大回滚不及时。
这套机制配合灰度，基本能把更新事故的影响面控制住。我自己吃过亏：早期没做回滚，一次发版有个依赖没打进去，几百台机器同时起不来，运维挨个远程处理，搞了一整天。从那以后，回滚和灰度成了我每个桌面项目的标配，宁可多写两百行代码，也不赌一次发版不出错。希望帮到你。
本文还有配套的精品资源，点击获取
