C# 项目安装包总是翻车?这套方案挺稳的

前言

很多 C# 项目在开发阶段跑得顺风顺水，一到交付环节就卡壳。程序能编译能运行，但客户那边装不上、装不好、装完了也不对劲。一些团队早期用压缩包交付，后来发现要处理注册表、Windows 服务、快捷方式、版本升级和卸载残留；再往后，项目版本多了，部署环境杂了，安装逻辑慢慢变成一堆批处理、PowerShell 脚本和零散的手动操作记录。临时能用，但长期维护起来非常吃力。

这篇文章聊一个老牌但依然很能打的工具：WiX Toolset。它不是那种"下一步、下一步"的安装包制作小玩具，而是一套面向工程化交付的 Windows Installer 工具集。今天就从 C# 项目最常见的交付痛点切入，看看 WiX 能解决什么问题，以及怎样把它放进真实的项目里。

把安装包当成交付代码来写

先看一个最小但完整的例子。假设有一个 C# 控制台程序，目录结构如下：

src/  DemoApp/    DemoApp.csprojinstaller/  Product.wxs

DemoApp 是一个普通的 .NET 控制台程序：

using System;namespaceDemoApp;internalstaticclassProgram{privatestaticvoidMain()    {        Console.WriteLine("DemoApp started.");        Console.WriteLine("Press any key to exit...");        Console.ReadKey();    }}

对应的 DemoApp.csproj 可以这样配置：

<ProjectSdk="Microsoft.NET.Sdk"><PropertyGroup><OutputType>Exe</OutputType><TargetFramework>net8.0-windows</TargetFramework><ImplicitUsings>enable</ImplicitUsings><Nullable>enable</Nullable><RuntimeIdentifier>win-x64</RuntimeIdentifier><SelfContained>true</SelfContained><PublishSingleFile>true</PublishSingleFile></PropertyGroup></Project>

先发布程序：

dotnet publish ./src/DemoApp/DemoApp.csproj -c Release -o ./publish/DemoApp

然后用 WiX 描述安装包。下面这个 Product.wxs 展示了最基本的安装动作：把程序安装到 Program Files 目录下，并创建开始菜单快捷方式。

<Wixxmlns="http://wixtoolset.org/schemas/v4/wxs"><PackageName="DemoApp"Manufacturer="Example Team"Version="1.0.0"UpgradeCode="11111111-1111-1111-1111-111111111111"><MajorUpgradeDowngradeErrorMessage="已经安装了更新版本的 DemoApp。" /><MediaTemplateEmbedCab="yes" /><StandardDirectoryId="ProgramFilesFolder"><DirectoryId="INSTALLFOLDER"Name="DemoApp"><ComponentId="MainExecutable"Guid="22222222-2222-2222-2222-222222222222"><FileId="DemoAppExe"Source="D:/myproject/11/TestC#/DemoApp/DemoApp/bin/Release/net8.0/publish/DemoApp.exe"KeyPath="yes" /><FileId="DemoAppDll"Source="D:/myproject/11/TestC#/DemoApp/DemoApp/bin/Release/net8.0/publish/DemoApp.dll" /><FileId="DemoAppdepsjson"Source="D:/myproject/11/TestC#/DemoApp/DemoApp/bin/Release/net8.0/publish/DemoApp.deps.json" /><FileId="DemoAppruntimeconfigjson"Source="D:/myproject/11/TestC#/DemoApp/DemoApp/bin/Release/net8.0/publish/DemoApp.runtimeconfig.json" /></Component></Directory></StandardDirectory><StandardDirectoryId="ProgramMenuFolder"><DirectoryId="ApplicationProgramsFolder"Name="DemoApp"><ComponentId="StartMenuShortcut"Guid="33333333-3333-3333-3333-333333333333"><ShortcutId="ApplicationStartMenuShortcut"Name="DemoApp"Description="启动 DemoApp"Target="[INSTALLFOLDER]DemoApp.exe"WorkingDirectory="INSTALLFOLDER" /><RemoveFolderId="RemoveApplicationProgramsFolder"On="uninstall" /><RegistryValueRoot="HKCU"Key="Software/ExampleTeam/DemoApp"Name="installed"Type="integer"Value="1"KeyPath="yes" /></Component></Directory></StandardDirectory><FeatureId="MainFeature"Title="DemoApp"Level="1"><ComponentRefId="MainExecutable" /><ComponentRefId="StartMenuShortcut" /></Feature></Package></Wix>

这个例子不花哨，但它抓住了 WiX 的核心思路：安装内容不是靠人脑记，而是靠文件声明。安装包也应该进版本库，跟代码一样接受版本管理。

版本升级是最容易翻车的地方

C# 项目做安装包，第一次安装通常不是最难的。真正麻烦的是升级。用户电脑上已经有旧版本，配置文件怎么处理？旧服务要不要停止？快捷方式是否更新？降级安装要不要拦截？这些问题没设计好，就会出现各种奇怪状况：桌面图标还在，程序目录里新旧 DLL 混在一起，卸载后还残留一堆文件。

WiX 里通常用 UpgradeCode 和 MajorUpgrade 管理大版本升级。前面的示例已经有这一段：

<MajorUpgradeDowngradeErrorMessage="已经安装了更新版本的 DemoApp。" />

这里有个容易被忽略的点：UpgradeCode 应该保持稳定，代表同一个产品族；而 ProductCode 通常在大版本升级时变化。WiX v4 的写法比老版本清爽不少，但概念不能搞混。

一个挺典型的坑：每次构建都随手换 UpgradeCode。结果安装器不认识旧版本，机器上能装出多个“同名但不同身份”的产品。界面上看着像一个软件，Windows Installer 眼里却是几户人家。后面卸载、升级、修复都会变得很麻烦。建议把产品身份当成数据库主键一样认真对待，不要随便改动。

msiexec /i DemoAppSetup.msi /qn /L*v install.log

第四个是开源协议相关的问题。WiX 仓库的 README 中提到，该项目的源码按许可证开放，但如果使用项目产生收入，需要关注 Open Source Maintenance Fee 的相关说明。企业使用前，最好让技术负责人和合规同事一起确认，不要只看“开源”两个字就贸然用上。

一个可直接用的构建脚本模板

下面是一个小团队可以直接改的构建脚本模板，胜在清晰直接。

param(  [string] $Configuration = "Release")$ErrorActionPreference = "Stop"$root = Split-Path -Parent $PSScriptRoot$appProject = Join-Path $root "src/DemoApp/DemoApp.csproj"$publishDir = Join-Path $root "publish/DemoApp"$installerProject = Join-Path $root "installer/DemoApp.Installer.wixproj"Write-Host "Cleaning publish directory..."if (Test-Path $publishDir) {  Remove-Item $publishDir -Recurse -Force}Write-Host "Publishing application..."dotnet publish $appProject `  -c $Configuration `  -o $publishDirWrite-Host "Building installer..."dotnet build $installerProject `  -c $ConfigurationWrite-Host "Done."