1. 项目概述为什么我们需要合并程序集在.NET项目开发特别是桌面应用或工具类项目的后期我们经常会遇到一个头疼的问题发布目录下散落着几十个甚至上百个DLL文件。主程序exe孤零零地站在那里周围簇拥着一大堆依赖项。这种场景不仅让最终用户感到困惑“我到底要运行哪个”也给分发和部署带来了麻烦——你得确保所有依赖文件一个不落地打包进去否则程序分分钟崩溃给你看。这时候“dll合并”或“exe合并”的需求就浮出水面了。简单说就是把主程序exe和它依赖的多个动态链接库dll“打包”成一个独立的、可以直接双击运行的可执行文件。ILMerge正是微软官方提供的一个经典工具专门用来解决这个问题。它不是在物理上压缩文件而是在中间语言IL层面进行合并将多个.NET程序集Assembly融合成一个。我经历过不少需要将工具交付给非技术同事或客户的场景每次都要附上一份长长的“使用说明”第一条就是“请把所有文件放在同一个文件夹下”。后来用了ILMerge直接把所有东西合成一个exe发过去对方双击即用体验瞬间提升问题反馈也少了一大半。这不仅仅是技术上的优化更是用户体验和工程效率的实实在在的改进。2. ILMerge核心原理与方案选型2.1 ILMerge是如何工作的要理解ILMerge得先知道.NET程序集是什么。当你用C#、VB.NET等语言编写代码并编译后生成的exe或dll并不是直接的机器码而是一种叫做“中间语言Intermediate Language, IL”的字节码外加描述类型、方法等信息的“元数据Metadata”。IL和元数据共同构成了.NET程序集。ILMerge的工作原理可以形象地理解为“搬家”和“合并户口本”。它读取你指定的主程序集比如YourApp.exe和所有需要合并的依赖程序集比如Newtonsoft.Json.dll, MyHelper.dll解析与提取将每个输入程序集的IL代码和元数据全部解析出来。重命名与重定向这是最关键的一步。为了避免合并后类型名冲突比如两个dll里都有一个叫Helper的类ILMerge会为来自不同程序集的类型生成新的、唯一的命名空间。同时它会重写所有类型引用、方法调用和资源访问的指令让它们指向合并后程序集内部的新位置。生成新程序集将所有处理过的IL代码、元数据、资源如图标、字符串表重新“组装”成一个全新的、独立的程序集。这个新程序集包含了原来所有程序集的功能。所以合并后的exe在运行时不再需要外部的那些dll文件因为它自己内部已经“内置”了所有必需的代码。.NET运行时CLR加载这一个文件就够了。2.2 为什么选择ILMerge与其他方案对比市面上实现程序集合并的方案不止ILMerge一种比如还有Costura.Fody通过嵌入资源的方式、.NET NativeAOT编译等。选择ILMerge通常基于以下几点考量ILMerge的优势官方与稳定由微软研究院开发并维护虽然现在更新不频繁但其核心稳定可靠兼容性经过长期考验。原理透明基于IL合并生成的是标准的.NET程序集调试符号pdb文件也可以合并方便后续调试。控制精细提供丰富的命令行参数可以精确控制内部可见性、入口点、资源处理等。输出单一最终就是一个文件极度简化部署。ILMerge的局限与对比对比Costura.FodyCostura.Fody是一个NuGet包它在编译时将dll作为嵌入资源打包进主exe运行时在内存中动态加载这些dll。它的优点是集成到MSBuild流程中使用更“现代”和方便。缺点是它本质上还是动态加载某些依赖原生库Native DLL或对加载上下文敏感的场景可能会出问题。ILMerge是静态的、彻底的合并生成一个纯粹的单一程序集。对比.NET Native / ReadyToRun这些是更底层的编译技术旨在提升启动性能和减少依赖。但它们主要面向UWP、.NET Core/5的某些发布模式对于传统的.NET Framework桌面应用ILMerge仍然是更通用、更直接的选择。自身局限合并强命名程序集Strong-named Assembly步骤稍复杂无法合并非托管NativeDLL对于某些高度动态如大量使用Reflection.Emit或涉及特定程序集加载逻辑的代码可能不适用。注意如果你的项目已经升级到.NET Core/5/6/7需要关注ILRepack一个ILMerge的分支更新更活跃或直接使用框架自带的“单文件发布Publish Single File”功能后者是微软官方推荐的现代方案。但对于传统的.NET Framework项目.NET 4.x, .NET 3.5等ILMerge依然是主力工具。3. 在Visual Studio项目中集成ILMerge的详细步骤光知道原理不够我们得把它用起来。将ILMerge集成到Visual Studio的生成后事件中可以实现“编译完成后自动合并”一键完成部署准备。3.1 环境准备与工具获取首先你需要获取ILMerge工具。有两种推荐方式直接下载可执行文件从微软的官方下载页或GitHub仓库下载ILMerge.exe。我习惯将其放在一个固定的工具目录下比如C:\BuildTools\ILMerge\。通过NuGet安装推荐在Visual Studio中为你需要合并的项目安装NuGet包ILMerge。安装后ILMerge.exe会出现在项目的packages\ILMerge.x.x.x.x\tools\目录下。这种方式的好处是版本随项目走便于团队协作和构建服务器自动化。对于本教程我们采用NuGet方式因为它与项目绑定无需每台开发机器单独配置路径。3.2 配置项目生成后事件假设我们有一个WinForms桌面应用项目名为MyDesktopApp它引用了Newtonsoft.Json和几个自己编写的类库项目。步骤一安装ILMerge NuGet包在解决方案资源管理器中右键点击需要合并的主项目通常是启动项目MyDesktopApp选择“管理NuGet程序包”。在浏览标签页中搜索ILMerge选择并安装。注意是安装到主项目而不是类库项目。步骤二编写生成后事件脚本右键点击主项目MyDesktopApp选择“属性”。在属性窗口中切换到“生成事件”选项卡。 在“生成后事件命令行”中我们需要输入一段命令。这里给出一个功能完整、带注释的脚本示例你可以根据实际情况修改echo 开始合并程序集... set ILMERGE_PATH$(SolutionDir)packages\ILMerge.3.0.41\tools\ILMerge.exe set OUTPUT_PATH$(TargetDir)merged\$(TargetFileName) set TARGET_KIND$(OutputType) set KEY_FILE$(ProjectDir)MyKey.snk REM 确保输出目录存在 if not exist $(TargetDir)merged mkdir $(TargetDir)merged REM 定义要排除的、不应合并的系统程序集通常以mscorlib, System, Microsoft开头 set EXCLUDE_ASSEMBLIES/internalize /wildcards /allowDup:mscorlib.dll /allowDup:System.dll /allowDup:System.Core.dll REM 定义要合并的第三方及自有DLL列表用空格分隔 set LIBS_TO_MERGENewtonsoft.Json.dll MyHelperLib.dll AnotherLib.dll REM 根据项目类型exe或dll调用ILMerge if $(TARGET_KIND)Exe ( %ILMERGE_PATH% /out:%OUTPUT_PATH% /target:exe /targetplatform:v4,%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.7.2 %EXCLUDE_ASSEMBLIES% $(TargetPath) %LIBS_TO_MERGE% ) else if $(TARGET_KIND)WinExe ( %ILMERGE_PATH% /out:%OUTPUT_PATH% /target:winexe /targetplatform:v4,%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.7.2 %EXCLUDE_ASSEMBLIES% $(TargetPath) %LIBS_TO_MERGE% ) else ( %ILMERGE_PATH% /out:%OUTPUT_PATH% /target:library /targetplatform:v4,%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.7.2 %EXCLUDE_ASSEMBLIES% $(TargetPath) %LIBS_TO_MERGE% ) REM 如果项目有强名称签名并且希望合并后程序集也保持签名添加/keyfile参数需取消下面一行的REM注释 REM if exist %KEY_FILE% ( REM echo 检测到签名密钥文件合并后将重新签名。 REM REM 注意这里需要在上面ILMerge命令行的最后加上 /keyfile:%KEY_FILE% REM ) if %errorlevel% equ 0 ( echo 程序集合并成功输出文件%OUTPUT_PATH% ) else ( echo 程序集合并失败请检查错误信息。 exit 1 )关键参数解析/out:指定合并后的输出文件路径。这里我们输出到$(TargetDir)merged\子目录避免覆盖原编译结果。/target:指定输出类型。exe是控制台应用winexe是Windows窗体/WPF应用无控制台窗口library是类库。/targetplatform:这是最容易出错的地方之一。必须指定目标.NET Framework版本和框架程序集目录。示例中指定了v4和对应路径。你需要根据你的项目目标框架版本调整并确保路径存在。可以打开文件浏览器导航到%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework\下查看具体版本目录。/internalize将除了主程序集外其他所有程序集中的public类型转为internal。这能有效封装内部实现避免合并后对外暴露不必要的API。强烈建议启用。/allowDup允许指定名称的程序集重复。像mscorlib、System这样的核心系统程序集不应被合并必须用此参数排除。/wildcards允许在指定库文件时使用通配符如*.dll但需谨慎容易误合并不需要的dll。/keyfile:如果你的原项目有强名称签名并提供.snk密钥文件路径合并后的程序集也会用相同密钥重新签名。步骤三确定需要合并的DLL列表如何知道哪些DLL需要合并最简单的方法是编译项目后查看输出目录bin\Debug或bin\Release下除了你主exe外还有哪些非系统dll。通常包括你从NuGet安装的第三方包如Newtonsoft.Json.dll。你解决方案中其他项目编译产生的dll如MyHelperLib.dll。 将这些dll文件名填入上面脚本的LIBS_TO_MERGE变量中。注意不要合并.NET Framework自带的系统dll如System.*.dll,Microsoft.*.dll。3.3 验证与测试配置完成后重新生成项目。查看“输出”窗口视图 - 输出应该能看到生成后事件执行的日志。如果成功会在bin\Debug\merged\或Release目录下找到合并后的单一exe文件。验证方法文件依赖检查将合并后的exe复制到一个全新的、空的文件夹中。尝试双击运行。如果正常运行说明合并成功它不再依赖外部dll。使用ILDasm工具这是.NET Framework SDK自带的一个工具ILDasm.exe。用它打开合并前后的exe对比查看命名空间和类型。合并后你应该能看到所有被合并库的类型并且它们的命名空间可能被ILMerge添加了前缀如果使用了/internalize等重命名策略。功能测试全面测试你的应用程序的所有功能确保合并没有引入运行时错误。特别要测试反射Reflection、资源访问、序列化等可能依赖程序集完整名称的功能。4. 高级配置与疑难问题排查4.1 处理强名称程序集与签名如果你的主项目或要合并的库项目使用了强名称签名流程会复杂一些。强名称签名包含了程序集的公钥令牌和哈希值用于保证唯一性和完整性。合并后这个签名就被破坏了。解决方案重新签名使用ILMerge的/keyfile参数指定你的.snk或.pfx密钥文件。ILMerge会在合并完成后用这个密钥为新的程序集重新签名。确保你拥有合法的签名密钥。延迟签名如果是在开发测试阶段可以考虑使用延迟签名合并和测试时不验证强名称。但这不适用于生产发布。合并已签名库如果要合并的第三方库本身是强名称签名的如官方的Newtonsoft.JsonILMerge通常能正确处理。但如果你同时合并多个有强名称的库且它们引用了相同程序集的不同版本可能会引发冲突。实操心得处理强名称合并时务必在干净的测试环境中先行验证。一个常见的坑是开发机器GAC全局程序集缓存里可能有某个库的签名版本导致本地测试通过但到用户机器上失败。始终在无GAC依赖的环境下测试合并后的文件。4.2 排除冲突与依赖问题有时合并会失败报错信息可能关于“重复的类型定义”或“无法解析依赖”。常见冲突场景与处理重复的系统程序集错误信息可能提示mscorlib或System冲突。这是因为被合并的某个dll可能间接引用了这些核心库。永远不要合并系统程序集。使用/allowDup参数明确排除它们如示例中所示。第三方库依赖了特定版本比如LibA依赖Newtonsoft.Json 12.0而你的主项目依赖13.0。如果两者都合并可能会因版本冲突导致运行时错误。策略统一所有项目的依赖版本到一致。如果无法统一可能需要寻找不合并该库或寻找兼容的替代方案。资源文件冲突多个dll可能包含同名资源如图片、字符串资源。ILMerge默认会尝试合并它们但可能失败。可以使用/log参数生成日志文件查看详细过程或使用/union参数尝试合并资源。排查流程简化问题先从合并最少量的dll开始逐步增加定位是哪个dll引起的问题。查看详细日志在ILMerge命令中添加/log:merge.log参数生成详细的合并日志分析冲突点。使用程序集绑定日志查看器Fuslogvw.exe如果合并后的程序集在运行时加载失败可以用这个工具查看程序集绑定失败的具体原因。4.3 性能影响与大小权衡合并会带来两个直观变化文件体积增大和可能影响加载速度。文件大小合并后的exe大小 ≈ 主exe 所有被合并dll的大小之和。因为ILMerge只是拼接没有进行压缩像安装包那样。对于现代存储空间几十MB的增量通常不是问题。加载性能理论上加载一个大的程序集可能比加载多个小dll稍慢因为CLR需要一次性解析更多的元数据。但在绝大多数桌面应用场景中这种差异用户感知不到。相反由于减少了文件I/O和多个程序集的验证、加载开销有时启动速度反而会略有提升。真正的性能瓶颈通常在于代码本身而非合并操作。一个更重要的考量是内存占用。合并后所有代码都位于同一个应用程序域中。这意味着即使你只用到了某个合并库的一小部分功能整个库的元数据和JIT编译后的代码都可能驻留在内存中。对于功能模块众多但每次只使用部分的大型应用这可能不是最优选择。但对于功能明确、所有依赖都会被用到的中小型工具或应用合并利大于弊。5. 现代替代方案与最佳实践建议虽然ILMerge在.NET Framework时代是黄金标准但技术生态在演进。了解当前的最优选择很重要。5.1 .NET Core/5/6/7 的单文件发布如果你已经迁移到.NET Core或.NET 5及以上版本请优先使用官方内置的“单文件发布”功能。这不再是IL层面的合并而是通过一个主机捆绑包host bundle将你的应用和所有依赖包括.NET运行时本身可选打包成一个文件。如何使用在项目文件.csproj中可以添加PublishSingleFiletrue/PublishSingleFile。或者使用命令行dotnet publish -r win-x64 --self-contained true /p:PublishSingleFiletrue。 这种方式更现代、更强大支持包括原生依赖在内的更复杂场景是微软官方推荐的方案。5.2 使用ILRepackILRepack 是 ILMerge 的一个开源分支和增强版。它修复了ILMerge的一些bug提供了更好的命令行接口并且仍在积极维护。如果你的项目遇到ILMerge无法解决的问题比如某些特定的泛型或异步代码合并问题可以尝试切换到ILRepack。用法与ILMerge高度相似通常只需替换可执行文件名和部分参数。5.3 最佳实践总结根据多年经验我总结出以下使用程序集合并的最佳实践明确目标合并是为了简化部署不是为了代码混淆或保护。如果有代码保护需求需要专门的混淆工具。测试至上合并后必须在多种环境干净系统、不同Windows版本下进行完整的冒烟测试和功能测试。特别是涉及动态加载、反射、COM互操作、P/Invoke调用原生代码的部分。版本一致确保解决方案中所有项目以及引用的NuGet包对于公共依赖如Json库、日志库使用统一的版本避免合并后的潜在冲突。渐进合并不要试图一次性合并所有dll。先合并最稳定、最独立的库逐步推进。将系统库、大型框架库如EntityFramework排除在合并范围之外通常是安全的。保留符号在调试阶段合并时保留调试符号pdb文件这样当合并后的程序崩溃时你仍然能获得有意义的堆栈跟踪信息。ILMerge支持/ndebug参数来禁用调试符号生成发布最终版本时才使用它。文档化在团队中将ILMerge的配置生成后事件脚本和合并策略记录在案。这有助于新成员理解和维护构建流程。考虑构建自动化对于团队项目考虑将ILMerge步骤从Visual Studio的生成后事件迁移到统一的CI/CD流水线如Azure DevOps, Jenkins中。这能保证构建环境的一致性避免因开发者机器配置不同导致的问题。可以在MSBuild目标.targets文件中定义ILMerge任务实现更优雅的集成。程序集合并是一个强大的工具它能显著提升最终用户的体验。理解其原理谨慎配置充分测试你就能在简化部署的道路上迈出坚实的一步。对于仍在维护的.NET Framework项目ILMerge依然是值得信赖的老兵而对于新项目不妨直接拥抱.NET现代版本的单文件发布特性。 ILMerge实战：.NET程序集合并原理与Visual Studio集成指南
1. 项目概述为什么我们需要合并程序集在.NET项目开发特别是桌面应用或工具类项目的后期我们经常会遇到一个头疼的问题发布目录下散落着几十个甚至上百个DLL文件。主程序exe孤零零地站在那里周围簇拥着一大堆依赖项。这种场景不仅让最终用户感到困惑“我到底要运行哪个”也给分发和部署带来了麻烦——你得确保所有依赖文件一个不落地打包进去否则程序分分钟崩溃给你看。这时候“dll合并”或“exe合并”的需求就浮出水面了。简单说就是把主程序exe和它依赖的多个动态链接库dll“打包”成一个独立的、可以直接双击运行的可执行文件。ILMerge正是微软官方提供的一个经典工具专门用来解决这个问题。它不是在物理上压缩文件而是在中间语言IL层面进行合并将多个.NET程序集Assembly融合成一个。我经历过不少需要将工具交付给非技术同事或客户的场景每次都要附上一份长长的“使用说明”第一条就是“请把所有文件放在同一个文件夹下”。后来用了ILMerge直接把所有东西合成一个exe发过去对方双击即用体验瞬间提升问题反馈也少了一大半。这不仅仅是技术上的优化更是用户体验和工程效率的实实在在的改进。2. ILMerge核心原理与方案选型2.1 ILMerge是如何工作的要理解ILMerge得先知道.NET程序集是什么。当你用C#、VB.NET等语言编写代码并编译后生成的exe或dll并不是直接的机器码而是一种叫做“中间语言Intermediate Language, IL”的字节码外加描述类型、方法等信息的“元数据Metadata”。IL和元数据共同构成了.NET程序集。ILMerge的工作原理可以形象地理解为“搬家”和“合并户口本”。它读取你指定的主程序集比如YourApp.exe和所有需要合并的依赖程序集比如Newtonsoft.Json.dll, MyHelper.dll解析与提取将每个输入程序集的IL代码和元数据全部解析出来。重命名与重定向这是最关键的一步。为了避免合并后类型名冲突比如两个dll里都有一个叫Helper的类ILMerge会为来自不同程序集的类型生成新的、唯一的命名空间。同时它会重写所有类型引用、方法调用和资源访问的指令让它们指向合并后程序集内部的新位置。生成新程序集将所有处理过的IL代码、元数据、资源如图标、字符串表重新“组装”成一个全新的、独立的程序集。这个新程序集包含了原来所有程序集的功能。所以合并后的exe在运行时不再需要外部的那些dll文件因为它自己内部已经“内置”了所有必需的代码。.NET运行时CLR加载这一个文件就够了。2.2 为什么选择ILMerge与其他方案对比市面上实现程序集合并的方案不止ILMerge一种比如还有Costura.Fody通过嵌入资源的方式、.NET NativeAOT编译等。选择ILMerge通常基于以下几点考量ILMerge的优势官方与稳定由微软研究院开发并维护虽然现在更新不频繁但其核心稳定可靠兼容性经过长期考验。原理透明基于IL合并生成的是标准的.NET程序集调试符号pdb文件也可以合并方便后续调试。控制精细提供丰富的命令行参数可以精确控制内部可见性、入口点、资源处理等。输出单一最终就是一个文件极度简化部署。ILMerge的局限与对比对比Costura.FodyCostura.Fody是一个NuGet包它在编译时将dll作为嵌入资源打包进主exe运行时在内存中动态加载这些dll。它的优点是集成到MSBuild流程中使用更“现代”和方便。缺点是它本质上还是动态加载某些依赖原生库Native DLL或对加载上下文敏感的场景可能会出问题。ILMerge是静态的、彻底的合并生成一个纯粹的单一程序集。对比.NET Native / ReadyToRun这些是更底层的编译技术旨在提升启动性能和减少依赖。但它们主要面向UWP、.NET Core/5的某些发布模式对于传统的.NET Framework桌面应用ILMerge仍然是更通用、更直接的选择。自身局限合并强命名程序集Strong-named Assembly步骤稍复杂无法合并非托管NativeDLL对于某些高度动态如大量使用Reflection.Emit或涉及特定程序集加载逻辑的代码可能不适用。注意如果你的项目已经升级到.NET Core/5/6/7需要关注ILRepack一个ILMerge的分支更新更活跃或直接使用框架自带的“单文件发布Publish Single File”功能后者是微软官方推荐的现代方案。但对于传统的.NET Framework项目.NET 4.x, .NET 3.5等ILMerge依然是主力工具。3. 在Visual Studio项目中集成ILMerge的详细步骤光知道原理不够我们得把它用起来。将ILMerge集成到Visual Studio的生成后事件中可以实现“编译完成后自动合并”一键完成部署准备。3.1 环境准备与工具获取首先你需要获取ILMerge工具。有两种推荐方式直接下载可执行文件从微软的官方下载页或GitHub仓库下载ILMerge.exe。我习惯将其放在一个固定的工具目录下比如C:\BuildTools\ILMerge\。通过NuGet安装推荐在Visual Studio中为你需要合并的项目安装NuGet包ILMerge。安装后ILMerge.exe会出现在项目的packages\ILMerge.x.x.x.x\tools\目录下。这种方式的好处是版本随项目走便于团队协作和构建服务器自动化。对于本教程我们采用NuGet方式因为它与项目绑定无需每台开发机器单独配置路径。3.2 配置项目生成后事件假设我们有一个WinForms桌面应用项目名为MyDesktopApp它引用了Newtonsoft.Json和几个自己编写的类库项目。步骤一安装ILMerge NuGet包在解决方案资源管理器中右键点击需要合并的主项目通常是启动项目MyDesktopApp选择“管理NuGet程序包”。在浏览标签页中搜索ILMerge选择并安装。注意是安装到主项目而不是类库项目。步骤二编写生成后事件脚本右键点击主项目MyDesktopApp选择“属性”。在属性窗口中切换到“生成事件”选项卡。 在“生成后事件命令行”中我们需要输入一段命令。这里给出一个功能完整、带注释的脚本示例你可以根据实际情况修改echo 开始合并程序集... set ILMERGE_PATH$(SolutionDir)packages\ILMerge.3.0.41\tools\ILMerge.exe set OUTPUT_PATH$(TargetDir)merged\$(TargetFileName) set TARGET_KIND$(OutputType) set KEY_FILE$(ProjectDir)MyKey.snk REM 确保输出目录存在 if not exist $(TargetDir)merged mkdir $(TargetDir)merged REM 定义要排除的、不应合并的系统程序集通常以mscorlib, System, Microsoft开头 set EXCLUDE_ASSEMBLIES/internalize /wildcards /allowDup:mscorlib.dll /allowDup:System.dll /allowDup:System.Core.dll REM 定义要合并的第三方及自有DLL列表用空格分隔 set LIBS_TO_MERGENewtonsoft.Json.dll MyHelperLib.dll AnotherLib.dll REM 根据项目类型exe或dll调用ILMerge if $(TARGET_KIND)Exe ( %ILMERGE_PATH% /out:%OUTPUT_PATH% /target:exe /targetplatform:v4,%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.7.2 %EXCLUDE_ASSEMBLIES% $(TargetPath) %LIBS_TO_MERGE% ) else if $(TARGET_KIND)WinExe ( %ILMERGE_PATH% /out:%OUTPUT_PATH% /target:winexe /targetplatform:v4,%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.7.2 %EXCLUDE_ASSEMBLIES% $(TargetPath) %LIBS_TO_MERGE% ) else ( %ILMERGE_PATH% /out:%OUTPUT_PATH% /target:library /targetplatform:v4,%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.7.2 %EXCLUDE_ASSEMBLIES% $(TargetPath) %LIBS_TO_MERGE% ) REM 如果项目有强名称签名并且希望合并后程序集也保持签名添加/keyfile参数需取消下面一行的REM注释 REM if exist %KEY_FILE% ( REM echo 检测到签名密钥文件合并后将重新签名。 REM REM 注意这里需要在上面ILMerge命令行的最后加上 /keyfile:%KEY_FILE% REM ) if %errorlevel% equ 0 ( echo 程序集合并成功输出文件%OUTPUT_PATH% ) else ( echo 程序集合并失败请检查错误信息。 exit 1 )关键参数解析/out:指定合并后的输出文件路径。这里我们输出到$(TargetDir)merged\子目录避免覆盖原编译结果。/target:指定输出类型。exe是控制台应用winexe是Windows窗体/WPF应用无控制台窗口library是类库。/targetplatform:这是最容易出错的地方之一。必须指定目标.NET Framework版本和框架程序集目录。示例中指定了v4和对应路径。你需要根据你的项目目标框架版本调整并确保路径存在。可以打开文件浏览器导航到%ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\.NETFramework\下查看具体版本目录。/internalize将除了主程序集外其他所有程序集中的public类型转为internal。这能有效封装内部实现避免合并后对外暴露不必要的API。强烈建议启用。/allowDup允许指定名称的程序集重复。像mscorlib、System这样的核心系统程序集不应被合并必须用此参数排除。/wildcards允许在指定库文件时使用通配符如*.dll但需谨慎容易误合并不需要的dll。/keyfile:如果你的原项目有强名称签名并提供.snk密钥文件路径合并后的程序集也会用相同密钥重新签名。步骤三确定需要合并的DLL列表如何知道哪些DLL需要合并最简单的方法是编译项目后查看输出目录bin\Debug或bin\Release下除了你主exe外还有哪些非系统dll。通常包括你从NuGet安装的第三方包如Newtonsoft.Json.dll。你解决方案中其他项目编译产生的dll如MyHelperLib.dll。 将这些dll文件名填入上面脚本的LIBS_TO_MERGE变量中。注意不要合并.NET Framework自带的系统dll如System.*.dll,Microsoft.*.dll。3.3 验证与测试配置完成后重新生成项目。查看“输出”窗口视图 - 输出应该能看到生成后事件执行的日志。如果成功会在bin\Debug\merged\或Release目录下找到合并后的单一exe文件。验证方法文件依赖检查将合并后的exe复制到一个全新的、空的文件夹中。尝试双击运行。如果正常运行说明合并成功它不再依赖外部dll。使用ILDasm工具这是.NET Framework SDK自带的一个工具ILDasm.exe。用它打开合并前后的exe对比查看命名空间和类型。合并后你应该能看到所有被合并库的类型并且它们的命名空间可能被ILMerge添加了前缀如果使用了/internalize等重命名策略。功能测试全面测试你的应用程序的所有功能确保合并没有引入运行时错误。特别要测试反射Reflection、资源访问、序列化等可能依赖程序集完整名称的功能。4. 高级配置与疑难问题排查4.1 处理强名称程序集与签名如果你的主项目或要合并的库项目使用了强名称签名流程会复杂一些。强名称签名包含了程序集的公钥令牌和哈希值用于保证唯一性和完整性。合并后这个签名就被破坏了。解决方案重新签名使用ILMerge的/keyfile参数指定你的.snk或.pfx密钥文件。ILMerge会在合并完成后用这个密钥为新的程序集重新签名。确保你拥有合法的签名密钥。延迟签名如果是在开发测试阶段可以考虑使用延迟签名合并和测试时不验证强名称。但这不适用于生产发布。合并已签名库如果要合并的第三方库本身是强名称签名的如官方的Newtonsoft.JsonILMerge通常能正确处理。但如果你同时合并多个有强名称的库且它们引用了相同程序集的不同版本可能会引发冲突。实操心得处理强名称合并时务必在干净的测试环境中先行验证。一个常见的坑是开发机器GAC全局程序集缓存里可能有某个库的签名版本导致本地测试通过但到用户机器上失败。始终在无GAC依赖的环境下测试合并后的文件。4.2 排除冲突与依赖问题有时合并会失败报错信息可能关于“重复的类型定义”或“无法解析依赖”。常见冲突场景与处理重复的系统程序集错误信息可能提示mscorlib或System冲突。这是因为被合并的某个dll可能间接引用了这些核心库。永远不要合并系统程序集。使用/allowDup参数明确排除它们如示例中所示。第三方库依赖了特定版本比如LibA依赖Newtonsoft.Json 12.0而你的主项目依赖13.0。如果两者都合并可能会因版本冲突导致运行时错误。策略统一所有项目的依赖版本到一致。如果无法统一可能需要寻找不合并该库或寻找兼容的替代方案。资源文件冲突多个dll可能包含同名资源如图片、字符串资源。ILMerge默认会尝试合并它们但可能失败。可以使用/log参数生成日志文件查看详细过程或使用/union参数尝试合并资源。排查流程简化问题先从合并最少量的dll开始逐步增加定位是哪个dll引起的问题。查看详细日志在ILMerge命令中添加/log:merge.log参数生成详细的合并日志分析冲突点。使用程序集绑定日志查看器Fuslogvw.exe如果合并后的程序集在运行时加载失败可以用这个工具查看程序集绑定失败的具体原因。4.3 性能影响与大小权衡合并会带来两个直观变化文件体积增大和可能影响加载速度。文件大小合并后的exe大小 ≈ 主exe 所有被合并dll的大小之和。因为ILMerge只是拼接没有进行压缩像安装包那样。对于现代存储空间几十MB的增量通常不是问题。加载性能理论上加载一个大的程序集可能比加载多个小dll稍慢因为CLR需要一次性解析更多的元数据。但在绝大多数桌面应用场景中这种差异用户感知不到。相反由于减少了文件I/O和多个程序集的验证、加载开销有时启动速度反而会略有提升。真正的性能瓶颈通常在于代码本身而非合并操作。一个更重要的考量是内存占用。合并后所有代码都位于同一个应用程序域中。这意味着即使你只用到了某个合并库的一小部分功能整个库的元数据和JIT编译后的代码都可能驻留在内存中。对于功能模块众多但每次只使用部分的大型应用这可能不是最优选择。但对于功能明确、所有依赖都会被用到的中小型工具或应用合并利大于弊。5. 现代替代方案与最佳实践建议虽然ILMerge在.NET Framework时代是黄金标准但技术生态在演进。了解当前的最优选择很重要。5.1 .NET Core/5/6/7 的单文件发布如果你已经迁移到.NET Core或.NET 5及以上版本请优先使用官方内置的“单文件发布”功能。这不再是IL层面的合并而是通过一个主机捆绑包host bundle将你的应用和所有依赖包括.NET运行时本身可选打包成一个文件。如何使用在项目文件.csproj中可以添加PublishSingleFiletrue/PublishSingleFile。或者使用命令行dotnet publish -r win-x64 --self-contained true /p:PublishSingleFiletrue。 这种方式更现代、更强大支持包括原生依赖在内的更复杂场景是微软官方推荐的方案。5.2 使用ILRepackILRepack 是 ILMerge 的一个开源分支和增强版。它修复了ILMerge的一些bug提供了更好的命令行接口并且仍在积极维护。如果你的项目遇到ILMerge无法解决的问题比如某些特定的泛型或异步代码合并问题可以尝试切换到ILRepack。用法与ILMerge高度相似通常只需替换可执行文件名和部分参数。5.3 最佳实践总结根据多年经验我总结出以下使用程序集合并的最佳实践明确目标合并是为了简化部署不是为了代码混淆或保护。如果有代码保护需求需要专门的混淆工具。测试至上合并后必须在多种环境干净系统、不同Windows版本下进行完整的冒烟测试和功能测试。特别是涉及动态加载、反射、COM互操作、P/Invoke调用原生代码的部分。版本一致确保解决方案中所有项目以及引用的NuGet包对于公共依赖如Json库、日志库使用统一的版本避免合并后的潜在冲突。渐进合并不要试图一次性合并所有dll。先合并最稳定、最独立的库逐步推进。将系统库、大型框架库如EntityFramework排除在合并范围之外通常是安全的。保留符号在调试阶段合并时保留调试符号pdb文件这样当合并后的程序崩溃时你仍然能获得有意义的堆栈跟踪信息。ILMerge支持/ndebug参数来禁用调试符号生成发布最终版本时才使用它。文档化在团队中将ILMerge的配置生成后事件脚本和合并策略记录在案。这有助于新成员理解和维护构建流程。考虑构建自动化对于团队项目考虑将ILMerge步骤从Visual Studio的生成后事件迁移到统一的CI/CD流水线如Azure DevOps, Jenkins中。这能保证构建环境的一致性避免因开发者机器配置不同导致的问题。可以在MSBuild目标.targets文件中定义ILMerge任务实现更优雅的集成。程序集合并是一个强大的工具它能显著提升最终用户的体验。理解其原理谨慎配置充分测试你就能在简化部署的道路上迈出坚实的一步。对于仍在维护的.NET Framework项目ILMerge依然是值得信赖的老兵而对于新项目不妨直接拥抱.NET现代版本的单文件发布特性。