办公软件要装、JDK 要装、数据库要装随手一搜“安装包”三个字都有一大堆下载需求。可大多数开发者真到了自己交付项目那天反而会在打包这一步卡住代码写完了自测也通过了客户机器却是刚装好的裸系统连运行环境都没有总不能让人家先装 Visual Studio 再跑你的程序。我这些年做 .NET 桌面程序交付用得最趁手的还是微软官方这套 Visual Studio Installer Projects 扩展。它能把 WPF、WinForms、控制台程序连同依赖一起打成正经的 MSI 安装包并生成 setup.exe 引导安装前置运行库。这篇文章我把从装扩展、建 Setup 工程、配文件系统到版本升级、自定义操作、报错排查的完整链路都过一遍适合正在为“程序到底怎么交到别人手上”发愁的 .NET 开发者也适合想系统了解 Windows Installer 打包机制的读者。1. 选型Installer Projects 在打包工具里的真实位置别急着开搞先搞清楚为什么是它。市面上能打包 Windows 程序的方案少说五六种我见过不少同事在 Inno Setup 和 NSIS 之间反复横跳也见过团队花大半个月啃 WiX 最后只为了一个安装界面。不是说这些工具不好而是“把 .NET 桌面程序交付给用户”这个具体场景工具选错了会成倍放大工作量。工具产物上手成本适用场景一句话评价Visual Studio Installer ProjectsMSI setup.exe低.NET 桌面程序、工具类软件和 VS 深度集成可视化编辑器依赖自动检测WiXMSI高需要精细控制 MSI 表的大型项目写 XML 像写程序能力天花板高但代价大Inno SetupEXE中低通用 Windows 软件脚本式配置中文资料多广受欢迎NSISEXE中轻量工具、自定义 UI插件生态强但脚本语法有一定门槛InstallShieldMSI中高企业级安装包、多语言商用授权LE 版已不再随 VS 提供回到 Installer Projects 本身。它的核心优势是“和工程绑定”你在解决方案里引用哪个程序安装包里就自动带上那个程序的编译输出程序集之间的引用关系也会被识别成 Detected Dependencies不需要手动维护文件清单。这对中小型 .NET 桌面项目来说节约的时间非常可观。另一个务实原因是它做出来的就是标准 MSI天然支持控制面板卸载、Windows Installer 日志、静默安装参数交付给企业客户时对方 IT 部门也能用 msiexec 管理。硬伤也要提前讲清楚。vdproj 是 Visual Studio 的私有工程格式MSBuild 原生不能直接编译CI 里需要特殊处理功能深度比 WiX 差一截复杂的条件安装、多语言 UI 改起来很费劲官方维护节奏也比较慢。但这就像你选一辆代步车——通勤够用、配件好找、不用懂修车就已经赢了。如果你的项目是内部管理系统、行业工具软件、演示程序这类场景它完全能扛住真到了需要企业级安装体验的那天再考虑 WiX 迁移也不迟。2. 从扩展安装到 Setup 工程落地环境准备全流程2.1 装扩展是第一步方法有两种新版 Visual Studio 里默认不带 Installer Projects需要先装扩展。打开 VS 菜单栏的“扩展(E)”→“管理扩展”联网搜索框里输入 “Installer Projects”找到 Microsoft Visual Studio Installer Projects 后安装重开 VS 即可。如果目标机器不方便联网也可以从 Visual Studio Marketplace 下载对应的 vsix 文件离线安装。这里提醒一句VS2022 的扩展是有 x64/ARM64 区分版本的下载前先看清楚自己的 VS 是什么架构。装完以后确认一下 VS 里能否搜到 “Setup Project” 模板搜不到就检查扩展列表是否真的启用成功别急着怀疑系统。2.2 创建 Setup 工程并认识六个编辑器在包含你主程序的解决方案里右键解决方案 →“添加”→“新建项目”搜索 “Setup Project” 或 “Visual Studio Installer”选择模板名称叫 “Setup Project” 的那一个。生成的工程文件后缀是 .vdproj在解决方案里会显示成独立的安装工程。工程一创建左侧会多出一列编辑器图标这是 Installer Projects 的核心操作区一共六个文件系统编辑器、注册表编辑器、文件类型编辑器、用户界面编辑器、自定义操作编辑器、启动条件编辑器。初次上手最容易忽略的一点是这六个编辑器操作的不是同一个文件而是同一个 vdproj 工程的不同视图你改完一个记得保存整个工程。2.3 vdproj 的构建特殊性CI 要提前留坑vdproj 不像 csproj 那样有完整的 MSBuild target普通msbuild命令行经常直接把安装工程跳过或者报“未注册的工程类型”。在本地 VS 里点“生成”没问题是因为 IDE 底层走了 devenv 的构建流程。到了 CI 环境最稳的做法是用 devenv.com 命令行devenv.com D:\Projects\MyApp\MyApp.sln /Build Release|x86用这条命令会按指定的解决方案配置把整个解决方案包括安装工程一起构建。如果你的构建机上没有完整 VS 而只有 Build Tools大概率搞不定 vdproj建议把安装包的构建放在一台装有 VS 的专用构建机上。这不是玄学是文件格式本身的限制早规划早省心。3. 文件系统编辑器让程序、依赖和快捷方式各就各位3.1 Add Project Output 到底该选哪几项进入文件系统编辑器右侧默认有“Application Folder”应用程序文件夹、“Users Programs Menu”用户程序菜单、“Users Desktop”用户桌面三个虚拟目录。右键 Application Folder →“Add”→“Project Output...”会弹出让你选择主项目的对话框。这个对话框里最常用的是两项Primary Output主项目编译产生的 exe、dll是安装包的核心。Content Files跟随程序的内容文件包括 app.config 转换出的 .exe.config、静态资源等。Localized Resources 是卫星资源程序集Debug Symbols 是 PDB 符号文件XML Documentation 是注释文档。一般内部交付选 Primary Output Content Files 足够。我见过有人把 Debug Symbols 也勾了结果安装目录里塞满 PDB毫无意义还容易被客户认为“工程没清理干净”。加完输出后Application Folder 下会自动生成 “Detected Dependencies”检测到的依赖项这是 VS 根据项目引用自动推导出来的程序集清单。这部分不要手动乱删删了安装后程序大概率缺程序集跑不起来。反过来如果发现某个第三方 DLL 没被自动检测到多半是因为它不是通过项目引用进来的比如运行时动态加载的插件程序集这种情况需要你手动 Add → File 把它塞进安装目录。3.2 安装目录、子目录和快捷方式的正确摆法Application Folder 节点有一个 DefaultLocation 属性默认值是[ProgramFilesFolder][Manufacturer]\[ProductName]翻译成人话就是C:\Program Files\厂商名\产品名。这个路径可以在属性栏里改比如想让程序装到 D 盘某个固定目录直接改成D:\MyApp或写成带[TARGETDIR]的表达式。如果你的程序有独立的插件目录、日志目录、资源目录就要在 Application Folder 下右键 → Add → Folder 创建同名子目录再把文件放进去。这里有个非常容易踩的坑你把一个文件放到了 Application Folder 根目录但代码里写的是相对路径./Plugins/xxx.dll安装后程序必然找不到文件。解决方案就是先在编辑器里建 Plugins 子目录再放文件别指望安装器替你“智能匹配”代码路径。快捷方式的创建方式比较反直觉不是直接右键添加而是先把 Primary Output 拖到 Application Folder 里然后右键这个输出项 → “Create Shortcut” 生成一个快捷方式图标再把快捷方式剪切粘贴到 Users Programs Menu 或 Users Desktop 目录下。创建后记得重命名否则默认名字是 “Primary Output from MyApp” 这种谁看了都懵的字符串。Users Programs Menu 代表所有用户或当前用户的开始菜单项取决于后续要说的 InstallAllUsers 属性并不是字面意思上的“某个叫 user 的人”。3.3 手动添加文件的细节和文件属性手动添加文件时建议把所有需要打包的杂项文件集中到一个干净的源目录再按目录结构逐个 Add。这样以后换版本只需要更新源目录里的文件不用反复调整安装工程。文件节点的属性栏里有两个冷门属性值得注意Permanent 和 Transitive。把某个文件设置为 Permanent True卸载时它会被保留适合日志、模板、用户配置这类“删了反而麻烦”的文件。Transitive 属性则比较进阶一般用不上别乱勾。4. ProductCode、UpgradeCode、RemovePreviousVersions升级与卸载的底层逻辑4.1 三个 GUID 各管哪一段务必记牢安装工程的核心属性里有一堆 GUID 和版本号很多人在这上面栽过跟头。把它们拆开看其实就三件事ProductCode当前版本的身份证不同版本必须是不同的 GUID。UpgradeCode整个产品线的“血缘标识”所有版本共用同一个换系列才需要改。PackageCode由系统每次构建时自动生成不用管。也就是说版本升级时要自动换 ProductCode但是 UpgradeCode 必须保持不变。如果 UpgradeCode 变了老版本就检测不到新版本属于同一产品会出现安装了两套同名程序的“双胞胎”事故如果 ProductCode 没换新版本在已安装旧版本的机器上会直接报“另一个版本已安装”。4.2 版本号规则与 RemovePreviousVersions 的配合版本相关的三个属性是一组组合拳ProductName产品名、Version版本号、RemovePreviousVersions是否移除旧版本。要做自动升级必须把 RemovePreviousVersions 设为 True并且保证新旧版本的 UpgradeCode 一致这样新版安装时会自动先卸载旧版再安装你自己。这里有个冷知识Windows Installer 的 ProductVersion 只认三段数字比如 1.0.0。你写四段 “1.0.0.1” 时第四位会被忽略甚至引发校验问题所以版本号统一用 x.y.z 三段。升级时还有个实际行为值得留意MSI 的升级机制是“先移后装”还是“并发”取决于具体配置但在 Installer Projects 的默认实现下用户直接运行新版 msi 时旧版会被移除再安装新版。如果旧版安装时往安装目录里写过用户数据升级后这些数据可能跟着旧版被删掉。所以我一直主张用户数据一律写%APPDATA%或其他数据目录永远不要依赖安装目录下的文件持久化。这不是安装包的锅是设计缺陷。4.3 卸载残留和强制清理手段控制面板“程序和功能”里的卸载入口其实是 MSI 根据 ProductCode 自动注册的。卸载不干净通常有三个原因自定义操作没挂 Uninstall 节点导致清理逻辑没执行程序进程在卸载时仍占用文件你自己手动写的注册表项没有随卸载删除。排查时可以直接查卸载注册表位置包括HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall和HKCU下对应项看看卸载入口是否真的被注册了。真遇到 MSI 状态损坏的极端情况可以用命令行强制卸载msiexec /x {ProductCodeGUID}或者拿到产品后先看它装的到底是谁msiexec /i MyApp.msi /l*v install.log日志文件是排查安装问题的第一手资料后面章节还会详细用到。5. 前置条件与启动条件别让干净机器变成安装事故现场5.1 Prerequisites 的正确配置和离线部署一个安装包如果没有处理运行库那基本等于没做安装包。选中 Setup 工程节点在属性窗口下方有个 “Prerequisites...” 按钮点开能看到一堆可选项。最常见的组合是 .NET Framework 4.8 和 VC Redistributable具体按你主程序的目标框架勾选。对话框里有三个下载位置选项“从组件供应商网站下载”意味着用户安装时必须联网“从与我的应用程序相同的位置下载”最推荐它会把前置条件安装器和 MSI 一起放进构建输出目录。选这个以后构建生成的不是一个孤零零的 msi而是一整套配套文件包括 setup.exe 引导程序和各个运行库的安装包。交付时要把整个输出文件夹完整发给对方只发那个 msi 文件的话前置条件一个都不会装。对 .NET 6 的项目要特别说明Installer Projects 的 Prerequisites 列表并不认识 .NET 运行时你没法给程序勾一个“先装 .NET 8 运行时”的选项。这种项目最省事的处理方式是发布成自包含单文件把运行时一并打进 exe否则就得在 Launch Condition 和文档里提醒用户先装运行时体验会打折。5.2 Launch Conditions能判断不能安装启动条件编辑器里新建 Setup 工程时一般会自动生成一个“.NET Framework”检查节点。选中它在属性栏里设置期望的版本号和 PublicKeyToken当目标机器缺少对应 Framework 时安装会弹出你写的提示文案并中断。这一步和 Prerequisites 是配合关系Prerequisites 负责“缺了就装”Launch Conditions 负责“装了但版本不够就拦”。逻辑上先判断、再安装最终保证安装完成后环境可用。如果想自行判断某个 DLL 是否存在可以右键启动条件编辑器 → Add → Search Target Machine → File Search指定文件名和查找路径。这个功能适合处理 VC 运行库等 Prerequisites 列表里没有明说的情况。需要提醒的是Launch Condition 只是检测不会执行修复别指望它自动装东西。5.3 InstallAllUsers 与默认安装路径的联动Setup 工程属性中有一个 InstallAllUsers 布尔值它决定了安装的作用域和权限模型True安装到 Program Files需要管理员权限控制面板卸载对所有用户生效。False安装到当前用户的 AppData 目录不需要管理员权限适合绿色工具。这个属性和 File System 编辑器里的 DefaultLocation 是联动的。如果你把 InstallAllUsers 从 True 改成 False还想让安装目录落到 AppData 下记得同步修改 Application Folder 的 DefaultLocation写成[AppDataFolder]\MyApp这样的形式。否则安装器会试图往 Program Files 写结果又绕回权限问题。这两个配置一定要一起测试单独改一个很容易埋雷。6. Custom Actions 实战安装过程中执行脚本的坑与技巧6.1 四个执行节点的顺序和挂载方式自定义操作编辑器里有四个固定节点Install、Commit、Rollback、Uninstall。Install 在安装主流程中执行Commit 在所有文件复制成功后执行Rollback 在安装失败回滚时执行Uninstall 在卸载时执行。这四个节点在时间上严格串行你不能指望 Commit 里的代码在文件复制之前跑。挂载自定义操作的方式是右键某个节点 → Add Custom Action然后在文件系统编辑器里选择要执行的 exe 或 dll。注意这里的选择是从“安装包内文件列表”里挑不是从磁盘直接选文件。如果你从磁盘硬选一个没在文件系统编辑器里出现的程序MSI 会在执行时找不到文件直接回滚。6.2 托管自定义动作的推荐写法给自定义操作挂一个普通 exe 不是不行但参数传递很受限。更稳的做法是新建一个类库项目引用System.Configuration.Install写一个 Installer 类把安装时要执行的逻辑放在里面using System.Collections; using System.ComponentModel; using System.Configuration.Install; [RunInstaller(true)] public class MyCustomAction : Installer { public override void Install(IDictionary stateSaver) { base.Install(stateSaver); string targetDir Context.Parameters[targetdir]; if (string.IsNullOrEmpty(targetDir)) { throw new InstallException(缺少 targetdir 参数); } // 在这里写你的逻辑生成配置、创建目录、写模板文件等 File.WriteAllText(Path.Combine(targetDir, installInfo.txt), $Installed at {DateTime.Now:yyyy-MM-dd HH:mm:ss}); } }把这个类库的编译输出 dll 加到 Application Folder再在 Install 节点上把它挂为自定义动作然后在自定义动作节点的属性里设置 CustomActionData例如/targetdir[TARGETDIR]\Installer 类里的Context.Parameters[targetdir]就能拿到[TARGETDIR]对应的实际安装路径。这里有个细节CustomActionData 里的[TARGETDIR]是由 Windows Installer 在运行时解析的写的时候路径要带反斜杠并且注意引号配对否则参数解析丢失最后一个反斜杠路径会出错。6.3 权限、路径和卸载节点最容易出问题的三个位置自定义操作执行时的权限取决于安装的作用域。InstallAllUsers 为 True 时MSI 会触发 UAC 提权自定义操作在高权限下执行写 Program Files 没问题InstallAllUsers 为 False 时整个流程都在用户权限下不要试图写 HKLM 或 Program Files早点改设计比在自定义操作里折腾提权靠谱得多。另一个高频坑自定义操作里的“当前工作目录”不一定是你想象的安装目录。Windows Installer 执行自定义操作时的工作目录可能是系统临时目录或系统目录所以千万别用相对路径所有路径都通过Context.Parameters或绝对路径获取。最后是卸载清理。很多人只在 Install 节点挂了自定义操作忘记在 Uninstall 节点也挂一遍结果安装时生成的文件卸载后全留在客户机器上。把同一个 dll 也挂到 Uninstall 节点并在代码里实现 Uninstall 方法的清理逻辑即可。如果这个 dll 同时被主项目引用了要在文件系统编辑器里把它标记 Exclude True避免文件重复安装造成冲突。7. 从编译到安装的报错排查链路与一些补充经验7.1 编译期问题平台不一致和缓存残留第一步先把主程序编译通过。安装工程依赖的是主项目输出如果主项目编译失败Setup 工程会跟着报 “Project Output ... could not be found” 之类的错误这时候排查方向不要跑偏。其次检查安装工程的 TargetPlatform 属性。VS 默认可能把你的安装工程设成 x86而主程序是 x64-only两者不一致时安装阶段可能一切正常但程序跑不起来或者被装到了Program Files (x86)导致路径对不上。建议在安装工程属性里显式指定 TargetPlatform和主程序的输出平台保持一致。编译完发现输出缓存里有旧版本残留时先把文件系统编辑器里的 Project Output 删掉再重新 Add Project Output不要直接改文件因为 vdproj 内部缓存了旧的输出标识重新添加才能刷新。7.2 安装期问题用日志还原事故现场安装到一半回滚是最让人头大的问题。别靠猜直接打开事件查看器Windows 日志 → 应用程序筛选来源为 MsiInstaller 的事件更精确的方法是给 msiexec 加上详细日志参数msiexec /i MyApp.msi /l*v install.log日志文件会记录 MSI 执行的完整步骤。重点搜索 “Return value 3” 和 “ROLLBACK”回滚前最后一个报错往往就是真正的问题点。如果错误码是 1001几乎可以断定是自定义操作抛了异常回到第 6 节逐项排查 dll 是否被正确打包、参数是否解析成功。还有一个常见场景是卸载时提示文件被占用原因往往是程序进程没退出。安装包本身没法替客户杀进程但在自定义操作里加上进程检测逻辑并提示用户关闭程序是成本最低的解决办法。7.3 签名、MSI 微调与 CI 构建的补充经验企业客户经常要求安装包有数字签名否则 SmartScreen 会拦一道。主程序 exe 和最后生成的 msi、setup.exe 都可以用 signtool 签名signtool sign /f cert.pfx /p password /t http://timestamp.digicert.com MyApp.msi签名要在打包完成后进行而且 msi 签名后不要再通过 VS 重新构建覆盖它否则签名失效。vdproj 没有直接的 PostBuildEvent所以签名这步通常写进发布脚本由脚本统管控制台编译、签名、压缩交付物。关于 MSI 微调Windows SDK 里有个 Orca 工具可以直接打开 MSI 文件改表。我日常会用它的场景是调整“程序和功能”里显示的自定义注释、图标这类细节。它是应急武器不是日常工具大规模改动后一定要在干净虚拟机里完整跑一遍安装卸载。CI 构建的事我在第 2 章提过这里再强调一次vdproj 不是 MSBuild 原生支持的工程类型构建机没有完整 VS 基本没戏。在自己的发布脚本里直接用 devenv.com /Build比折腾各种变通方案节省时间得多。我个人这些年用下来最大的体会是Installer Projects 能做的事不算多但只要把 ProductCode、UpgradeCode、RemovePreviousVersions 这三个配置想透再把前置条件和自定义操作这两块边界理清它就非常皮实。最后分享一个小技巧动手配置安装工程之前先在文件系统编辑器里把整个安装目录的布局画出来再对照着放文件、建目录、做快捷方式这套“先画图后配置”的习惯能帮你避开九成以上的路径错乱问题。
