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）：

1. 解析与提取：将每个输入程序集的IL代码和元数据全部解析出来。
2. 重命名与重定向：这是最关键的一步。为了避免合并后类型名冲突（比如两个dll里都有一个叫Helper的类），ILMerge会为来自不同程序集的类型生成新的、唯一的命名空间。同时，它会重写所有类型引用、方法调用和资源访问的指令，让它们指向合并后程序集内部的新位置。
3. 生成新程序集：将所有处理过的IL代码、元数据、资源（如图标、字符串表）重新“组装”成一个全新的、独立的程序集。这个新程序集包含了原来所有程序集的功能。

所以，合并后的exe在运行时，不再需要外部的那些dll文件，因为它自己内部已经“内置”了所有必需的代码。.NET运行时（CLR）加载这一个文件就够了。

2.2 为什么选择ILMerge？与其他方案对比

市面上实现程序集合并的方案不止ILMerge一种，比如还有Costura.Fody（通过嵌入资源的方式）、.NET Native（AOT编译）等。选择ILMerge通常基于以下几点考量：

ILMerge的优势：

1. 官方与稳定：由微软研究院开发并维护，虽然现在更新不频繁，但其核心稳定可靠，兼容性经过长期考验。
2. 原理透明：基于IL合并，生成的是标准的.NET程序集，调试符号（pdb文件）也可以合并，方便后续调试。
3. 控制精细：提供丰富的命令行参数，可以精确控制内部可见性、入口点、资源处理等。
4. 输出单一：最终就是一个文件，极度简化部署。

ILMerge的局限与对比：

• 对比Costura.Fody：Costura.Fody是一个NuGet包，它在编译时将dll作为嵌入资源打包进主exe，运行时在内存中动态加载这些dll。它的优点是集成到MSBuild流程中，使用更“现代”和方便。缺点是它本质上还是动态加载，某些依赖原生库（Native DLL）或对加载上下文敏感的场景可能会出问题。ILMerge是静态的、彻底的合并，生成一个纯粹的单一程序集。
• 对比.NET Native / ReadyToRun：这些是更底层的编译技术，旨在提升启动性能和减少依赖。但它们主要面向UWP、.NET Core/5+的某些发布模式，对于传统的.NET Framework桌面应用，ILMerge仍然是更通用、更直接的选择。
• 自身局限：合并强命名程序集（Strong-named Assembly）步骤稍复杂；无法合并非托管（Native）DLL；对于某些高度动态（如大量使用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工具。有两种推荐方式：

1. 直接下载可执行文件：从微软的官方下载页或GitHub仓库下载ILMerge.exe。我习惯将其放在一个固定的工具目录下，比如C:\BuildTools\ILMerge\。
2. 通过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_MERGE=Newtonsoft.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。通常包括：

1. 你从NuGet安装的第三方包（如Newtonsoft.Json.dll）。
2. 你解决方案中其他项目编译产生的dll（如MyHelperLib.dll）。 将这些dll文件名填入上面脚本的LIBS_TO_MERGE变量中。注意：不要合并.NET Framework自带的系统dll（如System.*.dll,Microsoft.*.dll）。

3.3 验证与测试

配置完成后，重新生成项目。查看“输出”窗口（视图 -> 输出），应该能看到生成后事件执行的日志。如果成功，会在bin\Debug\merged\（或Release）目录下找到合并后的单一exe文件。

验证方法：

1. 文件依赖检查：将合并后的exe复制到一个全新的、空的文件夹中。尝试双击运行。如果正常运行，说明合并成功，它不再依赖外部dll。
2. 使用ILDasm工具：这是.NET Framework SDK自带的一个工具（ILDasm.exe）。用它打开合并前后的exe，对比查看命名空间和类型。合并后，你应该能看到所有被合并库的类型，并且它们的命名空间可能被ILMerge添加了前缀（如果使用了/internalize等重命名策略）。
3. 功能测试：全面测试你的应用程序的所有功能，确保合并没有引入运行时错误。特别要测试反射（Reflection）、资源访问、序列化等可能依赖程序集完整名称的功能。

4. 高级配置与疑难问题排查

4.1 处理强名称程序集与签名

如果你的主项目或要合并的库项目使用了强名称签名，流程会复杂一些。强名称签名包含了程序集的公钥令牌和哈希值，用于保证唯一性和完整性。合并后，这个签名就被破坏了。

解决方案：

1. 重新签名：使用ILMerge的/keyfile参数，指定你的.snk或.pfx密钥文件。ILMerge会在合并完成后，用这个密钥为新的程序集重新签名。确保你拥有合法的签名密钥。
2. 延迟签名：如果是在开发测试阶段，可以考虑使用延迟签名，合并和测试时不验证强名称。但这不适用于生产发布。
3. 合并已签名库：如果要合并的第三方库本身是强名称签名的（如官方的Newtonsoft.Json），ILMerge通常能正确处理。但如果你同时合并多个有强名称的库，且它们引用了相同程序集的不同版本，可能会引发冲突。

实操心得：处理强名称合并时，务必在干净的测试环境中先行验证。一个常见的坑是，开发机器GAC（全局程序集缓存）里可能有某个库的签名版本，导致本地测试通过，但到用户机器上失败。始终在无GAC依赖的环境下测试合并后的文件。

4.2 排除冲突与依赖问题

有时合并会失败，报错信息可能关于“重复的类型定义”或“无法解析依赖”。

常见冲突场景与处理：

1. 重复的系统程序集：错误信息可能提示mscorlib或System冲突。这是因为被合并的某个dll可能间接引用了这些核心库。永远不要合并系统程序集。使用/allowDup参数明确排除它们，如示例中所示。
2. 第三方库依赖了特定版本：比如LibA依赖Newtonsoft.Json 12.0，而你的主项目依赖13.0。如果两者都合并，可能会因版本冲突导致运行时错误。策略：统一所有项目的依赖版本到一致。如果无法统一，可能需要寻找不合并该库，或寻找兼容的替代方案。
3. 资源文件冲突：多个dll可能包含同名资源（如图片、字符串资源）。ILMerge默认会尝试合并它们，但可能失败。可以使用/log参数生成日志文件查看详细过程，或使用/union参数尝试合并资源。

排查流程：

1. 简化问题：先从合并最少量的dll开始，逐步增加，定位是哪个dll引起的问题。
2. 查看详细日志：在ILMerge命令中添加/log:merge.log参数，生成详细的合并日志，分析冲突点。
3. 使用程序集绑定日志查看器（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运行时本身，可选）打包成一个文件。

如何使用：

1. 在项目文件（.csproj）中，可以添加<PublishSingleFile>true</PublishSingleFile>。
2. 或者使用命令行：dotnet publish -r win-x64 --self-contained true /p:PublishSingleFile=true。 这种方式更现代、更强大，支持包括原生依赖在内的更复杂场景，是微软官方推荐的方案。

5.2 使用ILRepack

ILRepack 是 ILMerge 的一个开源分支和增强版。它修复了ILMerge的一些bug，提供了更好的命令行接口，并且仍在积极维护。如果你的项目遇到ILMerge无法解决的问题（比如某些特定的泛型或异步代码合并问题），可以尝试切换到ILRepack。用法与ILMerge高度相似，通常只需替换可执行文件名和部分参数。

5.3 最佳实践总结

根据多年经验，我总结出以下使用程序集合并的最佳实践：

1. 明确目标：合并是为了简化部署，不是为了代码混淆或保护。如果有代码保护需求，需要专门的混淆工具。
2. 测试至上：合并后必须在多种环境（干净系统、不同Windows版本）下进行完整的冒烟测试和功能测试。特别是涉及动态加载、反射、COM互操作、P/Invoke调用原生代码的部分。
3. 版本一致：确保解决方案中所有项目以及引用的NuGet包，对于公共依赖（如Json库、日志库）使用统一的版本，避免合并后的潜在冲突。
4. 渐进合并：不要试图一次性合并所有dll。先合并最稳定、最独立的库，逐步推进。将系统库、大型框架库（如EntityFramework）排除在合并范围之外通常是安全的。
5. 保留符号：在调试阶段，合并时保留调试符号（pdb文件），这样当合并后的程序崩溃时，你仍然能获得有意义的堆栈跟踪信息。ILMerge支持/ndebug参数来禁用调试符号生成，发布最终版本时才使用它。
6. 文档化：在团队中，将ILMerge的配置（生成后事件脚本）和合并策略记录在案。这有助于新成员理解和维护构建流程。
7. 考虑构建自动化：对于团队项目，考虑将ILMerge步骤从Visual Studio的生成后事件迁移到统一的CI/CD流水线（如Azure DevOps, Jenkins）中。这能保证构建环境的一致性，避免因开发者机器配置不同导致的问题。可以在MSBuild目标（.targets文件）中定义ILMerge任务，实现更优雅的集成。

程序集合并是一个强大的工具，它能显著提升最终用户的体验。理解其原理，谨慎配置，充分测试，你就能在简化部署的道路上迈出坚实的一步。对于仍在维护的.NET Framework项目，ILMerge依然是值得信赖的老兵；而对于新项目，不妨直接拥抱.NET现代版本的单文件发布特性。