1. 项目概述：为什么我们需要合并程序集？
在Visual Studio项目开发中，尤其是桌面应用或工具类项目的发布阶段，我们常常会遇到一个不大不小的烦恼：项目编译后，除了主程序（.exe）外，还会生成一堆依赖的DLL文件。对于开发者来说，这再正常不过，但对于最终用户，尤其是那些对技术不甚了解的普通用户，看到安装目录里散落着十几个甚至几十个文件，第一感觉可能就是“不专业”、“复杂”，甚至担心误删了某个文件导致程序无法运行。更实际的问题是，当你需要将一个小工具分发给同事或客户时，发送一个独立的exe文件远比发送一个包含exe和多个dll的文件夹要方便得多，也减少了文件丢失或路径错误的风险。
这就是“DLL合并”或“EXE合并”技术出现的背景。它的核心目标，是将一个主程序（.exe）及其所有依赖的动态链接库（.dll）合并成一个单一的可执行文件。这个单一文件内部已经包含了所有必要的运行时代码，运行时无需再依赖外部的DLL。听起来是不是很美好？这不仅能简化部署，还能在一定程度上保护代码逻辑（虽然不能完全替代混淆或加密），让程序看起来更简洁。
要实现这个目标，社区里有很多工具，比如Costura.Fody、ILRepack等。但今天我们要深入探讨的，是微软官方出品的元老级工具——ILMerge。它直接操作.NET程序集的中间语言（IL），进行深度的合并操作，是理解程序集合并原理的绝佳实践。虽然它现在已不再被积极维护，但其设计思想和实现方式，对于深入理解.NET程序集结构依然具有很高的学习价值。接下来，我将结合多年的项目打包经验，带你从零开始，彻底掌握ILMerge的使用、原理以及那些官方文档里不会告诉你的“坑”。
2. ILMerge工具详解：原理、获取与基础配置
2.1 ILMerge是什么？它的工作原理是什么？
ILMerge，顾名思义，是一个“IL合并器”。IL是.NET平台上的中间语言（Intermediate Language），所有C#、VB.NET等高级语言编写的代码，最终都会被编译成这种与CPU无关的指令集。.NET程序集（.exe或.dll）本质上就是包含了IL代码、元数据（类型、方法等信息）和资源（如图片、字符串表）的PE文件。
ILMerge的工作原理可以概括为以下几个步骤：
- 加载与解析：ILMerge会加载你指定的主程序集（Primary Assembly，通常是你的exe）和所有需要合并的辅助程序集（Secondary Assemblies，即那些DLL）。它会解析这些程序集的所有元数据，包括类型定义、方法签名、引用关系等，构建出一个完整的内存模型。
- 重写与重整：这是最核心的一步。ILMerge会遍历所有程序集中的IL指令。当遇到引用外部程序集类型或方法的指令时（例如
call void [OtherAssembly]OtherNamespace.Class::Method()），ILMerge会将这些外部引用重写为对合并后新程序集内部目标的引用。同时，它需要处理可能出现的命名冲突，例如两个不同的DLL里都有一个叫Helper的类。ILMerge提供了命名空间重定向等机制来解决这个问题。 - 合并资源：除了代码，程序集内嵌的资源（如图标、位图、字符串资源）也会被提取并合并到新的目标程序集中。
- 生成新程序集：最后，ILMerge将所有重写后的IL代码、重整后的元数据以及合并的资源，重新打包成一个全新的、独立的.NET程序集文件。
这个过程听起来简单，但实际操作中，由于.NET程序集依赖关系的复杂性（特别是强命名程序集、友元程序集、InternalsVisibleTo特性等），合并时极易出错。理解其原理，有助于我们在遇到问题时快速定位。
2.2 如何获取与安装ILMerge？
ILMerge是一个命令行工具。虽然微软已将其开源并归档，但获取和使用依然直接。
方法一：通过NuGet安装（推荐）这是目前最方便、最易于与VS项目集成的方法。在你的Visual Studio项目中，通过NuGet包管理器控制台或图形界面，搜索并安装ILMerge包。
Install-Package ILMerge -Version 3.0.41安装后，ILMerge的可执行文件（ILMerge.exe）通常位于项目的packages\ILMerge.3.0.41\tools目录下。这种方式的好处是，工具版本与项目绑定，便于团队协作和构建服务器上的自动化。
方法二：直接下载二进制文件你可以从ILMerge的GitHub发布页面下载编译好的ZIP包，解压后即可得到ILMerge.exe。将其路径添加到系统的PATH环境变量中，就可以在任意命令行窗口使用了。
注意：ILMerge的运行依赖于.NET Framework。如果你的项目是.NET Core/.NET 5+，虽然ILMerge本身是.NET Framework程序，但它仍然可以合并面向.NET Standard或.NET Core的程序集，只要这些程序集是传统的.dll/.exe格式。对于更新的单文件发布需求，微软官方推荐使用
.NETSDK自带的PublishSingleFile功能，我们会在后面进行对比。
2.3 基础命令行参数解析
ILMerge主要通过命令行参数来控制其行为。掌握几个核心参数是成功合并的关键。假设我们有一个主程序MyApp.exe，它依赖于Newtonsoft.Json.dll和MyHelperLib.dll。
一个最基础的合并命令如下：
ILMerge.exe /out:MergedApp.exe MyApp.exe Newtonsoft.Json.dll MyHelperLib.dll/out:：指定合并后输出文件的路径和名称。这是必须的参数。- 后面的参数列表：第一个参数默认为主程序集（primary assembly），之后的所有参数都是需要被合并进去的辅助程序集。
但这远远不够。我们来看几个必须掌握的重要参数：
/target:：指定输出文件的类型。/target:exe：生成控制台应用程序。/target:winexe：生成Windows图形界面应用程序。/target:dll：生成动态链接库。如果你想将多个DLL合并成一个DLL，就使用这个。- 实操心得：这个参数必须与你的主程序集类型匹配！如果你的
MyApp.exe是WinForms程序，但你用了/target:exe，合并后的程序虽然能运行，但可能会失去一些Windows应用程序的特性（比如隐藏控制台窗口）。最稳妥的做法是查看原项目的输出类型，并保持一致。
/targetplatform:：指定目标.NET平台版本。这是最容易出错的地方之一。- 格式：
/targetplatform:version,platformdirectory - 例如：
/targetplatform:v4,C:\Windows\Microsoft.NET\Framework64\v4.0.30319 - 为什么重要？.NET有不同的Profile（如Client Profile, Full Profile）和架构（x86, x64, AnyCPU）。如果平台指定错误，合并后的程序集可能在目标机器上无法加载，提示“找不到对应版本的.NET Framework运行时”。你必须指定一个包含
mscorlib.dll（.NET Framework）或netstandard.dll（.NET Standard）等核心程序集的目录。 - 避坑指南：对于现代的.NET Framework项目，通常使用
v4（即.NET Framework 4.x）。你需要找到本机对应版本的框架目录。对于AnyCPU程序，使用Framework目录；对于x64程序，可能需要使用Framework64目录。如果不确定，一个简单的方法是打开项目的属性页，查看“目标框架”版本，然后去对应的系统目录下确认路径。
- 格式：
/keyfile:与/delaysign:：处理强命名程序集。- 如果你的主程序集或任何依赖的程序集是强命名的（即有数字签名），合并后的程序集也需要被重新签名，否则将无法通过.NET运行时的强名称验证。
/keyfile:MyKey.snk：指定用于签名的密钥文件。/delaysign+：如果原程序集是延迟签名的，也需要加上此参数。- 重要警告：如果你合并了第三方强命名DLL（如
Newtonsoft.Json），而你没有它的私钥，你将无法成功合并出一个强命名程序集。ILMerge会报错。对于这种情况，通常的解决方案是：1) 寻找非强命名版本的第三方库；2) 放弃对自己最终程序集的强命名；3) 使用其他支持“合并后跳过验证”或“重新绑定”的替代工具（如ILRepack有相应选项）。
3. 在Visual Studio项目中集成ILMerge：自动化构建流程
手动在命令行执行合并对于开发调试来说太繁琐了。最佳实践是将ILMerge集成到Visual Studio的构建后事件（Post-Build Event）或MSBuild目标中，实现编译后自动合并。
3.1 使用生成后事件（Post-Build Event）
这是最简单直接的集成方式。在Visual Studio中，右键点击项目 -> “属性” -> “生成事件” -> “后期生成事件命令行”。
假设你的项目输出是$(TargetPath)（即你的exe），并且你通过NuGet安装了ILMerge，它的路径可能是$(SolutionDir)packages\ILMerge.3.0.41\tools\ILMerge.exe。你需要合并Newtonsoft.Json.dll。
一个示例的后期生成事件命令如下：
echo 开始合并程序集... "$(SolutionDir)packages\ILMerge.3.0.41\tools\ILMerge.exe" /target:winexe /targetplatform:v4,"C:\Windows\Microsoft.NET\Framework64\v4.0.30319" /out:"$(TargetDir)Merged\$(TargetName)_Merged$(TargetExt)" "$(TargetPath)" "$(TargetDir)Newtonsoft.Json.dll" echo 合并完成！输出文件位于 $(TargetDir)Merged\命令拆解与注意事项：
echo命令用于在输出窗口显示信息，方便调试。- 使用
$(SolutionDir),$(TargetDir),$(TargetPath),$(TargetName),$(TargetExt)这些Visual Studio预定义的宏，可以确保路径的正确性，无论你的项目名称或输出目录如何变化。 /out参数指定了一个新的输出目录$(TargetDir)Merged\，并将合并后的文件重命名为原名称_Merged.exe。这样做的好处是不会覆盖原始的编译输出，方便对比和调试。- 你需要将
C:\Windows\Microsoft.NET\Framework64\v4.0.30319替换为你机器上确切的.NET Framework路径。对于32位项目，路径可能是C:\Windows\Microsoft.NET\Framework\v4.0.30319。 - 所有需要合并的DLL，都必须列出其完整路径。
$(TargetDir)就是输出目录，通常为bin\Debug\或bin\Release\。
踩坑实录：在生成后事件中，路径中的空格是常见的“杀手”。如果解决方案路径或项目路径包含空格，一定要确保所有路径都用双引号括起来，就像示例中那样。否则，命令会因参数解析错误而失败。
3.2 创建MSBuild目标文件（.targets）实现更精细控制
对于更复杂、需要团队共享的配置，或者项目文件是SDK风格（.NET Core/.NET 5+）的情况，使用MSBuild目标文件是更专业的选择。你可以创建一个ILMerge.targets文件，并将其导入到项目文件（.csproj）中。
步骤一：创建ILMerge.targets文件
<?xml version="1.0" encoding="utf-8"?> <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <!-- 定义ILMerge可执行文件路径，假设通过NuGet安装 --> <PropertyGroup> <ILMergePath Condition="'$(ILMergePath)' == ''">$(NuGetPackageRoot)ilmerge\3.0.41\tools\ILMerge.exe</ILMergePath> <TargetFrameworkVersionForMerge Condition="'$(TargetFrameworkVersionForMerge)' == ''">v4</TargetFrameworkVersionForMerge> <!-- 自动推断平台目录，这是一个简化示例，实际可能需要更复杂的逻辑 --> <NetFrameworkDir Condition="'$(NetFrameworkDir)' == '' AND '$(PlatformTarget)' == 'x64'">C:\Windows\Microsoft.NET\Framework64\$(TargetFrameworkVersionForMerge).0.30319</NetFrameworkDir> <NetFrameworkDir Condition="'$(NetFrameworkDir)' == ''">C:\Windows\Microsoft.NET\Framework\$(TargetFrameworkVersionForMerge).0.30319</NetFrameworkDir> </PropertyGroup> <!-- 定义要合并的程序集列表，可以在项目文件中覆盖此属性 --> <ItemGroup> <AssembliesToMerge Include="Newtonsoft.Json.dll"/> <!-- 可以添加更多 --> </ItemGroup> <!-- 定义ILMerge任务 --> <Target Name="ILMergeAfterBuild" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'"> <!-- 通常只在Release模式下合并 --> <Message Importance="high" Text="开始使用ILMerge合并程序集..." /> <!-- 准备输出目录 --> <MakeDir Directories="$(OutputPath)Merged\" /> <!-- 构建ILMerge命令行参数 --> <ItemGroup> <MergeArgs Include="/target:$(OutputType.ToLower())" /> <MergeArgs Include="/targetplatform:$(TargetFrameworkVersionForMerge),$(NetFrameworkDir)" /> <MergeArgs Include="/out:"$(OutputPath)Merged\$(TargetName)_Merged$(TargetExt)"" /> <MergeArgs Include=""$(TargetPath)"" /> <MergeArgs Include="@(AssembliesToMerge->'"$(OutputPath)%(Identity)"')" /> </ItemGroup> <!-- 执行ILMerge命令 --> <Exec Command=""$(ILMergePath)" @(MergeArgs, ' ')" /> <Message Importance="high" Text="程序集合并完成，输出文件: $(OutputPath)Merged\$(TargetName)_Merged$(TargetExt)" /> </Target> </Project>步骤二：在项目文件（.csproj）中引用在.csproj文件的末尾，</Project>标签之前，添加：
<Import Project="$(MSBuildProjectDirectory)\ILMerge.targets" /> <!-- 如果需要，可以在项目文件中覆盖要合并的程序集列表 --> <ItemGroup> <AssembliesToMerge Include="MyHelperLib.dll" /> <AssembliesToMerge Include="AnotherLib.dll" /> </ItemGroup>这种方法的优势：
- 条件化构建：可以方便地设置为仅在
Release配置下运行（如示例所示）。 - 参数集中管理：所有路径、平台版本都在一个地方配置。
- 易于团队共享：将
.targets文件放在解决方案目录，所有项目都可以引用同一套配置。 - 更强的灵活性：可以定义更复杂的逻辑，比如根据不同的目标框架选择不同的合并策略。
4. 高级用法与疑难问题深度排查
掌握了基础用法，我们来看看那些让新手头疼的高级场景和常见错误。
4.1 处理依赖冲突与内部可见性（InternalsVisibleTo）
场景一：同名类型冲突两个不同的DLL里都有一个完全同名的类（包括命名空间），比如Common.Utility。合并时ILMerge会报错：“Duplicate type 'Common.Utility'”。ILMerge提供了/union参数来处理这种情况。
/union参数会尝试合并这些重复的类型。但慎用！这通常意味着你的项目依赖设计有问题，或者你引入了两个不同版本但包含同名类的库。合并可能导致不可预知的行为。最佳实践是避免引入冲突的库，或者使用别名（extern alias）在代码层面进行区分。
场景二：友元程序集（InternalsVisibleTo）如果你的主程序集通过[assembly: InternalsVisibleTo("MyTestProject")]将内部成员暴露给了一个单元测试项目，合并后这个特性就失效了。因为测试项目期望的友元程序集名称是MyTestProject，而合并后的程序集名字变了（比如叫MergedApp）。
- ILMerge对此无能为力。如果你的程序严重依赖友元程序集特性（比如为了单元测试而大量使用
internal），那么合并程序集可能不是一个好选择。可以考虑其他部署方式，或者调整代码结构，减少对InternalsVisibleTo的依赖。
4.2 合并WPF或WinForms项目时的特殊资源处理
WPF应用程序的XAML文件通常编译为BAML资源并嵌入程序集。WinForms项目则有窗体资源文件（.resx）。ILMerge在默认情况下能够处理这些嵌入式资源。但是，对于WPF，有一个著名的“PresentationFramework版本不匹配”问题。
问题现象：合并一个WPF程序后，运行时可能抛出XamlParseException，提示找不到资源或类型初始化失败。
根本原因：WPF框架本身（PresentationFramework.dll,PresentationCore.dll等）包含大量内部依赖和资源引用。ILMerge在合并时，如果处理不当，可能会破坏WPF程序集内部严格的版本和资源契约。
解决方案：
- 排除WPF核心程序集：绝对不要尝试合并
PresentationFramework.dll,PresentationCore.dll,WindowsBase.dll等WPF框架DLL。它们应该作为外部依赖保留。ILMerge命令中不应包含它们。 - 使用
/wildcards参数需谨慎：不要用/wildcards自动合并bin目录下所有DLL，这很容易误将WPF框架DLL包含进去。 - 考虑替代方案：对于WPF程序，微软官方推荐的部署方式是ClickOnce或MSIX安装包，它们能很好地处理依赖。如果非要单文件，.NET Core 3.0+ 的单文件发布（PublishSingleFile）是更现代、更可靠的选择，它采用“捆绑（Bundling）”而非“合并（Merging）”技术，对WPF支持更好。
4.3 调试合并后的程序集
程序合并后，如何调试？原始的PDB（程序数据库）文件包含了源代码和IL的映射信息。ILMerge也支持合并PDB文件。
- 生成调试信息：在ILMerge命令中添加
/ndebug参数可以禁用调试信息生成。但通常我们想要调试，所以应该省略此参数，或者使用/debug参数（在某些版本中）。 - 实际操作：ILMerge在合并
.exe/.dll时，如果发现同目录下有对应的.pdb文件，它会自动尝试将它们也合并到输出文件的调试信息中。前提是这些PDB文件是存在的。 - 调试配置：在Visual Studio中调试合并后的程序，你需要：
- 确保合并时生成了PDB文件（默认行为）。
- 将合并后的
MergedApp.exe和MergedApp.pdb放在一起。 - 在VS中，选择“调试”->“附加到进程”，找到你的
MergedApp.exe进程并附加。只要PDB和源代码匹配，你就可以像调试原始程序一样设置断点、查看变量。
心得：为了获得最佳的调试体验，建议在项目的“Debug”配置下也启用ILMerge，但输出到独立的目录（如
bin\Debug\Merged\），这样你可以在需要时快速附加调试器。
4.4 常见错误代码与排查表
ILMerge运行出错时，会返回错误代码和简略信息。下表列出了一些常见错误及排查思路：
| 错误提示 / 现象 | 可能原因 | 排查与解决方案 |
|---|---|---|
ILMerge.Merge: ERROR!! | 通用错误，需查看后续详细消息。 | 检查命令行参数格式，特别是路径引号、逗号分隔符。 |
The assembly ‘xxx.dll’ was not found. | 1. DLL路径错误。 2. DLL文件名拼写错误。 3. DLL依赖于其他未指定的DLL。 | 1. 使用绝对路径或确保相对路径正确。 2. 仔细核对文件名。 3. 使用 /lib参数指定额外的库搜索目录，或将该依赖DLL也加入合并列表。 |
Duplicate type ‘XXX.YYY’ found. | 两个被合并的程序集中存在完全同名的类型。 | 1. 检查是否引入了冲突的NuGet包。 2. 如果必须合并，尝试使用 /union参数（风险高）。3. 最佳方案：重构代码或更换库，避免冲突。 |
Strong name signature not valid for this assembly. | 尝试合并强命名程序集，但输出未正确签名或签名失败。 | 1. 使用/keyfile提供有效的签名密钥文件。2. 如果合并了第三方强命名DLL，而你无其私钥，则无法生成强命名合并程序集。考虑放弃强命名或使用非强命名版本库。 |
合并后的程序运行崩溃，提示FileNotFoundException或TypeLoadException | 1. 合并过程遗漏了某个间接依赖。 2. 平台目标（ /targetplatform）指定错误。3. 依赖的Native DLL（C++编写）未被合并（ILMerge只能合并托管DLL）。 | 1. 使用ildasm或dotnet peek等工具查看原始程序集的引用清单，确保所有被引用的托管DLL都已加入合并列表。2. 仔细核对 /targetplatform的版本和目录，确保与项目目标框架完全一致。3. 对于Native DLL，它们无法被ILMerge合并。你需要将它们作为附属文件，与合并后的exe放在同一目录下。 |
| WPF程序合并后界面无法加载 | 误合并了WPF框架DLL或资源处理出错。 | 1. 从合并列表中移除PresentationFramework.dll,PresentationCore.dll,WindowsBase.dll等。2. 优先考虑使用.NET Core+的单文件发布功能。 |
5. ILMerge的替代方案与未来展望
虽然ILMerge是一个强大的学习工具和经典解决方案，但在现代.NET开发中，它已不再是唯一甚至不是最佳的选择。
5.1 .NET Core/5+ 的单文件发布（PublishSingleFile）
这是微软官方推荐的现代方案。在项目文件（.csproj）中添加以下配置：
<PropertyGroup> <PublishSingleFile>true</PublishSingleFile> <SelfContained>true</SelfContained> <!-- 如果需要包含运行时，则为true --> <RuntimeIdentifier>win-x64</RuntimeIdentifier> <!-- 指定运行时标识符 --> </PropertyGroup>然后使用命令行发布：
dotnet publish -c Release -r win-x64与ILMerge的核心区别：
- 技术原理：ILMerge是“合并（Merge）”，将多个程序集的IL代码物理上合并到一个程序集中。而单文件发布是“捆绑（Bundle）”，它将所有依赖的程序集（包括.NET运行时，如果选择自包含）压缩并作为资源打包进一个外壳exe中。运行时，这些程序集会被解压到临时目录再加载。
- 优点：
- 官方支持：与.NET SDK深度集成，未来有保障。
- 兼容性更好：尤其对WPF、Windows Forms等有复杂依赖和资源管理的框架支持更佳。
- 支持自包含：可以将整个.NET运行时一起打包，用户无需安装.NET。
- 启动性能：现代版本在启动解压速度上做了大量优化。
- 缺点：生成的文件体积通常比ILMerge合并的文件大（因为包含了运行时或采用了压缩打包方式）。
5.2 Costura.Fody
这是一个非常流行的NuGet包。你只需要安装它，它就会在编译时通过MSBuild任务自动将所有引用的DLL作为资源嵌入到主程序集中，并在运行时动态从内存加载。
<PackageReference Include="Costura.Fody" Version="5.7.0" />特点：
- 零配置：安装即用，几乎不需要任何额外代码或构建脚本。
- 纯净：输出目录下真的只有一个exe文件，没有临时解压文件（资源在内存中加载）。
- 适合场景：中小型桌面应用程序，追求极简部署。
- 注意：某些杀毒软件可能会对从内存加载代码的行为敏感。
5.3 ILRepack
ILRepack可以看作是ILMerge的一个开源替代品，API兼容，但解决了一些ILMerge的问题（如对某些强命名库的处理更灵活），并且仍在积极维护。
ILRepack.exe /out:Merged.exe MyApp.exe Newtonsoft.Json.dll它的命令行参数与ILMerge高度相似，迁移成本低。如果你在ILMerge上遇到无法解决的强命名或兼容性问题，可以尝试切换到ILRepack。
5.4 方案选择建议
| 特性/需求 | ILMerge | .NET 单文件发布 | Costura.Fody | ILRepack |
|---|---|---|---|---|
| 技术原理 | IL代码合并 | 文件捆绑+运行时 | 嵌入资源+内存加载 | IL代码合并 |
| 维护状态 | 微软归档，不活跃 | 微软官方，活跃 | 社区活跃 | 社区活跃 |
| .NET Core/5+ | 支持（合并托管程序集） | 原生支持 | 支持 | 支持 |
| WPF/WinForms | 兼容性一般，需谨慎 | 兼容性好 | 兼容性好 | 兼容性优于ILMerge |
| 强命名支持 | 严格，需私钥 | 由项目签名决定 | 由项目签名决定 | 相对灵活 |
| 输出纯净度 | 单个exe | 单个exe（可能带.pdb） | 单个exe | 单个exe |
| 启动速度 | 快（直接加载） | 首次稍慢（需解压） | 快（内存加载） | 快（直接加载） |
| 学习/控制度 | 高（需理解参数） | 中（配置简单） | 低（自动完成） | 高（类似ILMerge） |
个人经验选择指南：
- 如果是学习、研究.NET程序集结构，或者维护一个传统的.NET Framework老项目，ILMerge值得深入把玩。
- 如果是全新的.NET Core/5+ 项目，尤其是WPF/WinForms，无脑选择.NET 单文件发布，这是未来的标准。
- 如果追求极致的“单文件”体验，且项目不大，Costura.Fody是最省心的选择。
- 如果在ILMerge上遇到了无法解决的兼容性问题，可以尝试换到ILRepack。
在我自己的项目中，对于需要分发给内部同事使用的小工具（.NET Framework WinForms），我仍然使用ILMerge，因为我对它的行为已经非常熟悉，构建脚本稳定。而对于所有新的.NET 6+项目，我会毫不犹豫地使用单文件发布。工具是手段，最终目的是可靠、便捷地交付软件。理解这些工具背后的原理，能让你在遇到问题时，不再盲目尝试，而是有的放矢地排查和选择。