一个 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。开发机装过 SDK,SDK 自带运行时,所以永远复现不出来。
包太大改成自带运行时后,运行时被打进产物,再叠加单文件、ReadyToRun,体积会从 169.2 KB 涨到约 160 MB。
被拦截安装包没有 Authenticode 签名,或签名证书在 SmartScreen 那里还没有信誉。
配置写不进去配置、日志、缓存写在 exe 旁边。装进 Program Files 后,普通用户对该目录只有读权限。

共同的误判是把它们当成打包工具的问题,分别是发布模型、信任链和权限设计。

从源码到客户机器
编译与发布
决定运行时随不随包
单文件与优化选项
安装器封装
签名与时间戳
安装、首次启动、升级

运行时到底跟不跟包

先纠正混淆:依赖框架和自带运行时是「运行时怎么带」,单文件是「文件怎么摆」,不是同一层选项。单文件可以打在依赖框架的产物上,也可以打在自带运行时的产物上。

依赖框架

产物只有程序集和第三方库,运行时靠机器上已安装的 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 时,单文件反而让安装器更难做。

不要用「把配置和数据库塞到 exe 旁边」来图省事。单文件运行时的工作目录、解压目录、exe 所在目录不是同一个概念,相对路径很容易指错。可写数据走用户数据目录,只读资源才跟着程序走。

安装器:四种选择的代价

方案得到什么代价适合
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,也不处理多用户和卸载。

小结与练习

三句话收尾:运行时跟不跟包,取决于你能不能控制客户机器的环境;单文件只是打包方式,不消除依赖,还会带来解压目录和路径假设的问题;安装器、目录权限、签名和升级标识,决定程序能不能被顺利装上、用住、换版本。

当天可以自己验证的练习:

  1. 对同一个项目分别做依赖框架和自带运行时的发布,记录文件数和总体积,再把两份都拷到没装 .NET 的虚拟机上试启动。
  2. 只改压缩和 ReadyToRun 开关各发布一次,用秒表记录「双击到窗口出现」的时间,确认体积与启动速度的取舍方向。
  3. 加一个 SQLite 依赖并发布成单文件,运行后在 %TEMP%\.net 下找到解压目录,确认原生库被释放到了哪里。
  4. 把读取配置的代码改到 %LocalAppData%,再把程序装到 Program Files,确认设置能存、卸载后数据还在。
  5. 用 Get-AuthenticodeSignature 分别检查已签名和未签名的文件,对比状态、签名主体和时间戳字段。

下一篇讲老项目维护与迁移到新框架。新项目可以从发布方式开始设计,老项目往往反过来:先有一堆 .NET Framework 程序、COM 组件和第三方库,再考虑怎么让它们在新运行时上活下来。那篇讲迁移策略、升级工具的实际边界,以及配置、注册表、WebBrowser 这些历史包袱怎么逐个处理。