简介面向 .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 ListUpdateFile 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.DeserializeUpdateManifest(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 Taskbool DownloadAndVerifyAsync(UpdateFile item, string stagingDir, IProgressdouble? 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 ListUpdateFile(); 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_dirdist/$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 取 sizesha256sum 算哈希jq 把每条记录整理成清单里的一个文件对象。所有路径都按相对路径输出url 统一拼成https://your-server/updates/{version}/{path}格式。这个脚本还缺一个步骤需要把打包好的版本目录连同 manifest.json 一起上传到静态服务然后修改服务端的 currentVersion。发布时我只跑脚本不再手动改任何 JSON。清单里的 minVersion 是发布策略通常只在有大版本不兼容时调整平时固定不变。5. C# 自动更新程序避坑5 个高频故障的排查与处理自动更新代码写完后真正考验人的是部署运行阶段。下面这 5 个故障是我在不同项目里反复踩过的每一条都按“现象、原因、解决”列出排查时可以直接对照。5.1 更新日志显示成功但重启后版本号还是旧的现象Updater 日志里已经打印 apply_successupdate.status 文件也写成了 applied但用户重启后运行的程序版本依旧。原因替换文件时主进程并没有完全退出进程句柄还占着 exe 或 DLLFile.Move 并没有真的覆盖成功。在 Windows 上文件被独占时 Move 会抛异常但很多实现里异常被吞掉只记录了继续执行的状态。解决替换前必须先确认主进程退出不能用“休眠几秒”代替。我会在主程序退出前写一个退出标记文件Updater 循环检查该标记直到消失再开始替换如果进程还活着直接按进程名结束然后等两秒确认句柄释放。回滚逻辑也要在替换失败时真实执行不能只打印一行错误。5.2 清单里的 SHA256 永远校验不过现象同一个文件下载到本地手动算出的哈希和清单里写的不一致重新下载依旧不一致。原因通常有三个一是生成清单时用文本编辑器手动改过文件换行符变化导致哈希变了二是客户端计算哈希时没有用二进制读取模式三是服务端 CDN 或代理缓存了旧文件。解决客户端统一用 File.OpenRead 加 SHA256.ComputeHashAsyncServer 端生成清单也基于同一个构建产物不经过任何文本转换。发布清单后做一次端到端验证从下载 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、rollbackresult 是 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确认新旧版本比例符合预期且新增错误日志没有明显上升。回滚和灰度两者配合起来自动更新才不算黑匣子。我的习惯是每次全量发布前先让内部环境跑一整天灰度看过错误日志没有明显增长后才会放心把版本放出去。自动更新这道工序一旦变得可验证你才会真正愿意把它用到生产环境里希望这篇对你有帮助。本文还有配套的精品资源点击获取
