ILMerge

ILMerge is a static linker for .NET Assemblies.

1,284

177

1,284

View on GitHub

Top Related Projects

DotNetCorePlugins

1,710

.NET Core library for dynamically loading code

Fody

4,457

Extensible tool for weaving .net assemblies

Harmony

5,635

A library for patching, replacing and decorating .NET and Mono methods during runtime

Quick Overview

ILMerge is a utility for merging multiple .NET assemblies into a single assembly. It is useful for combining related assemblies into a single, easy-to-distribute file, which can simplify deployment and reduce the complexity of managing multiple DLLs.

Pros

Simplifies deployment by reducing the number of files to distribute
Helps prevent assembly version conflicts
Can potentially improve application load time
Supports merging assemblies targeting different .NET Framework versions

Cons

May increase the size of the final assembly
Can complicate debugging, as line numbers may not match the original source
Not officially supported for .NET Core or .NET 5+ projects
May encounter issues with certain types of assemblies or dependencies

Getting Started

To use ILMerge, follow these steps:

Install ILMerge via NuGet Package Manager:
```
Install-Package ILMerge
```
Use the ILMerge command-line tool or integrate it into your build process. Here's a basic command-line example:
```
ilmerge /out:merged.dll assembly1.dll assembly2.dll assembly3.dll
```
For more advanced scenarios, consider using ILMerge in a post-build event or as part of an MSBuild task.

Note: Always test thoroughly after merging assemblies to ensure functionality is preserved.

Competitor Comparisons

DotNetCorePlugins

1,710

.NET Core library for dynamically loading code

Pros of DotNetCorePlugins

Designed specifically for .NET Core, offering better compatibility with modern .NET applications
Supports dynamic loading and unloading of assemblies at runtime
Allows for isolation of plugin assemblies, reducing potential conflicts

Cons of DotNetCorePlugins

Limited to .NET Core applications, not suitable for older .NET Framework projects
Requires more setup and configuration compared to ILMerge's simpler approach
May introduce additional complexity in managing plugin lifecycles

Code Comparison

ILMerge:

ILMerge merger = new ILMerge();
merger.SetInputAssemblies(new string[] { "MainAssembly.dll", "Plugin1.dll", "Plugin2.dll" });
merger.OutputFile = "MergedAssembly.dll";
merger.Merge();

DotNetCorePlugins:

var loader = PluginLoader.CreateFromAssemblyFile(
    assemblyFile: "Plugin1.dll",
    sharedTypes: new[] { typeof(IPlugin) },
    isUnloadable: true);
var plugin = loader.LoadDefaultAssembly().CreateInstance("Plugin1.MyPlugin") as IPlugin;
plugin.Execute();

Fody

4,457

Extensible tool for weaving .net assemblies

Pros of Fody

More flexible and extensible with a plugin-based architecture
Supports a wider range of IL weaving tasks beyond just merging assemblies
Active development and community support

Cons of Fody

Steeper learning curve due to its plugin system
May require more configuration and setup for specific tasks

Code Comparison

Fody (using Costura.Fody for embedding dependencies):

<ItemGroup>
  <PackageReference Include="Fody" Version="6.5.1">
    <PrivateAssets>all</PrivateAssets>
    <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
  </PackageReference>
  <PackageReference Include="Costura.Fody" Version="5.3.0" />
</ItemGroup>

ILMerge (command-line usage):

ilmerge /out:output.exe /target:exe input.exe dependency1.dll dependency2.dll

Summary

Fody is a more versatile tool for IL weaving tasks, offering a plugin-based system that can handle various operations beyond merging assemblies. It's actively maintained and has strong community support. However, it may require more setup and has a steeper learning curve compared to ILMerge.

ILMerge, on the other hand, is focused specifically on merging .NET assemblies. It's simpler to use for this specific task but lacks the flexibility and extensibility of Fody. The choice between the two depends on the specific requirements of your project and the range of IL manipulation tasks you need to perform.

Costura

2,475

Embed references as resources

Pros of Costura

Easier to use with a more streamlined setup process
Integrates seamlessly with the build process as a NuGet package
Supports compressing embedded resources for smaller output files

Cons of Costura

Limited control over the merging process compared to ILMerge
May have compatibility issues with certain types of assemblies
Potential performance impact due to runtime unpacking of compressed resources

Code Comparison

Costura:

[assembly: Costura.AssemblyLoader(DisableCompression = true)]

ILMerge:

ILMerge merger = new ILMerge();
merger.SetInputAssemblies(new string[] { "MainAssembly.dll", "Dependency1.dll", "Dependency2.dll" });
merger.OutputFile = "Merged.exe";
merger.Merge();

Summary

Costura is a more user-friendly option for embedding dependencies, offering easy integration and compression features. However, it may lack the fine-grained control and flexibility provided by ILMerge. ILMerge offers more control over the merging process but requires more manual configuration. The choice between the two depends on project requirements, desired level of control, and ease of use preferences.

Harmony

5,635

A library for patching, replacing and decorating .NET and Mono methods during runtime

Pros of Harmony

Allows runtime patching of .NET methods without modifying the original assemblies
Provides a high-level API for method manipulation, making it easier to use than low-level IL manipulation
Supports a wide range of patching scenarios, including prefix, postfix, and transpiler patches

Cons of Harmony

Requires more runtime overhead compared to compile-time merging
May have compatibility issues with some security restrictions or managed environments
Learning curve can be steeper for developers unfamiliar with runtime patching concepts

Code Comparison

Harmony patch example:

[HarmonyPatch(typeof(TargetClass), "TargetMethod")]
class Patch
{
    static void Postfix(ref int __result)
    {
        __result *= 2;
    }
}

ILMerge usage example:

ILMerge merger = new ILMerge();
merger.SetInputAssemblies(new string[] { "Assembly1.dll", "Assembly2.dll" });
merger.OutputFile = "Merged.dll";
merger.Merge();

Summary

Harmony focuses on runtime method patching, offering flexibility and ease of use for modifying existing code without recompilation. ILMerge, on the other hand, is designed for compile-time merging of assemblies, which can be more efficient but less flexible. The choice between the two depends on the specific requirements of the project, such as runtime modification needs, performance considerations, and deployment constraints.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

ILMerge

ILMerge is a utility that merges multiple .NET assemblies into a single assembly. It is freely available for use and is available as a NuGet package.

If you have any problems using it, please get in touch. (mbarnett at microsoft dot com). But first try reading the documentation.

ILMerge takes a set of input assemblies and merges them into one target assembly. The first assembly in the list of input assemblies is the primary assembly. When the primary assembly is an executable, then the target assembly is created as an executable with the same entry point as the primary assembly. Also, if the primary assembly has a strong name, and a .snk file is provided, then the target assembly is re-signed with the specified key so that it also has a strong name.

ILMerge is packaged as a console application. But all of its functionality is also available programmatically.

There are several options that control the behavior of ILMerge. See the documentation that comes with the tool for details.

The current version is 3.0.29 (released on 10 April 2019). NOTE: There is no longer a version of ILMerge that runs in the v1.1 runtime.

ILMerge runs in the v4.0 .NET Runtime, but it is also able to merge assemblies from other framework versions using the /targetplatformoption. Please see the documentation. (However, it can merge PDB files only for v2 (and later) assemblies.)

Currently, ILMerge works only on Windows-based platforms. It does not yet support Rotor or Mono.

If you use ASP.NET v2.0, then it provides a tool (based on ILMerge) to combine assemblies created during precompilation. You can get more details from the ASP.NET web site.

Installation

As noted on the ilmerge NuGet page, the package can be installed from the Visual Studio environment. Expand the project container in the Solution Explorer view. Right click on references and select Manage NuGet Packages

NuGet References Setting

Ensure the Package source is set to nuget.org

NuGet Package source

Next, click on Tools - NuGet Package Manager - Package Manager Console. Ensure the Package source is also set to nuget.org

NuGet Pakage Manager Console source.PNG

To install for the project, use the Install-Package command:

Install-Package ilmerge -Version 3.0.29

Usage

MSBuild

ILMerge can be used in MSBuild using the NuGet package:

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="ILMerge" Version="3.0.29" />
  </ItemGroup>

  <Target Name="ILMerge">
    <!-- the ILMergePath property points to the location of ILMerge.exe console application -->
    <Exec Command="$(ILMergeConsolePath) /out:Merged.dll File1.dll File2.dll" />
  </Target>

</Project>

Edit the project .csproj or .vbproj files (inside the respective <Project> .. </Project> tags, typically at the end of the file. If compiling for a specific target, use explicit directories such as Bin\x64\Release:

<ItemGroup>
    <PackageReference Include="ILMerge" Version="3.0.29" />
  </ItemGroup>

  <Target Name="ILMerge">
    <!-- the ILMergePath property points to the location of ILMerge.exe console application -->
    <Exec Command="$(ILMergeConsolePath) Bin\x64\Release\myapp.exe  /out:myapp.exe Bin\x64\Release\File1.dll Bin\x64\Release\File2.dll Bin\x64\Release\File3.dll " />
  </Target>

Although whitespace is usually ignored in XML files, in this case the exact text is processed as a DOS command, so to improve readability, use the carat ^ (shift 6) line extenders:

<ItemGroup>
    <PackageReference Include="ILMerge" Version="3.0.29" />
  </ItemGroup>

  <Target Name="ILMerge">
    <!-- the ILMergePath property points to the location of ILMerge.exe console application -->
    <Exec Command="$(ILMergeConsolePath) Bin\x64\Release\myapp.exe ^
    /out:myapp.exe ^
    Bin\x64\Release\File1.dll ^
    Bin\x64\Release\File2.dll ^ 
    Bin\x64\Release\File3.dll " />
  </Target>

The DOS dir /b option can be helpful in listing all of the dependencies:

dir bin\x64\Debug\*.dll /b

From Visual Studio Developer Command Prompt:

# Download/install the package reference
msbuild /t:Restore

# Run the ILMerge target
msbuild /t:ILMerge

To run `ILMerge` in a batch file:

The Visual Studio Developer Command Prompt is not needed here, as msbuild is not used.

@echo off

:: this script needs https://www.nuget.org/packages/ilmerge

:: set your target executable name (typically [projectname].exe)
SET APP_NAME=myapp.exe

:: Set build, used for directory. Typically Release or Debug
SET ILMERGE_BUILD=Debug

:: Set platform, typically x64
SET ILMERGE_PLATFORM=x64

:: set your NuGet ILMerge Version, this is the number from the package manager install, for example:
:: PM> Install-Package ilmerge -Version 3.0.29
:: to confirm it is installed for a given project, see the packages.config file
SET ILMERGE_VERSION=3.0.29

:: the full ILMerge should be found here:
SET ILMERGE_PATH=%USERPROFILE%\.nuget\packages\ilmerge\%ILMERGE_VERSION%\tools\net452
:: dir "%ILMERGE_PATH%"\ILMerge.exe

echo Merging %APP_NAME% ...

:: add project DLL's starting with replacing the FirstLib with this project's DLL
"%ILMERGE_PATH%"\ILMerge.exe Bin\%ILMERGE_PLATFORM%\%ILMERGE_BUILD%\%APP_NAME%  ^
  /lib:Bin\%ILMERGE_PLATFORM%\%ILMERGE_BUILD%\ ^
  /out:%APP_NAME% ^
  FirstLib.dll ^
  mylib1.dll ^
  Microsoft.lib2.dll ^
  SomeOtherLib.dll ^
  \otherlibdir\otherlib.dll 


:Done
dir %APP_NAME%

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Getting Started

Competitor Comparisons

Pros of DotNetCorePlugins

Cons of DotNetCorePlugins

Code Comparison

Pros of Fody

Cons of Fody

Code Comparison

Summary

Pros of Costura

Cons of Costura

Code Comparison

Summary

Pros of Harmony

Cons of Harmony

Code Comparison

Summary

Convert designs to code with AI

README

ILMerge

Installation

Usage

MSBuild

To run ILMerge in a batch file:

Top Related Projects

Convert designs to code with AI

To run `ILMerge` in a batch file: