开发工具构建工具【免费下载链接】wix3WiX Toolset v3.x项目地址https://gitcode.com/gh_mirrors/wi/wix3点击查看免费下载本文基于 WiX Toolset v3 官方文档《Creating a Simple WiX Extension》带你完整走通扩展开发的第一步创建一个继承自WixExtension的骨架扩展程序集并用-ext开关在 Candle 和 Light 上完成验证。读完本文你将掌握骨架扩展的 6 个构建步骤、-ext参数在candle.cs/light.cs中的真实解析与加载链路、WixExtension.Load支持的 5 种程序集定位方式以及仓库内ValidatorExampleExtension这一可对照的完整样例。一、WiX 扩展是什么从哪里开始WiX 扩展用于扩展和定制 WiX 构建的内容与构建的方式。扩展的入口点是一个继承自WixExtension类的 C# 类它是所有扩展实现编译器钩子、绑定器钩子、验证器、命令行参数解析等的容器。要理解扩展机制最直接的读物是 WiX 源码中的 WixExtension 基类。从源码结构看该类全部成员均为virtual且默认返回null——这意味着一个“什么都不做”的空子类也是合法的扩展这正是骨架扩展能够直接通过 Candle/Light 验证的原因。二、六步创建骨架 WiX 扩展以下步骤完整继承自官方文档并补充了与仓库源码对照的工程细节。第 1 步创建 C# 类库项目在 Visual Studio 中创建一个名为SampleWixExtension的新 C# 类库.dll项目。扩展必须是类库而非可执行程序——仓库内的真实扩展工程 ValidatorExampleExtension.csproj 也明确设置了OutputTypeLibrary/OutputType。第 2 步引用 wix.dll为项目添加对wix.dll的引用。在仓库源码工程里对应的写法是 ProjectReferenceReference IncludeSystem / Reference IncludeSystem.Xml / ProjectReference Include..\..\..\Wix\Wix.csproj /外部开发者则直接引用安装好的 WiX SDK 中的wix.dll即可。第 3 步引入命名空间添加指向核心命名空间的 using 语句using Microsoft.Tools.WindowsInstallerXml;该命名空间是WixExtension与AssemblyDefaultWixExtensionAttribute的所属命名空间可在 WixExtension.cs 与 AssemblyDefaultWixExtensionAttribute.cs 中确认。第 4 步继承 WixExtensionpublic class SampleWixExtension : WixExtension {}空类体即可。WixExtension的抽象能力通过虚属性暴露骨架阶段全部保持默认null实现。第 5 步注册默认扩展类型在项目的AssemblyInfo.cs中添加AssemblyDefaultWixExtensionAttribute[assembly: AssemblyDefaultWixExtension(typeof(SampleWixExtension.SampleWixExtension))]这个属性是命令行“只给 DLL 路径、不指定类名”场景下的关键。从源码看当WixExtension.Load在程序集中找不到显式类名时会通过Attribute.GetCustomAttribute读取该属性来获取默认扩展类型若属性不存在直接抛出InvalidExtensionType异常见 WixExtension.cs 第 226-235 行。该属性本身定义于 AssemblyDefaultWixExtensionAttribute.cs仅允许作用于程序集[AttributeUsage(AttributeTargets.Assembly)]。仓库内的实例可对照 ValidatorExampleExtension 的 AssemblyInfo.cs[assembly: AssemblyDefaultWixExtension(typeof(ValidatorExampleExtension))]第 6 步编译构建项目得到SampleWixExtension.dll。虽然此时这个扩展尚不会做任何事但它已经具备了被 WiX 工具链识别和加载的全部要件。三、用 -ext 验证骨架candle.exe 与 light.exe骨架编译完成后即可将 DLL 通过-ext开关传给 Candle 和 Light 进行编译/链接candle.exe Product.wxs -ext SampleWixExtension.dll light.exe Product.wxs -ext SampleWixExtension.dll这条命令背后的完整调用链可以在仓库源码中逐层验证命令行解析。candle.cs在解析参数时遇到ext会将其取值加入extensionList若-ext后缺少参数则报告TypeSpecificationForExtensionRequired错误candle.cs 第 344-355 行light.cs有完全对称的实现light.cs 第 581-590 行。扩展加载。Candle 对extensionList中每一项调用WixExtension.Load(extension)随后把同一个实例同时注册给预处理器和编译器preprocessor.AddExtension(wixExtension)与compiler.AddExtension(wixExtension)candle.cs 第 149-156 行。Light 侧的差异。Light 除了加载扩展外还会利用扩展的ParseCommandLine消化 light 自身未识别的剩余命令行参数light.cs 第 142-153 行并在后续流程中读取扩展提供的本地化资源此外若扩展提供了CustomBinder可与命令行-binder指定的类名匹配以替换默认绑定器light.cs 第 116-121 行。只要 candle 与 light 都能正常走完编译与链接流程而没有扩展加载错误就证明你的骨架扩展在程序集定位、默认扩展类型解析两个环节上均符合要求。四、WixExtension.Load-ext 参数到底支持哪些写法骨架阶段只需给 DLL 路径但读懂Load的实现有助于排错。WixExtension.LoadWixExtension.cs 第 143-247 行支持 5 种程序集定位形式AssemblyQualifiedName例如MyExt, MyAssembly, Version1.3.0.0, Cultureneutral, PublicKeyTokenb17a5c561934e089AssemblyName例如MyAssembly, Version1.3.0.0, Cultureneutral, PublicKeyTokenb17a5c561934e089绝对路径例如C:\MyExtensions\ExtensionAssembly.dll走Assembly.LoadFrom应用程序目录下的文件名例如ExtensionAssembly.dll相对路径例如..\..\MyExtensions\ExtensionAssembly.dll。另有一条通用规则可以在程序集名前用逗号前缀显式指定扩展类的全名如TopNamespace.ContainingClass, C:\MyExtensions\ExtensionAssembly.dll未指定类名时则回退到第五步的AssemblyDefaultWixExtensionAttribute。加载成功后Load会校验目标类型必须IsSubclassOf(typeof(WixExtension))并用Activator.CreateInstance实例化任何一步失败都会以WixException抛出InvalidExtension或InvalidExtensionType错误这正是-ext参数写错时你在命令行看到的错误来源。五、骨架之后WixExtension 提供的扩展点WixExtension通过一组虚属性把不同阶段的钩子暴露给扩展骨架阶段它们全部返回null后续按需覆盖即可。整理自 WixExtension.cs 的扩展点如下虚成员用途ParseCommandLine(args, messageHandler)解析扩展自定义的命令行参数返回未被解析的参数集合供其他扩展继续处理CompilerExtension提供编译器扩展在单遍编译的相应时机被调用BinderExtension提供绑定器扩展BinderFileManager提供绑定器文件管理器CustomBinder提供对默认绑定器的完整替换DecompilerExtension提供反编译器扩展PreprocessorExtension提供预处理器扩展自定义指令等InspectorExtension提供检查器扩展Light 的 inspector 阶段UnbinderExtension提供解绑器扩展decompile 场景ValidatorExtension提供验证器扩展TableDefinitions注册扩展自带的内部表定义DefaultCulture声明扩展本地化的默认语言GetLibrary(tableDefinitions)返回扩展关联的 WiX 库wixlib基类默认返回null仓库内可运行的完整样例是 ValidatorExampleExtension它覆盖了InspectorExtension与ValidatorExtension两个属性并用私有字段对实例做延迟初始化展示了一个多钩子扩展的典型组织方式——骨架扩展扩展为功能扩展时的形态与它一致。六、继续深入的两条路径骨架代码是 WiX 扩展开发的公共基础完成本文步骤后沿两条主线继续构建自定义操作以骨架代码为起点开发 custom action然后在 WiX 源码中编写对应操作参见仓库文档 Adding a Custom Action构建预处理器扩展完整走一遍扩展含 XSD schema 与表定义的构建流程参见 Creating a Preprocessor Extension。此外扩展开发的通用约定目标框架、schema 编写、RequiredVersion属性等在 Introduction to Developing WiX Extensions 中有系统说明其中特别提到多个同类型扩展之间没有处理顺序保证扩展之间不能存在排序依赖并建议扩展开发者在Wix元素上实现RequiredVersion属性以便安装项目作者锁定扩展版本。七、小结一个可工作的 WiX 骨架扩展只需要四件事继承WixExtension的空类、对wix.dll的引用、AssemblyDefaultWixExtensionAttribute的程序集级注册、以及一次成功的candle.exe / light.exe -ext验证。理解了WixExtension.Load的 5 种程序集定位规则与默认扩展属性的回退机制再配合仓库中ValidatorExampleExtension这一参照实现即可在骨架之上按需覆盖CompilerExtension、ValidatorExtension等虚属性逐步长出完整的自定义扩展。赞分享开发工具构建工具【免费下载链接】wix3WiX Toolset v3.x项目地址https://gitcode.com/gh_mirrors/wi/wix3点击查看免费下载相关推荐终极Ulauncher扩展开发指南从零开始构建你的第一个Linux启动器插件终极Ulauncher扩展开发指南从零开始构建你的第一个Linux启动器插件 Ulauncher是一款功能丰富的Linux应用启动器通过扩展机制可以极大增强桌面应用开发工具VSCodium扩展开发入门从零构建你的第一个插件VSCodium扩展开发入门从零构建你的第一个插件 为什么选择VSCodium开发扩展 VSCodium作为Visual Studio Code的开源替代版本开发工具BlueOcean插件开发入门从零构建你的第一个扩展BlueOcean插件开发入门从零构建你的第一个扩展 BlueOcean是Jenkins的一款革命性插件为开发者提供现代化、直观的持续集成/持续部署 CI/创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/14 21:24:15 · 阅读 1.2k WiX Toolset 扩展开发入门：从零构建一个可被 candle 与 light 加载的骨架扩展
开发工具构建工具【免费下载链接】wix3WiX Toolset v3.x项目地址https://gitcode.com/gh_mirrors/wi/wix3点击查看免费下载本文基于 WiX Toolset v3 官方文档《Creating a Simple WiX Extension》带你完整走通扩展开发的第一步创建一个继承自WixExtension的骨架扩展程序集并用-ext开关在 Candle 和 Light 上完成验证。读完本文你将掌握骨架扩展的 6 个构建步骤、-ext参数在candle.cs/light.cs中的真实解析与加载链路、WixExtension.Load支持的 5 种程序集定位方式以及仓库内ValidatorExampleExtension这一可对照的完整样例。一、WiX 扩展是什么从哪里开始WiX 扩展用于扩展和定制 WiX 构建的内容与构建的方式。扩展的入口点是一个继承自WixExtension类的 C# 类它是所有扩展实现编译器钩子、绑定器钩子、验证器、命令行参数解析等的容器。要理解扩展机制最直接的读物是 WiX 源码中的 WixExtension 基类。从源码结构看该类全部成员均为virtual且默认返回null——这意味着一个“什么都不做”的空子类也是合法的扩展这正是骨架扩展能够直接通过 Candle/Light 验证的原因。二、六步创建骨架 WiX 扩展以下步骤完整继承自官方文档并补充了与仓库源码对照的工程细节。第 1 步创建 C# 类库项目在 Visual Studio 中创建一个名为SampleWixExtension的新 C# 类库.dll项目。扩展必须是类库而非可执行程序——仓库内的真实扩展工程 ValidatorExampleExtension.csproj 也明确设置了OutputTypeLibrary/OutputType。第 2 步引用 wix.dll为项目添加对wix.dll的引用。在仓库源码工程里对应的写法是 ProjectReferenceReference IncludeSystem / Reference IncludeSystem.Xml / ProjectReference Include..\..\..\Wix\Wix.csproj /外部开发者则直接引用安装好的 WiX SDK 中的wix.dll即可。第 3 步引入命名空间添加指向核心命名空间的 using 语句using Microsoft.Tools.WindowsInstallerXml;该命名空间是WixExtension与AssemblyDefaultWixExtensionAttribute的所属命名空间可在 WixExtension.cs 与 AssemblyDefaultWixExtensionAttribute.cs 中确认。第 4 步继承 WixExtensionpublic class SampleWixExtension : WixExtension {}空类体即可。WixExtension的抽象能力通过虚属性暴露骨架阶段全部保持默认null实现。第 5 步注册默认扩展类型在项目的AssemblyInfo.cs中添加AssemblyDefaultWixExtensionAttribute[assembly: AssemblyDefaultWixExtension(typeof(SampleWixExtension.SampleWixExtension))]这个属性是命令行“只给 DLL 路径、不指定类名”场景下的关键。从源码看当WixExtension.Load在程序集中找不到显式类名时会通过Attribute.GetCustomAttribute读取该属性来获取默认扩展类型若属性不存在直接抛出InvalidExtensionType异常见 WixExtension.cs 第 226-235 行。该属性本身定义于 AssemblyDefaultWixExtensionAttribute.cs仅允许作用于程序集[AttributeUsage(AttributeTargets.Assembly)]。仓库内的实例可对照 ValidatorExampleExtension 的 AssemblyInfo.cs[assembly: AssemblyDefaultWixExtension(typeof(ValidatorExampleExtension))]第 6 步编译构建项目得到SampleWixExtension.dll。虽然此时这个扩展尚不会做任何事但它已经具备了被 WiX 工具链识别和加载的全部要件。三、用 -ext 验证骨架candle.exe 与 light.exe骨架编译完成后即可将 DLL 通过-ext开关传给 Candle 和 Light 进行编译/链接candle.exe Product.wxs -ext SampleWixExtension.dll light.exe Product.wxs -ext SampleWixExtension.dll这条命令背后的完整调用链可以在仓库源码中逐层验证命令行解析。candle.cs在解析参数时遇到ext会将其取值加入extensionList若-ext后缺少参数则报告TypeSpecificationForExtensionRequired错误candle.cs 第 344-355 行light.cs有完全对称的实现light.cs 第 581-590 行。扩展加载。Candle 对extensionList中每一项调用WixExtension.Load(extension)随后把同一个实例同时注册给预处理器和编译器preprocessor.AddExtension(wixExtension)与compiler.AddExtension(wixExtension)candle.cs 第 149-156 行。Light 侧的差异。Light 除了加载扩展外还会利用扩展的ParseCommandLine消化 light 自身未识别的剩余命令行参数light.cs 第 142-153 行并在后续流程中读取扩展提供的本地化资源此外若扩展提供了CustomBinder可与命令行-binder指定的类名匹配以替换默认绑定器light.cs 第 116-121 行。只要 candle 与 light 都能正常走完编译与链接流程而没有扩展加载错误就证明你的骨架扩展在程序集定位、默认扩展类型解析两个环节上均符合要求。四、WixExtension.Load-ext 参数到底支持哪些写法骨架阶段只需给 DLL 路径但读懂Load的实现有助于排错。WixExtension.LoadWixExtension.cs 第 143-247 行支持 5 种程序集定位形式AssemblyQualifiedName例如MyExt, MyAssembly, Version1.3.0.0, Cultureneutral, PublicKeyTokenb17a5c561934e089AssemblyName例如MyAssembly, Version1.3.0.0, Cultureneutral, PublicKeyTokenb17a5c561934e089绝对路径例如C:\MyExtensions\ExtensionAssembly.dll走Assembly.LoadFrom应用程序目录下的文件名例如ExtensionAssembly.dll相对路径例如..\..\MyExtensions\ExtensionAssembly.dll。另有一条通用规则可以在程序集名前用逗号前缀显式指定扩展类的全名如TopNamespace.ContainingClass, C:\MyExtensions\ExtensionAssembly.dll未指定类名时则回退到第五步的AssemblyDefaultWixExtensionAttribute。加载成功后Load会校验目标类型必须IsSubclassOf(typeof(WixExtension))并用Activator.CreateInstance实例化任何一步失败都会以WixException抛出InvalidExtension或InvalidExtensionType错误这正是-ext参数写错时你在命令行看到的错误来源。五、骨架之后WixExtension 提供的扩展点WixExtension通过一组虚属性把不同阶段的钩子暴露给扩展骨架阶段它们全部返回null后续按需覆盖即可。整理自 WixExtension.cs 的扩展点如下虚成员用途ParseCommandLine(args, messageHandler)解析扩展自定义的命令行参数返回未被解析的参数集合供其他扩展继续处理CompilerExtension提供编译器扩展在单遍编译的相应时机被调用BinderExtension提供绑定器扩展BinderFileManager提供绑定器文件管理器CustomBinder提供对默认绑定器的完整替换DecompilerExtension提供反编译器扩展PreprocessorExtension提供预处理器扩展自定义指令等InspectorExtension提供检查器扩展Light 的 inspector 阶段UnbinderExtension提供解绑器扩展decompile 场景ValidatorExtension提供验证器扩展TableDefinitions注册扩展自带的内部表定义DefaultCulture声明扩展本地化的默认语言GetLibrary(tableDefinitions)返回扩展关联的 WiX 库wixlib基类默认返回null仓库内可运行的完整样例是 ValidatorExampleExtension它覆盖了InspectorExtension与ValidatorExtension两个属性并用私有字段对实例做延迟初始化展示了一个多钩子扩展的典型组织方式——骨架扩展扩展为功能扩展时的形态与它一致。六、继续深入的两条路径骨架代码是 WiX 扩展开发的公共基础完成本文步骤后沿两条主线继续构建自定义操作以骨架代码为起点开发 custom action然后在 WiX 源码中编写对应操作参见仓库文档 Adding a Custom Action构建预处理器扩展完整走一遍扩展含 XSD schema 与表定义的构建流程参见 Creating a Preprocessor Extension。此外扩展开发的通用约定目标框架、schema 编写、RequiredVersion属性等在 Introduction to Developing WiX Extensions 中有系统说明其中特别提到多个同类型扩展之间没有处理顺序保证扩展之间不能存在排序依赖并建议扩展开发者在Wix元素上实现RequiredVersion属性以便安装项目作者锁定扩展版本。七、小结一个可工作的 WiX 骨架扩展只需要四件事继承WixExtension的空类、对wix.dll的引用、AssemblyDefaultWixExtensionAttribute的程序集级注册、以及一次成功的candle.exe / light.exe -ext验证。理解了WixExtension.Load的 5 种程序集定位规则与默认扩展属性的回退机制再配合仓库中ValidatorExampleExtension这一参照实现即可在骨架之上按需覆盖CompilerExtension、ValidatorExtension等虚属性逐步长出完整的自定义扩展。赞分享开发工具构建工具【免费下载链接】wix3WiX Toolset v3.x项目地址https://gitcode.com/gh_mirrors/wi/wix3点击查看免费下载相关推荐终极Ulauncher扩展开发指南从零开始构建你的第一个Linux启动器插件终极Ulauncher扩展开发指南从零开始构建你的第一个Linux启动器插件 Ulauncher是一款功能丰富的Linux应用启动器通过扩展机制可以极大增强桌面应用开发工具VSCodium扩展开发入门从零构建你的第一个插件VSCodium扩展开发入门从零构建你的第一个插件 为什么选择VSCodium开发扩展 VSCodium作为Visual Studio Code的开源替代版本开发工具BlueOcean插件开发入门从零构建你的第一个扩展BlueOcean插件开发入门从零构建你的第一个扩展 BlueOcean是Jenkins的一款革命性插件为开发者提供现代化、直观的持续集成/持续部署 CI/创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考