简介：面向 .NET 开发者的 C# 自动更新程序源码，基于 .NET 2.0 并借助 IIS 等 Web 服务，解决客户端程序远程版本检测与自动升级的问题。整套源码包含服务端与客户端两大部分：XmlUpdate 负责扫描服务端目录并生成所有文件及目录的 MD5 校验信息，AutoUpdateClient 完成更新逻辑，并通过批处理实现客户端自身的覆盖更新，形成可实际落地的更新闭环。包内共 55 个文件，以 cs 源码、csproj/sln 工程文件、resx/resources 资源文件为主，同时包含可执行 exe、调试符号 pdb、配置文件及说明文档；整体压缩包约 494KB，结构清晰，适合学习和二次开发。目前已有 735 人浏览学习。通过该源码可以掌握生成文件 MD5 清单、Web 端部署更新包、客户端对比校验与下载安装等关键环节，尤其适合需要为自家软件快速加入自动更新能力的中级 .NET 开发者参考。
1. C# 自动更新程序源码：客户端软件最不该省的那块拼图
给生产部门用的内部工具升一次级，最怕的不是改代码，而是让几十台电脑在同一周内都用上新版。有人进程没关，有人文件被占用，有人下载到一半就关了机器，最后还要挨个远程处理。做这种交付的人大多会得出同一个结论：与其反复折腾，不如把 C# 自动更新程序源码这一套能力提前做进客户端，让版本检查、下载、校验、替换、回滚全部自动化。它解决的问题很聚焦：程序装上之后，还能安全地把自身换掉。本文会把这套源码里的架构选型、核心代码、参数配置和真实故障拆开讲一遍。适合桌面端工具、企业内部系统、工业上位机这类需要长期迭代但不想养复杂后台的场景。不需要数据库，不需要专门服务端，一个静态文件目录就能跑起来。
2. C# 自动更新程序源码的架构选型：全量包、增量补丁与启动器分离
不要把自动更新想成“把压缩包下载下来解压覆盖”。从用户点下“检查更新”到新版本真正跑起来，中间至少经过版本检查、下载、校验、备份、替换、重启六个动作，任一个环节考虑不到位，上线就是事故。这章先把两个关键决策讲清楚：更新包做全量还是增量，更新器放在主程序里还是拆成独立进程。选型定了，后面写代码才不会返工。
2.1 全量包与增量补丁：三张牌怎么打
我多数场景的默认选择是全量包。理由很简单：打包复杂度低，失败好恢复，对客户端当前版本的依赖也最小。对大多数 C# 桌面端来说，应用目录里的程序、依赖库和资源文件打包出来通常也就几十兆，全量分发成本可以接受。只有当包明显变大、用户网络又慢或流量敏感时，增量补丁才值得做。
下面这个对比表是我在给不同项目选型时常用的判断依据：
| 对比维度 | 全量包 | 增量补丁 |
|---|---|---|
| 包体大小 | 整个应用目录，通常几十 MB | 只有变化文件，可能小到几百 KB |
| 服务端要求 | 一个静态目录加 JSON 清单 | 需要维护基准版本和差分产物 |
| 客户端要求 | 任意旧版本都能升到最新 | 客户端版本必须与基准版本一致，否则补丁失效 |
| 出错恢复 | 某个文件坏了下一次重下载该文件即可 | 基准对不上时只能整包重来 |
| 适用场景 | 内网工具、中小型桌面端 | 公网客户端、大体积资源包 |
我的经验数字是：更新包 50 MB 以内直接全量；超过 100 MB 且更新频率高，再考虑增量。许多项目走到增量才发现额外成本：每个“基准版本不一致”的用户都要单独处理，服务端要保留多个历史构建，发布流程复杂度明显上升。再一个容易忽略的点是，清单里的 size 字段别省。SHA256 能发现文件被改过或传错，但网络截断导致文件不完整时，连哈希都算不完，直接靠 Content-Length 和清单 size 对比就能第一时间淘汰坏文件。所以我把 size 和 sha256 看成前后两道闸门，缺一个都容易把问题拖到最后一步才暴露。
2.2 为什么更新器必须拆成独立进程
这是 C# 自动更新程序源码里最重要的一条架构约束。主程序不能替换自己，运行中的 exe 和相关 DLL 被系统占用，直接覆盖大概率失败。就算强删成功，正在执行的代码路径也已经被加载进内存，状态没法干净回收。所以常见做法是把更新逻辑拆成一个独立的 Updater 进程，它不承载业务逻辑，只负责备份、替换、启动主程序。
两个进程的职责边界我一般这样划分：主程序只做版本检查、下载、校验和用户提示，下载完成后把文件放到暂存目录，拉起 Updater 后自行退出；Updater 负责等待主进程彻底退出，再执行文件替换，最后启动主程序。业务主程序不碰替换逻辑，Updater 也不去理解业务数据结构，两者靠约定好的文件和目录通信。
拆成独立进程还有一个实际好处：主程序崩溃不影响更新完成。比如新版本下载好了但用户一直没重启，这时主程序因为别的 bug 闪退，用户再打开时，启动器可以检测到暂存区里存在完整的新版本，直接走一次替换流程，把用户救回来。把更新逻辑塞在主程序里的方案很难做到这点，主程序挂了，更新也跟着一起断。另外，主程序如果不小心有权限问题或长期被占用，更新器至少是个干净的环境，替换失败还能拿到准确异常。
2.3 服务端最小形态：静态目录加 manifest.json
很多团队一上来就设计更新管理系统、数据库、后台管理页面，最后发现发布频率根本用不上。自动更新最可靠的服务端形态反而是一个静态文件服务，内网 Web 目录、云存储桶都可以。服务端只需要提供两样东西：版本清单文件，和对应的版本文件目录。
清单文件我固定命名为 manifest.json，内容如下：
{ "appId": "demo-tool", "currentVersion": "1.4.2", "minVersion": "1.2.0", "forceUpdate": false, "files": [ { "path": "bin/demo-tool.exe", "size": 885120, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "url": "https://your-server/updates/1.4.2/bin/demo-tool.exe" }, { "path": "config/appsettings.json", "size": 2048, "sha256": "60303ae22b998861a4bca71c5b6e4e2f5c7b2d5e6b7c9d0e1f2a3b4c5d6e7f8a9", "url": "https://your-server/updates/1.4.2/config/appsettings.json" } ] }字段说明：appId 用来防止客户端拿错清单，多产品共用同一套更新服务时尤其重要；currentVersion 是服务端认为的最新版本；minVersion 是能继续使用的最低版本，低于它就必须强制更新；forceUpdate 控制旧版本用户是否阻断进入主界面；files 数组里的 path 是相对应用根目录的安装路径，url 是下载地址，size 和 sha256 用于下载后的完整性校验。
把这两块拆开是有原因的：某些项目喜欢让服务端根据客户端版本动态返回最优清单，但对小团队来说，静态文件足够，而且更容易排查问题。更新服务挂掉时，客户端只是“检不到新版本”，主程序照常运行，不存在单点依赖。需要发布新版本时，把文件传上去、改一下 currentVersion，发布流程就结束了。
3. 手写 C# 自动更新器源码：从 JSON 清单到原子替换的完整路径
网上能找到不少现成的自动更新组件，但我建议至少自己把核心逻辑写一遍。真正会在生产环境出问题的，往往集中在三块：清单解析、下载校验、备份替换。把这三块代码握在自己手里，遇到故障才能快速定位。这章给出的代码是可以直接接进项目的骨架，业务项目只需要照着调整路径和参数。
3.1 定义清单数据结构：让下载与校验都有依据
C# 端定义与 JSON 一一对应的模型类，解析用自带的 System.Text.Json 即可：
public class UpdateManifest { public string AppId { get; set; } = ""; public string CurrentVersion { get; set; } = ""; public string MinVersion { get; set; } = ""; public bool ForceUpdate { get; set; } public List<UpdateFile> Files { get; set; } = new(); } public class UpdateFile { public string Path { get; set; } = ""; public long Size { get; set; } public string Sha256 { get; set; } = ""; }解析代码：
var manifest = JsonSerializer.Deserialize<UpdateManifest>(jsonString, new JsonSerializerOptions { PropertyNameCaseInsensitive = true }); if (manifest == null || manifest.Files.Count == 0) { throw new InvalidDataException("manifest is empty"); }这里的 Path 是相对应用根目录的路径，客户端拿到后把它映射成实际磁盘路径。Size 和 Sha256 不能省，size 做第一道快速校验，sha256 做最终完整性确认。URL 字段我没有放进模型里，理由是从 manifest 里拿到的文件相对路径可以拼到下载地址上，少一份字段就少一处可能写错。
3.2 下载与 SHA256 校验：下载到临时文件再校验
下载和校验我分开做，先下载到临时文件，再计算哈希，最后再移到正式的暂存目录。这样做的好处是文件损坏时能明确区分是下载问题还是校验问题。直接流式计算哈希虽然省一次磁盘 IO，但下载中途崩溃时谁都说不清文件是半截还是完整。
public static async Task<bool> DownloadAndVerifyAsync(UpdateFile item, string stagingDir, IProgress<double>? progress, CancellationToken ct) { string tmpPath = Path.Combine(stagingDir, item.Path.Replace('/', Path.DirectorySeparatorChar) + ".download"); Directory.CreateDirectory(Path.GetDirectoryName(tmpPath)!); using (var http = new HttpClient { Timeout = TimeSpan.FromMinutes(30) }) { using var resp = await http.GetAsync(GetDownloadUrl(item), HttpCompletionOption.ResponseHeadersRead, ct); resp.EnsureSuccessStatusCode(); if (resp.Content.Headers.ContentLength is long len && len != item.Size) { return false; } await using var fs = File.Create(tmpPath); await resp.Content.CopyToAsync(fs, ct); } await using var verify = File.OpenRead(tmpPath); if (verify.Length != item.Size) { return false; } using var sha = SHA256.Create(); byte[] hash = await sha.ComputeHashAsync(verify, ct); if (!Convert.ToHexString(hash).Equals(item.Sha256, StringComparison.OrdinalIgnoreCase)) { File.Delete(tmpPath); return false; } string target = Path.Combine(stagingDir, item.Path.Replace('/', Path.DirectorySeparatorChar)); File.Move(tmpPath, target, overwrite: true); return true; }参数说明：超时设 30 分钟偏保守，内网下载几十 MB 通常几十秒内完成，公网弱网环境需要这个余量；Content-Length 与清单 size 不等时直接返回 false，省掉后面一次完整哈希计算；计算哈希前再次比对 Length，是因为下载结束后文件可能被外部干预，多一次长度检查成本极低；校验失败的.download文件要删除，避免下次重复下载时读到污染文件。.download 后缀是约定，也是为了主程序或用户手动拷贝时不会误用半截文件。
3.3 备份、替换、回滚三步编排：原子替换的骨架
更新器最核心的一段代码是把暂存文件搬到应用目录，并在失败时回滚。顺序一定不能乱，我先全部备份，再逐个替换，最后写状态文件。
public bool ApplyUpdate(string appRoot, string stagingDir, string backupDir) { var updatedFiles = _manifest.Files; var replacedFiles = new List<UpdateFile>(); try { foreach (var f in updatedFiles) { string src = Path.Combine(appRoot, f.Path); if (!File.Exists(src)) continue; string dst = Path.Combine(backupDir, f.Path); Directory.CreateDirectory(Path.GetDirectoryName(dst)!); File.Copy(src, dst, overwrite: true); } foreach (var f in updatedFiles) { string staged = Path.Combine(stagingDir, f.Path); string target = Path.Combine(appRoot, f.Path); if (!File.Exists(staged)) continue; Directory.CreateDirectory(Path.GetDirectoryName(target)!); File.Move(staged, target, overwrite: true); replacedFiles.Add(f); } File.WriteAllText(Path.Combine(appRoot, "update.status"), "applied:" + _manifest.CurrentVersion); return true; } catch { foreach (var f in replacedFiles) { string backup = Path.Combine(backupDir, f.Path); string target = Path.Combine(appRoot, f.Path); if (File.Exists(backup)) File.Copy(backup, target, overwrite: true); } return false; } }逻辑说明：第一步备份用的是 File.Copy 而不是 File.Move，因为备份必须保留旧文件的完整副本，后续回滚全靠它。第二步替换用 File.Move 并带 overwrite，作用是让“移动”成为同一磁盘卷上的原子操作，新文件直接顶上。回滚只处理已完成替换的文件，避免把还没动过的文件也拷一遍。最后写 update.status 是因为主程序启动时可以通过这个文件判断上一次更新有没有落地，如果落地失败可以自动走回滚。
这里有一个常见的误用：不要用 File.Replace 做替换。File.Replace 会要求目标文件必须存在，而且对文件系统元数据要求更高，内网环境还能正常工作，公网 NTFS 权限一变就容易抛异常。File.Move 加 overwrite 已经把覆盖和替换都做掉了，语义更直接。
4. 把 C# 自动更新接到业务端：版本比较、触发策略与清单生成自动化
核心代码写完，要接进真实业务项目还需要处理三个问题：版本号怎么比较才不出错，更新检查什么时候触发，以及发布时清单怎么自动生成。这章给出的都是可直接用的参数和脚本。
4.1 版本比较：为什么“2.10.1 大于 2.9.9”用字符串会写错
直接把版本号当字符串比较是自动更新程序里翻车率最高的写法。字符串比较按字符逐位走，“2.10.1”会被判定为小于“2.9.9”，因为第一个字符相等，第二位字符 '1' 小于 '9'。客户端会一直认为自己不是最新版，反复弹更新提示。正确做法是把版本号拆成整数逐段比较。
public static int CompareVersion(string a, string b) { var left = a.Split('.'); var right = b.Split('.'); int maxLen = Math.Max(left.Length, right.Length); for (int i = 0; i < maxLen; i++) { int x = i < left.Length && int.TryParse(left[i], out var v1) ? v1 : 0; int y = i < right.Length && int.TryParse(right[i], out var v2) ? v2 : 0; if (x != y) return x.CompareTo(y); } return 0; }参数说明：Split 后用 int.TryParse 逐段转成数字，缺的段补 0，“2.10”和“2.10.0”会被视为同一版本。返回值小于 0 表示 a 比 b 老，大于 0 表示 a 比 b 新，等于 0 表示同一版本。实际调用时，用 manifest.CurrentVersion 和本地版本比较，返回小于 0 才需要更新。minVersion 字段则用于强制更新判断：本地版本小于 minVersion，不管 currentVersion 是什么，都直接进入强制更新流程。
提示：版本字符串里可能会带“v”前缀，比较前先 trim 掉首字母 v，避免解析失败。
4.2 触发策略：启动时、定时器、手动按钮三个入口
更新检查不能只做一个启动时检查。三个入口都建议保留：应用启动后延迟几秒在后台检查一次；应用运行期间由定时器周期检查；设置页面放一个手动检查按钮。这样既不会每次启动都卡界面，又能覆盖长时间不重启的机器。
private async Task StartUpdateCheckLoopAsync() { while (!_cancellation.Token.IsCancellationRequested) { try { await TryCheckAndDownloadAsync(); } catch (Exception ex) { Log.Warning(ex, "update check failed"); } await Task.Delay(TimeSpan.FromHours(_checkIntervalHours), _cancellation.Token); } }这里的关键参数是 _checkIntervalHours，我通常设 2 到 6 小时，避免服务器被频繁请求。TryCheckAndDownloadAsync 内部要先把“检查”和“下载”分开：检查更新只是拉取 manifest，下载则要等用户确认或判断是否静默更新。内网工具一般直接自动下载新版本，下载完成后再提示重启；公网软件则看 forceUpdate，为 true 时直接下载并强制重启，为 false 时只在用户点击“更新”按钮时才开始下载。下载过程要放在后台线程，界面上只显示进度，不能阻塞 UI。
我习惯再加一层本地缓存：把上次检查时间存到本地文件，距上次检查不足 10 分钟时直接跳过。这个参数可以防止用户在设置页反复点“检查更新”，也能避免多开几个实例时同时请求服务端。
4.3 清单生成脚本：把 SHA256 和 size 交给发布流程
手动写 manifest 或者手工算 SHA256 都不可靠，发布时用脚本自动生成。我在 CI 里放了一段 bash 脚本，把 dist 目录下所有文件扫描一遍，生成清单：
#!/usr/bin/env bash set -euo pipefail version="${1:?usage: gen_manifest.sh <version>}" dist_dir="dist/$version" find "$dist_dir" -type f -print0 | while IFS= read -r -d '' f; do rel="${f#$dist_dir/}" size=$(stat -c %s "$f") sha=$(sha256sum "$f" | awk '{print $1}') jq -n --arg path "$rel" --arg size "$size" --arg sha "$sha" \ '{path:$path, size:($size|tonumber), sha256:$sha, url:("https://your-server/updates/'"$version"'/" + $path)}' done | jq -s '{appId:"demo-tool", currentVersion:"'"$version"'", minVersion:"1.0.0", forceUpdate:false, files:.}' \ > "$dist_dir/manifest.json"逻辑说明：find 遍历发布目录按字节读取文件，stat 取 size，sha256sum 算哈希，jq 把每条记录整理成清单里的一个文件对象。所有路径都按相对路径输出，url 统一拼成https://your-server/updates/{version}/{path}格式。这个脚本还缺一个步骤：需要把打包好的版本目录连同 manifest.json 一起上传到静态服务，然后修改服务端的 currentVersion。发布时我只跑脚本，不再手动改任何 JSON。清单里的 minVersion 是发布策略，通常只在有大版本不兼容时调整，平时固定不变。
5. C# 自动更新程序避坑：5 个高频故障的排查与处理
自动更新代码写完后，真正考验人的是部署运行阶段。下面这 5 个故障是我在不同项目里反复踩过的，每一条都按“现象、原因、解决”列出，排查时可以直接对照。
5.1 更新日志显示成功，但重启后版本号还是旧的
现象：Updater 日志里已经打印 apply_success，update.status 文件也写成了 applied，但用户重启后运行的程序版本依旧。原因：替换文件时主进程并没有完全退出，进程句柄还占着 exe 或 DLL，File.Move 并没有真的覆盖成功。在 Windows 上，文件被独占时 Move 会抛异常，但很多实现里异常被吞掉，只记录了继续执行的状态。解决：替换前必须先确认主进程退出，不能用“休眠几秒”代替。我会在主程序退出前写一个退出标记文件，Updater 循环检查该标记直到消失，再开始替换；如果进程还活着，直接按进程名结束，然后等两秒确认句柄释放。回滚逻辑也要在替换失败时真实执行，不能只打印一行错误。
5.2 清单里的 SHA256 永远校验不过
现象：同一个文件下载到本地，手动算出的哈希和清单里写的不一致，重新下载依旧不一致。原因通常有三个：一是生成清单时用文本编辑器手动改过文件，换行符变化导致哈希变了；二是客户端计算哈希时没有用二进制读取模式；三是服务端 CDN 或代理缓存了旧文件。解决：客户端统一用 File.OpenRead 加 SHA256.ComputeHashAsync，Server 端生成清单也基于同一个构建产物，不经过任何文本转换。发布清单后做一次端到端验证：从下载 URL 拉一次文件，比对哈希，通过了再对外宣称发布完成。如果代理缓存可疑，在下载请求里加时间戳参数绕过 CDN 缓存。
5.3 更新完第一次启动直接闪退，配置全部丢失
现象：新版本文件替换正常，启动时进程起来又立刻退出，用户配置和本地数据也不见了。原因大多是程序目录和数据目录混在一起，新版本把旧配置文件覆盖了，或者配置格式变化后没有做迁移逻辑。解决：把程序文件和数据文件彻底分开，程序目录只放 exe、DLL 和只读资源，用户配置、数据库、日志放到系统用户目录下。更新清单时只列程序目录文件，数据目录不进 files。如果配置 schema 确实变化，要在代码里做迁移，而不是靠删除旧配置来规避。我习惯在启动时检测配置版本号，版本不一致时自动备份旧配置并生成新配置，出问题还能换回旧配置。
5.4 客户端反复提示“有新版本”，更新完成后还在提示
现象：版本明明已经更新到 currentVersion，下次启动仍然弹出更新提示。原因大概率是版本比较逻辑写成了字符串比较，或者本地版本号读取代码有问题。比如本地版本号从 AssemblyInformationalVersion 读出来是“1.10.0”，manifest 里是“1.9.9”，字符串比较会认为 1.10.0 小于 1.9.9。解决：统一走 CompareVersion 那套整数分段比较，并且比较前把“v”前缀去掉。如果本地版本读取不到，也要在日志里打出来，不能默认版本为 0，否则永远在强制更新。另外，客户端可以在检查更新成功后把当前版本号写入本地缓存文件，作为本次跳过版本，避免弹窗重复出现。
5.5 杀毒软件把更新器或下载的 exe 直接隔离
现象：更新日志下载全部成功，Updater 却没有执行，检查发现暂存目录里的文件被杀毒软件隔离或删除。原因：更新器没有代码签名，新下载的 exe 又被标记为来自网络，杀毒软件对“下载目录下出现可执行文件并试图替换系统程序目录里的文件”这种组合高度敏感。解决：对更新器和主程序 exe 做代码签名，这是最有效的一步。内部工具环境允许的话，可以把更新目录和服务端域名加入白名单。文件名上也有讲究，我见过直接命名 update.exe 被格外关照的，改成业务品牌相关的可执行名会好一些。如果杀毒软件还是误删，就要在日志里记录隔离事件，让用户看到的是“更新失败原因：文件被安全软件拦截”，而不是无提示的静默失败。
6. 把 C# 自动更新做成可验证、可回滚、可灰度的工具
自动更新不能只看功能跑通，还要能在故障发生时定位问题。我给更新的每个阶段都写了一条结构化日志：设备号、版本号、阶段、结果、耗时。这样用户反馈异常时，可以直接从日志判断是下载失败、校验失败还是替换失败，而不是靠猜。
6.1 更新结果日志：故障要能追溯到具体设备
日志字段固定下来，后续所有数据都能汇总。一个可用的格式如下：
_log.Info("update_result device_id={DeviceId} from={OldVersion} to={NextVersion} " + "stage={Stage} result={Result} error={Error} duration_ms={DurationMs}");stage 可以是 check、download、verify、apply、rollback，result 是 success 或 failure。上线后每天看一眼 error 不为空的记录，比用户投诉后再排查高效得多。日志文件要按日期滚动，并限制单文件大小，避免持续运行几个月后把磁盘占满。
6.2 一键回滚与灰度发布的最小实现
回滚功能其实不需要单独做服务端接口，只要更新时每个版本保留一份备份目录，然后提供一个回滚入口。我在设置页放一个“回滚到上一版本”按钮，点击后写一个 rollback 标记文件，下次启动时启动器检测到标记，把最新的备份目录拷贝回程序目录，然后删除标记。这样用户升级后发现新版本有问题，可以自己回到旧版，不需要拍着同事的肩膀去现场处理。
灰度发布的最小实现也简单，按设备号稳定哈希取模，决定是否进入新版本池。代码只有几行：
public static bool IsInGrayBucket(string deviceId, int bucketPercent) { int hash = 17; foreach (char c in deviceId) { hash = (hash * 31 + c) % 100000; } return hash % 100 < bucketPercent; }说明：deviceId 必须用参与稳定字段，比如机器码或用户标识，不能用随机数，否则客户端每次启动会进入不同分组。bucketPercent 是灰度比例，5 就表示 5% 的设备先收到新版本，观察一天日志确认没有异常，再把比例提高到 50，最后才全量发布。灰度期间要对照更新日志里的 from 和 to，确认新旧版本比例符合预期，且新增错误日志没有明显上升。回滚和灰度两者配合起来，自动更新才不算黑匣子。我的习惯是每次全量发布前先让内部环境跑一整天灰度，看过错误日志没有明显增长后才会放心把版本放出去。自动更新这道工序一旦变得可验证，你才会真正愿意把它用到生产环境里；希望这篇对你有帮助。
本文还有配套的精品资源，点击获取
