將多個專案組件 (DLL) 合併為單一執行檔,可簡化部署、避免 DLL Hell、保護智慧財產。本文比較三種主流方案:**ILMerge (傳統)**、**Costura.Fody (編織/內嵌資源)**、**單一專案多檔案編譯 (Source Merge)**,並說明適用條件、限制與遷移建議。
| 方案 | 原理 | 支援 .NET Framework | 支援 .NET Core / .NET 5+ | 強名稱/簽署 | PDB 除錯符號 | 維護狀態 |
|---|---|---|---|---|---|---|
| ILMerge | 後處理合併 IL | ✅ 完整 | ❌ 不支援 | 需額外簽署 | 支援 | 維護模式 (2018 後無更新) |
| Costura.Fody | 編譯期織入,DLL 內嵌為資源,運行時解壓 | ✅ | ✅ (需 Fody 6+) | 自動保留 | 支援 | 活躍 |
| 單一專案多檔案 (Source Merge) | 將所有 .cs 納入同一專案編譯 | ✅ | ✅ | 原生 | 原生 | 原生支援 |
| .NET Core 單檔發佈 | `PublishSingleFile=true` + `IncludeNativeLibrariesForSelfExtract` | ❌ | ✅ 原生 | 原生 | 原生 | 官方標準 |
// 安裝
nuget install ILMerge -Version 3.0.41
// 命令列合併
ilmerge /out:MergedApp.exe /target:exe /targetplatform:v4,C:\Windows\Microsoft.NET\Framework\v4.0.30319 \
Primary.exe Lib1.dll Lib2.dll /ndebug /copyattrs /log:ilmerge.log
// 專案後建置事件自動化
"$(SolutionDir)packages\ILMerge.3.0.41\tools\ilmerge.exe" /out:"$(TargetDir)Merged.$(TargetFileName)" "$(TargetPath)" "$(TargetDir)Lib1.dll" "$(TargetDir)Lib2.dll" /target:library /ndebug
⚠️ **限制**:不支援 .NET Core/.NET 5+、WPF 資源合併易出錯、強名稱需額外 `sn -Ra`。
<Weavers xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FodyWeavers.xsd">
<Costura CreateTemporaryAssemblies="false" IncludeDebugSymbols="true" />
</Weavers>
✅ **優點**:零程式碼修改、支援強名稱、保留 PDB、支援 .NET Framework 4.6.2+ / .NET Core 3.1+ (Fody 6+)。
將多個類庫專案的 `.cs` 檔案以 `
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup><OutputType>Exe</OutputType><TargetFramework>net48</TargetFramework></PropertyGroup>
<ItemGroup>
<Compile Include="..\Lib1\**\*.cs" Exclude="..\Lib1\obj\**;..\Lib1\bin\**;..\Lib1\Properties\AssemblyInfo.cs" />
<Compile Include="..\Lib2\**\*.cs" Exclude="..\Lib2\obj\**;..\Lib2\bin\**;..\Lib2\Properties\AssemblyInfo.cs" />
</ItemGroup>
</Project>
⚠️ **注意**:命名空間衝突、內部類別可見度變更、專案結構耦合。適合**完全自有原始碼**且團隊同意合併倉庫時。
dotnet publish -r win-x64 -c Release /p:PublishSingleFile=true /p:IncludeNativeLibrariesForSelfExtract=true /p:EnableCompressionInSingleFile=true
目標框架?
├─ .NET Framework 4.x (舊專案)
│ ├─ 需保留獨立 DLL 給其他程式參考? → 否 → Costura.Fody (最省力)
│ └─ 必須合併為單一檔案? → ILMerge (若 Costura 失敗)
├─ .NET Core 3.1 / .NET 5+ (新專案)
│ ├─ Self-contained 單檔? → `PublishSingleFile=true` (官方標準)
│ └─ Framework-dependent 單檔? → `PublishSingleFile=true` + `SelfContained=false`
└─ 完全自有原始碼且願意合併專案 → Source Merge (csproj Include)
依專案框架、原始碼擁有權、部署限制選擇合適方案;現代 .NET 專案請優先使用官方單檔發佈,舊專案以 Costura.Fody 為最佳平衡點。