一个 WPF 设备管理程序,开发机上双击就开。发给客户,第一台提示「必须安装 .NET Desktop Runtime」;第二台被 SmartScreen 拦住;第三台装上了,但客户嫌安装包一百多兆;第四台能开,改完设置一重启就丢——配置写在了 Program Files 下的安装目录,普通用户没有写权限。
四个现场指向同一件事:构建成功不等于能交付。运行时怎么带、文件怎么摆、装到哪里、有没有签名、升级怎么覆盖,这些决定在业务代码写完之后才被想起,却恰恰是客户最先撞上的部分。
这篇从源码走到客户机器双击:两种运行时带法、具体发布命令与真实结果、单文件和原生依赖的副作用、安装器取舍、目录权限、代码签名、版本升级。版本按 .NET 8 的 WPF 讲。本机 SDK 8.0.427 下实际发布过:框架依赖 5 个文件、169.2 KB;自包含 -r win-x64 464 个文件、163,850.8 KB(约 160 MB)。MSIX 打包和代码签名缺少证书与环境,仍未验证。
现场:交付期才暴露的四件事
这四个问题的根因不一样,但都不是代码写错。
共同的误判是把它们当成打包工具的问题,分别是发布模型、信任链和权限设计。
运行时到底跟不跟包
先纠正混淆:依赖框架和自带运行时是「运行时怎么带」,单文件是「文件怎么摆」,不是同一层选项。单文件可以打在依赖框架的产物上,也可以打在自带运行时的产物上。
依赖框架
产物只有程序集和第三方库,运行时靠机器上已安装的 Desktop Runtime。本机这套发布出来 5 个文件、169.2 KB,同一个运行时能被多个程序共享,系统更新一次全部受益。代价是目标机器必须先有运行时,且大版本要对上,.NET 8 的程序默认不会跑到 .NET 9 上。
自带运行时
运行时按 RID 一起复制进发布目录,客户不用预装 .NET。体积会到约 160 MB(464 个文件、163,850.8 KB)。代价是每个程序各背一份运行时,安全补丁要跟自己的发布节奏走,多个自研程序就会重复占空间。
怎么选看交付环境。客户机器由你们统一装机、能推运行时,依赖框架更省体积;完全不确定机器状态、拷 U 盘就要能跑,自带运行时更稳。折中是让安装器检测运行时,缺了静默安装,装不上再提示,但要多维护一套先决条件。
RID 是另一个容易漏的维度。win-x64 覆盖大多数桌面机器,win-arm64 面向 ARM 笔记本和平板。只发 x64,在 ARM 设备上会走模拟层,能跑但更耗电、启动更慢,原生组件还可能不兼容。客户群里有 ARM 设备就出双包,至少在安装器里判断架构并提示。
AnyCPU 描述程序集平台,不是发布产物。执行 dotnet publish -r win-x64 时,RID 决定运行时和原生库的选择。两者混着理解,就会出现「项目写 AnyCPU,发布出来却只能跑 64 位」的困惑。--self-contained 的默认值会随是否指定 RID 变化,命令里显式写出来,别依赖记忆。
场景走查:把 DeviceDesk 发到干净机器
需求:一个叫 DeviceDesk 的 WPF 程序,读本地 SQLite 设备库,能改设置,最终装到客户的内网 Windows 机器上。客户没有开发环境,也不一定装了 .NET。
先建项目,并加一个带原生依赖的库,后面讲单文件时会用到:
dotnet new wpf -n DeviceDesk -f net8.0
cd DeviceDesk
dotnet add package Microsoft.Data.Sqlite
dotnet run
dotnet run 预期打开一个空窗口,先确认项目本身能编译能启动。接着按依赖框架的方式发布,产物小、结构清楚:
dotnet publish -c Release -r win-x64 --self-contained false
预期在 bin\Release\net8.0\win-x64\publish\ 下看到 DeviceDesk.exe、若干 .dll、deps.json、runtimeconfig.json,以及 runtimes 目录里的原生库。这个目录拷到装了 .NET 8 Desktop Runtime 的机器上能直接跑;没装的机器就会看到开头那句提示。它不会自动安装,也不会告诉你缺哪个具体版本。
确认客户机状态可以用:
dotnet --list-runtimes
预期输出里出现 Microsoft.WindowsDesktop.App 8.x 才算 Desktop Runtime 到位。只有 Microsoft.NETCore.App 不够,WPF 和 WinForms 要的是 WindowsDesktop 这一组。机器上完全没装 dotnet 时这条命令本身就不存在,这时代码检测或安装器先决检查才有意义。
第二次发布改成自带运行时加单文件,这是准备发给客户的那份:
dotnet publish -c Release -r win-x64 --self-contained true `
-p:PublishSingleFile=true `
-p:PublishReadyToRun=true `
-p:EnableCompressionInSingleFile=true
预期 publish 目录里主要是一个 DeviceDesk.exe,可能还有 .pdb 和少量附属文件,体积 163,850.8 KB。拷到干净虚拟机上双击,预期直接启动,不需要装 .NET。失败时先看事件查看器里的 .NET Runtime 错误,再确认原生库是否真的被打进去。
三个参数各管一件事,不是全开就最好:
PublishSingleFile把程序集和资源收进一个 exe,不消除运行时依赖,只是少给一堆文件。PublishReadyToRun预编译部分代码,减少启动时的即时编译。体积变大,启动通常更快。EnableCompressionInSingleFile压缩内容,体积下降。代价是首次启动要解压,更慢,也更容易被杀毒软件盯上。把这几个开关组合跑一遍,记录体积和「双击到窗口出现」的时间。压缩换体积、ReadyToRun 换启动速度,方向相反,取值只能按客户更在意哪一头来定。还要在干净虚拟机上走完安装、启动、卸载、再装新版的流程。
单文件的三个副作用
第一,原生库怎么放。像 SQLite 的 e_sqlite3.dll 这种依赖,默认可能留在 exe 旁边;设了 IncludeNativeLibrariesForSelfExtract=true 才会打进单文件,运行时解压到 %TEMP%\.net\ 下按程序名和哈希分的子目录。安全软件可能对这个「释放 dll 再加载」的动作敏感。排查原生库问题时,两个地方都要看。
第二,路径假设失效。单文件里 Assembly.Location 可能返回空,原来按「程序集所在目录」拼配置、模板的代码会崩或读错位置。正确做法是用 AppContext.BaseDirectory 或 Environment.ProcessPath 拿 exe 位置;用户数据根本不该放 exe 旁边。这个问题用 dotnet run 永远发现不了。
第三,裁剪。WPF 和 WinForms 重度依赖反射:绑定路径、序列化、资源查找、设计器代码,编译期看起来都没被引用。开启 PublishTrimmed 后,裁剪器会删掉这些成员,表现是启动报缺类型、绑定静默失效、一点就崩。WPF 官方不支持裁剪,WinForms 的支持也有限,第三方控件基本没戏。这两个框架不要为减体积去开裁剪。
另外,单文件不适合增量更新:改一行代码,整个 exe 的哈希都变,客户要重下全部。它也不等于免安装,快捷方式、卸载、文件关联、开机自启仍然要处理。程序要写注册表、装服务、注册 COM 时,单文件反而让安装器更难做。
安装器:四种选择的代价
| 方案 | 得到什么 | 代价 | 适合 |
|---|---|---|---|
| MSIX | 标准打包、干净装卸、容器化文件与注册表 | 要签名;容器限制写入位置、注册表、COM、服务,老程序常要先改代码 | 新项目、接受沙箱规则 |
| Inno Setup | 脚本安装、体积小、可按用户或按机器装 | 不是 MSI,企业批量部署弱,自动更新要自己做 | 中小项目、内网分发 |
| WiX | 标准 MSI,支持组策略、静默安装、升级链 | XML 繁琐;升级码配错会留下装不掉也升不上的残局 | 企业客户、IT 统一部署 |
| ClickOnce | 按用户安装、自动更新、部署简单 | 安装位置受限,原生依赖、COM、写 Program Files 都别扭 | 纯托管、更新频繁的内部工具 |
选型先问三件事:客户有没有 IT 部门要求 MSI 或静默安装;程序要不要写注册表、装服务、注册 COM;更新由谁触发。偏企业就 WiX 或 MSIX,偏小团队就 Inno,纯内部工具且更新频繁可以 ClickOnce,但要接受布局限制。最贵的不是工具,是装错后留在客户机器上的半安装状态。
不管选哪个,安装器至少要能检测运行时、选择目录、创建和删除快捷方式、升级时保留用户数据。自动更新不是赠品,需要版本清单、下载校验、失败回滚,做不好不如让用户手动下载。
要不要按机器安装,取决于客户现场谁有权限、谁来装。按用户安装不需要提权,但多用户各装一份、版本统一都是问题;按机器安装需要管理员,适合共享电脑和企业环境。
装到哪、写在哪
Program Files 是程序文件,普通用户只读;%LocalAppData% 是当前用户的私有数据,读写不用提权;%ProgramData% 是机器级共享数据,写入通常要管理员。程序把配置写在 exe 旁边,开发机上没问题,因为开发目录在你自己的用户目录下;装到 Program Files 后,同样的代码就会失败。
更隐蔽的是重定向。老的 32 位程序往受保护目录写文件,Windows 可能悄悄放到 VirtualStore,程序以为写成功了,实际文件在别处,重装或换机器后配置就消失。到 .NET 8 的 64 位进程,这层兼容往往不生效,写入直接抛异常。同一份代码在旧版「能用但有怪问题」,新版「直接报错」,很容易误判成迁移引入的缺陷。
正确分工是:只读资源跟安装目录;用户设置、最近文件、缓存、日志放 %LocalAppData%\公司名\产品名;共享数据放 %ProgramData%\公司名\产品名,安装时建目录、设权限。代码用 Environment.GetFolderPath 取路径,不硬编码盘符和用户名,也不假设目录已存在。
客户可能把程序装到 D 盘、路径里有空格或中文。写文件都要有失败路径,配置读写要原子化,先写临时文件再替换,避免留下半截 JSON。
签名与 SmartScreen
代码签名解决两件事:文件有没有被篡改,发布者是谁。Windows 用 Authenticode 校验 exe、dll 和安装包。签名后文件属性里会多一个「数字签名」页,客户能看到证书主体;没有这一页,SmartScreen 对陌生文件的默认态度就是拦。
实操有三个细节。签名要覆盖真正分发的文件:安装包、主 exe,必要时包括单独加载的 dll。签名必须带时间戳:证书有有效期,没有时间戳的签名在证书过期后会一起失效,已发出去的程序会突然「签名无效」。签名要在打包之后、发布之前做,顺序反了,安装包里的 exe 改过,外层签名就对不上。
证书类型影响 SmartScreen 的表现,但没有「买了证书就永远不弹」。EV 证书通常能更快建立信誉,OV 证书要靠下载量和时间积累。判断还跟文件哈希、发布者、下载来源有关,新版本即使同证书也可能被拦。签名的作用是「有身份可查、可申诉」,不是免疫拦截。
验证不要只看文件属性。用 signtool verify /pa /v DeviceDesk.exe 或 Get-AuthenticodeSignature,确认状态有效、时间戳存在。发布流水线里把这一步做成检查项,比人工点属性可靠。私钥要用硬件令牌或云签名服务保护,泄露比没签名更糟。
客户仍被拦时,能做的不是让他「点仍要运行」了事。可以提交误报、检查文件是否被二次打包改了哈希、确认签名链完整、让客户从正式渠道下载。说明里写清发布者名称和文件指纹,比一句「这是误报」有用。
版本号与覆盖安装
版本号要在两个地方同时成立:程序的 FileVersion 与 ProductVersion,和安装器的升级标识。前者用于界面显示和日志排查,后者决定新包是「升级旧版」还是「并排装一份新的」。
版本号单调递增,别回退,也别用日期字符串糊弄。安装器侧的升级码、应用标识一旦发布就不要改;改了等于告诉系统这是全新产品,旧版不会自动替换,客户机器上会出现两个程序、两套注册表项,卸载还只能一个个来。
覆盖安装的预期行为要明确:文件整体替换,用户数据保留,配置兼容旧版本。数据目录不要放安装目录;配置读取要能处理缺字段、多字段,不要一遇到未知键就抛异常;数据库变更要有版本号和迁移脚本,升级前先备份。降级通常不被允许,回滚方案就是「保留上一版安装包加备份用户数据」。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 提示缺少 .NET Desktop Runtime | 依赖框架发布,客户机没有对应大版本的运行时 | 看 --self-contained 的值;在客户机执行 dotnet --list-runtimes,找 WindowsDesktop |
| 双击没反应,日志里有 .NET Runtime 错误 | 原生库缺失,或运行时与程序版本不匹配 | 看事件查看器里的异常类型和第一个缺失模块 |
| 单文件首次启动特别慢 | 压缩内容要解压,原生库还要释放到临时目录 | 关掉压缩再发布对比;看 %TEMP%\.net 下的解压目录 |
| 发布后读不到配置或模板 | 用 Assembly.Location 拼路径,单文件下为空 | 搜索 Assembly.Location 和相对路径,改成 AppContext.BaseDirectory |
| 装在 Program Files 后设置保存失败 | 配置写在 exe 旁边,普通用户没写权限 | 看配置路径是否来自安装目录,是否被放到 VirtualStore |
| 安装包被 SmartScreen 拦截 | 未签名,或证书在该文件上还没信誉 | 看文件属性有没有数字签名页,查签名状态和时间戳 |
边界与代价
自带运行时不是「一劳永逸」。运行时打进包,就要对它负责:安全补丁、版本升级、新系统兼容,都得跟自己的发布周期走。客户不会因为运行时是你带的就少报一个漏洞,反而认为它是软件的一部分。团队里要有人盯 .NET 支持周期,别让一个 LTS 在客户机器上裸奔好几年。
体积和启动速度很难同时最优。压缩减体积但增加首次启动时间,ReadyToRun 反过来,单文件省文件数但增加解压和误报概率。没有一组参数适合所有客户,能做的只是记录取舍,按交付场景选默认值。
安装器的学习成本被低估。Inno Setup 做静默安装、升级检测、卸载清理,脚本很快长出分支;WiX 一个升级码写错,可能让客户机器进入「新版装不上、旧版卸不掉」的状态。选轻量工具就接受功能边界,选重量工具就接受维护成本。
签名有持续成本:证书按年买,私钥按规范保管,签名进流水线,时间戳服务要可用。内部工具可能不划算;但程序发给外部客户,没有签名就是把「安装失败」的概率交给运气。单文件也不是「绿色版」的替代品,它不处理注册表、服务、COM,也不处理多用户和卸载。
小结与练习
三句话收尾:运行时跟不跟包,取决于你能不能控制客户机器的环境;单文件只是打包方式,不消除依赖,还会带来解压目录和路径假设的问题;安装器、目录权限、签名和升级标识,决定程序能不能被顺利装上、用住、换版本。
当天可以自己验证的练习:
- 对同一个项目分别做依赖框架和自带运行时的发布,记录文件数和总体积,再把两份都拷到没装 .NET 的虚拟机上试启动。
- 只改压缩和 ReadyToRun 开关各发布一次,用秒表记录「双击到窗口出现」的时间,确认体积与启动速度的取舍方向。
- 加一个 SQLite 依赖并发布成单文件,运行后在
%TEMP%\.net下找到解压目录,确认原生库被释放到了哪里。 - 把读取配置的代码改到
%LocalAppData%,再把程序装到 Program Files,确认设置能存、卸载后数据还在。 - 用
Get-AuthenticodeSignature分别检查已签名和未签名的文件,对比状态、签名主体和时间戳字段。
下一篇讲老项目维护与迁移到新框架。新项目可以从发布方式开始设计,老项目往往反过来:先有一堆 .NET Framework 程序、COM 组件和第三方库,再考虑怎么让它们在新运行时上活下来。那篇讲迁移策略、升级工具的实际边界,以及配置、注册表、WebBrowser 这些历史包袱怎么逐个处理。