简介面向Winform、WPF等桌面客户端开发者的软件自动更新解决方案核心思路是按文件列表逐一比对哈希值仅对变更内容执行下载替换、删除或新增操作完成后重新拉起主程序实现自动升级。针对需要频繁发布补丁、文件数量较多的桌面应用该方案提供了一条可落地的增量更新路径。整套资源共394个文件、约23.49MB从文件构成看包含cs源码、dll程序集、xml配置说明、nupkg依赖包、pdb调试符号、exe启动示例等覆盖了从代码实现、依赖管理到编译输出的完整环节。需要提醒的是作者已声明项目停止维护、不建议直接用于生产环境但其更新流程和哈希校验逻辑经过实际测试仍可作为自研更新模块的参考实现。目前已有2135人学习下载适合想了解桌面端增量更新机制、正在设计自动升级功能的开发者参考与改造。1. WinForms 与 WPF 的自动更新先看更新器要解决什么WinForms 和 WPF 桌面软件的自动更新翻车常不在“下载”而在“运行时替换正在被占用的 exe/dll”。直接在主程序启动路径里写File.Copy等窗口和控件库加载完再去覆盖同名程序集多半会抛“正由另一进程使用”用户看到的就是白屏。正确路线是先下后换主程序检查版本、下载到暂存区再启动独立更新器进程更新器等主程序退出后替换文件最后拉起新版。标题里的 Winfrom 是日常拼写实际指 WinForms两者 UI 生命周期有差异更新链路可复用同一套。下面的实现按我维护 WinForms 老项目和 WPF/MVVM 上位机工具时落地过的套路来写适合要给软件加自动更新的 .NET 开发者。2. 选型ClickOnce、Squirrel 还是自研更新器WinForms/WPF 各取所需桌面自动更新方案很多真正需要决定的不是“用哪个库”而是“允许文件系统里出现多深的目录结构、回滚怎么做”。先给一张常见选型参考表后面按自研路线展开。2.1 三条路线在 WinForms 与 WPF 下的真实边界方案更新包形态运行目录特征更适用于ClickOnce发布清单 部署清单位于用户 AppData/Apps/2.0 深层目录内部小工具、改动少、不追求自定义安装体验Squirrel.Windows / VelopackNuGet 包生成安装器与 delta 更新安装器引导之后跑在主程序目录新起 WPF 项目、想要快捷方式和完整安装流程AutoUpdater.NETJSON 清单 单个升级包原安装目录库内直接完成老 WinForms 工程改动面越小越好自研更新器HTTP 静态资源 zip/文件列表用户可写目录或 Program Files 加 UAC要控制回滚、渠道、离线包和内网分发ClickOnce 对 WPF 也能用缺点是回滚和自定义。发布新版本靠提升部署清单版本号想退回旧版得先改服务端清单内部团队用可以面向外部用户时体验很一般。Squirrel.Windows 已经归档Velopack 是接棒者适合新 WPF 项目不过涉及自定义安装位置和离线包时需要自己维护打包脚本CI 上要额外跑一遍打包任务。AutoUpdater.NET 更适合老工程“嵌入式”用法把库拖进去调用 API 即可但断点续传、分渠道灰度这些能力都要自己补。所以我通常会选自研。自研不等于从零造轮子而是把更新器拆成“检查、下载、替换”三个独立块每块都能单独测试出问题时能定位到具体环节。2.2 自研更新器的运行时序与目录约定我把目录统一放在%LocalAppData%\YourApp下而不是 Program Files。这样做的好处是普通用户权限即可读写后续替换不用每回都弹 UAC。C:\Users\dev\AppData\Local\YourApp\ ├─ run\ # 当前运行目录exe、dll 都在这 ├─ staging\ # 下载并解压的新版本 └─ backup\ # 被替换前的旧版本快照staging、run、backup 三个目录在同一磁盘卷下方便用Directory.Move做目录交换这是后文替换逻辑的基础。运行时序固定为五步主程序启动检查清单把新版本下载到 staging启动独立的 Updater.exe传参告知源目录、目标目录和旧进程 PID主程序立即退出Updater 等待旧进程结束后替换 run 目录最后拉起新版本。这个顺序的关键点是“下载期间主程序照常运行替换动作只在进程退出后发生”。如果更新内容只是配置文件、图片、SQLite 这类数据文件不一定要独立进程一旦带 dll/exe就必须走这一步。WinForms 和 WPF 都适用区别主要在 UI 线程退出时资源是否释放干净这在第 5 章展开。3. 版本清单与差异计算WPF/WinForms 更新前的检查协议更新器第一步是知道“有没有新版本”。很多项目卡在这里拿远程版本号字符串和本地比较碰上年月日格式、四段版本号混用一下全乱。所以要先约定一个服务端生成的清单文件客户端只读它。3.1 清单结构版本号、文件列表与 SHA-256JSON 是 WinForms/WPF 项目最容易处理的格式不需要额外引入 Schema。一个最小可用的manifest.json如下{ version: 2.3.1.0, baseVersion: 2.2.0.0, minSupportVersion: 2.0.0.0, force: false, files: [ { path: bin/App.dll, size: 2097152, sha256: a94f8c...e07d, url: https://update.example.com/yourApp/2.3.1.0/bin/App.dll } ] }字段含义version是本次发布版本baseVersion表示这个增量包是从哪个版本升上来的minSupportVersion是客户端允许执行增量更新的最低版本比它老就提示用户重新安装完整版force为 true 时跳过用户确认直接更新files里列出所有需要比对的文件path用相对路径并统一正斜杠避免 Windows 反斜杠在 JSON 转义时出问题。公网环境还要考虑清单篡改HTTPS 是最低要求校验文件 SHA-256 能防下载损坏但防不了清单被整体替换。更严格的做法是服务端用私钥对version files做签名客户端内置公钥验签。内部工具可以先不做对外产品建议加上。3.2 C# 解析清单并与本地运行目录比对拿到清单后逐文件计算本地 SHA-256和远程对比产生待下载列表public async TaskListUpdateFile DiffLocalAsync( HttpClient http, string manifestUrl, string runDir, CancellationToken ct) { using var stream await http.GetStreamAsync(manifestUrl, ct); var manifest await JsonSerializer.DeserializeAsyncUpdateManifest( stream, JsonOptions, ct); var toDownload new ListUpdateFile(); foreach (var file in manifest.Files) { var localPath Path.Combine(runDir, file.Path.Replace(/, Path.DirectorySeparatorChar)); if (!File.Exists(localPath)) { toDownload.Add(file); continue; } var hash await ComputeSha256Async(localPath, ct); if (!string.Equals(hash, file.Sha256, StringComparison.OrdinalIgnoreCase)) toDownload.Add(file); } return toDownload; }这里用GetStreamAsync边下边反序列化避免整个清单在内存里放大到几十 MB逐文件比对而不是全量遍历哈希一次算完是因为断点续传后续要按文件维护状态。ComputeSha256Async实现为FileStream加SHA256.Create().ComputeHashAsync结果转十六进制字符串。哈希比较用OrdinalIgnoreCase兼容服务端可能输出大写的情况。文件多时要注意Path.Combine的路径穿越风险。远程 path 只允许相对路径检查是否包含..否则可能被恶意清单把文件写到系统目录。这个校验一定要在组合本地路径前做。3.3 增量与全量 zip 的下载策略选择场景推荐做法单个 exe 或少量 dll 变更按 files 数组逐个下载支持断点续传更新包含大量资源、语言包全量 zip 包解压后整体替换内网 wpf 上位机或工控机全量 zip 放内网 HTTP 或共享目录少做增量公网跨大版本升级按minSupportVersion判断老版本直接给全量包不建议一上来就做二进制差分。手工维护“上一版本到当前版本的 delta”列表服务端和客户端一旦不一致故障定位极难。最小更新单元是文件哪个哈希变了就下载哪个文件数量过多时改用 zip 减少 HTTP 请求数。自研方案先做文件级增量再按场景升级到全量包比一开始追求 diff 算法实用得多。4. WinForms/WPF 更新器核心流程下载、校验、备份、替换拿到待下载列表后整个流程必须按“破坏性操作放在最后”的顺序执行。以下代码在最小工程里可以直接跑通。4.1 更新前检查单实例、磁盘空间与版本约束using Mutex mutex new(true, YourApp.UpdateMutex, out bool createdNew); if (!createdNew !mutex.WaitOne(TimeSpan.FromSeconds(5))) { return; // 已有更新任务在跑避免重复下载 }Mutex 名称用“YourApp.UpdateMutex”这种全局名保证同一个应用只有一个更新流程。注意 Mutex 要显式释放否则进程退出后内核对象仍可能残留短暂时间影响下次启动。检查项判定失败处置单实例Mutex 能在 5 秒内进入放弃本次等下次启动再试磁盘剩余剩余空间 包大小 × 2 200 MB弹窗提示不进入下载版本跨度minSupportVersion大于本地版本提示重新安装完整版磁盘空间按包大小两倍预估因为替换前要保留 backup。WPF 项目常有人忽略这一步下载到一半磁盘满了staging 目录留下一个残缺文件下次更新还会在同一个位置失败。4.2 下载与校验HttpClient 处理大包public async Task DownloadFileAsync( HttpClient http, string url, string targetFile, string expectedSha256, CancellationToken ct) { Directory.CreateDirectory(Path.GetDirectoryName(targetFile)!); var tmpFile targetFile .download; using var resp await http.GetAsync(url, HttpCompletionOption.ResponseHeadersRead, ct); resp.EnsureSuccessStatusCode(); await using var src await resp.Content.ReadAsStreamAsync(ct); await using var dst new FileStream( tmpFile, FileMode.Create, FileAccess.Write, FileShare.None, 81920, true); await src.CopyToAsync(dst, ct); var actual await ComputeSha256Async(tmpFile, ct); if (!string.Equals(actual, expectedSha256, StringComparison.OrdinalIgnoreCase)) { File.Delete(tmpFile); throw new InvalidDataException($哈希校验失败: {Path.GetFileName(targetFile)}); } File.Move(tmpFile, targetFile, overwrite: true); }HttpCompletionOption.ResponseHeadersRead表示拿到响应头就开始读流不把整个响应缓冲进内存81920 是常见的高速磁盘 buffer 大小useAsync: true保证文件写入不阻塞线程。文件先写.download临时名校验通过后才File.Move成正式名避免半截文件被后续逻辑误用。校验失败就删除临时文件并抛异常外层捕获后终止本次更新而不是继续下一个文件。4.3 备份与替换分离进程、等待主进程退出主程序在完成下载后启动放置在 staging 目录里的 Updater.exe。为什么更新器要放在 staging 而不是运行目录因为运行目录马上就要被替换更新器自身不能是被换掉的文件之一。public static void StartUpdaterAndExit( string runDir, string stagingDir, string backupDir, string updaterExe, string restartExe) { int currentPid Environment.ProcessId; var psi new ProcessStartInfo { FileName Path.Combine(stagingDir, updaterExe), UseShellExecute true, Arguments $\{stagingDir}\ \{runDir}\ \{backupDir}\ {currentPid} \{restartExe}\ }; Process.Start(psi); Environment.Exit(0); }UseShellExecute true让更新器以独立进程启动不继承当前控制台主程序紧接着调用Environment.Exit(0)主动让出所有 dll 句柄。Updater.exe 内的替换逻辑是核心static int Main(string[] args) { string src args[0], dst args[1]; string backup args[2], restart args[4]; int oldPid int.Parse(args[3]); try { using var p Process.GetProcessById(oldPid); p?.WaitForExit(10_000); } catch (ArgumentException) { } if (Directory.Exists(backup)) Directory.Delete(backup, true); Directory.Move(dst, backup); // 旧版本快速离场 try { Directory.Move(src, dst); // 新版本上位 } catch { Directory.Move(backup, dst); // 回滚是恢复目录名不是复制文件 throw; } Process.Start(restart); return 0; }Directory.Move比递归复制快得多而且是同卷内的元数据操作接近原子。它要求 src 和 dst 在同一逻辑卷所以上一章的目录约定里强调 staging、run、backup 要放在同一目录树下。如果应用装在 Program Filesstaging 在另一个分区那只能退化为“复制新文件 删除旧目录”回滚也会变成复制备份回来耗时和失败率都会上升。参数解析这里的示例用了固定位置正式项目建议封装成CommandLineParse把--src、--dst这种命名参数做全。4.4 状态放到 ViewModel别把更新逻辑写进窗口后台代码WPF 项目里常见的问题是更新逻辑写在Window_Loaded里窗口关不掉、进度条刷不了。更整洁的做法是把更新器封装成IUpdateService注册进依赖注入容器ViewModel 通过异步方法调用它。Prism 项目里就是把IUpdateService注入到 ViewModel按钮能不能点用DelegateCommand.CanExecute控制。WinForms 侧没有绑定机制就用事件把进度推给 Form。这样更新流程可以脱离界面单独测试UI 只是订阅进度的一个观察者。5. 部署排错权限、DLL 占用与 WPF 资源释放的常见坑上线的自动更新问题几乎都出在部署环境。下面三个坑是按出现频率排序的。5.1 目录权限为什么最好不要把 WinForms/WPF 目标放在 Program Files安装了 Program Files 的应用普通用户进程对运行目录只有读权限。覆盖 dll/exe 必须提权游离在 UAC 之外的标准做法有三种第一首版安装时就装到%LocalAppData%\YourApp\run后续更新完全不弹 UAC。大多数公司内部分发的工具、上位机软件都适合这种。第二必须装 Program Files 时给 Updater.exe 加requestedExecutionLevelrequireAdministrator的 manifest替换前弹一次 UAC。第三staging 与 run 在不同卷时放弃Directory.Move改用复制加删除但删除动作同样需要提权。还有一个和本标题不直接相关但经常卡人的问题vs2022 中 wpf 的可选模板不见了。如果创建更新器小工具时建不了 WPF 项目多半是 Visual Studio Installer 里没勾选“.NET 桌面开发”工作负载重开安装器补上即可和更新器代码本身无关。5.2 DLL 占用WPF 资源句柄与程序集加载进程退出后仍无法替换文件最常见原因是 WPF 应用没有真正退出。比如窗口关了但有个非后台线程在监听命名管道或者DispatcherTimer没停进程就一直活着。Environment.Exit(0)能强制终止但会跳过正常的保存逻辑不适合主程序自己调用。更新器侧的策略是等待加确认WaitForExit超时后检查目标 exe 是否仍存在如果被占用尝试CloseMainWindow给主程序一次善后机会再等几秒仍不行就把错误写进日志保留 staging 和 backup 目录等待下次开机重试。不要直接Process.Kill那会把用户未保存的数据丢掉。另一个相关细节是公共控件库。如果主程序和更新器同时加载了同一个 wpf 控件库 dll更新器自身也会占用该文件。所以在设计上Updater.exe 尽量只依赖标准类库不引用任何业务 UI 组件。启动更新器时把它放在 staging 目录内就是避免它和待替换文件同目录互相锁。5.3 代码签名与杀软误报 应对自研更新器很容易被杀软误报。无签名 exe 下载 zip、解压、替换其他 exe这套行为组合和常见下载者的特征太像了。误报类型常见触发点处理建议无签名下载器更新器不带证书执行下载并运行主程序和更新器都做 Authenticode 签名解压释放可执行文件运行时从临时目录释放 dll 再加载不用“释放到临时目录再执行”的模式改为直接解压到 staging内网大批量相同文件同版本 exe 在企业网内大量分发签名后加入企业证书白名单验证签名最简单的方式是 PowerShellGet-AuthenticodeSignature -FilePath C:\YourApp\Updater.exe | Select-Object Status, StatusMessageStatus为Valid说明证书链完整UnknownError或NotSigned就要回到签名环节。自签名证书能通过Get-AuthenticodeSignature但 SmartScreen 仍然会显示“未知发布者”。外网产品用商业证书内网分发用企业内部 CA 证书并下发到客户端受信任列表这才是完整解法。6. 静默更新与版本回滚WinForms/WPF 自动更新的最后一道保险6.1 用版本目录和 current.txt 做启动前回滚把第 4 章的目录交换升级成多版本目录回滚成本会进一步降低。结构变成versions\2.3.1.0\、versions\2.3.2.0\启动器只读versions\current.txt决定跑哪个版本string ver File.ReadAllText(Path.Combine(baseDir, versions, current.txt)).Trim(); Process.Start(Path.Combine(baseDir, versions, ver, YourApp.exe));写current.txt时先写临时文件再File.Move(overwrite: true)避免启动器读到半个版本号。新版本第一次启动成功后由主程序回写一个ok标记更新器发现标记才删除旧版本目录第一次启动失败或 exit code 非 0更新器把current.txt指回上一个版本并重启。这个方案保留了 1 到 2 个旧版本换来了“回滚是改一行文本”的效果。6.2 静默下载的 UI 细节与最后一步检查WPF 上位机更新经常会用到无人值守场景。下载线程用await异步执行进度通过IProgressdouble回传ViewModel 里只绑定ProgressValue和StatusText。按钮是否可点由DelegateCommand.CanExecute控制下载中禁止再次触发更新。UI 线程不再直接做 I/O窗口的Dispatcher不会被大文件下载卡住。最后建议在更新器替换完成后于 run 目录写入update.ok标记文件。新版本主程序启动后主动检查并删除这个标记同时把 staging 里残留的更新包清掉避免磁盘被重复堆积。这样整条链路从检查、下载、替换到回滚都变成了可追踪的状态WinForms 和 WPF 项目都能按同一套目录约定落地后续加渠道控制或灰度发布时也不会推翻重来。本文还有配套的精品资源点击获取