[File]Merge assemblies

ILMerge is a utility that can be used to merge multiple .NET assemblies into a single assembly.
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.

ILMerge runs in the v2.0 .NET Runtime, but it is also able to merge v1 or v1.1 assemblies. However it can merge PDB files only for v2 assemblies.

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

If you have any problems using ILMerge please contact mbarnett _at_ microsoft _dot_ com. More details are available at the ILMerge web site.

ILMerge should work just fine with newer versions of .NET. Just use the option: /targetplatform:v4,<path to your v4 framework directory>. For version 3.5, you probably don't need to set the target platform, but you may need to add the v3.5 framework directory as a /lib option so that assemblies from there can be found. (Unless they're in the GAC in which case they'll be found anyway.)

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.

The current version is 2.10.0219 (created on 19 February 2010). NOTE: There is no longer a version of ILMerge that runs in the v1.1 runtime.

The v2.0 version of ILMerge runs in the v2.0 .NET Runtime, but it is also able to merge v1 or v1.1 assemblies. However, it can merge PDB files only for v2 (and later) assemblies.

The v2 version of ILMerge was built with v2.0.50727 of the .NET Runtime. If you have an earlier version (e.g., Beta2 is v2.0.50215), then you need to use a config file: ILMerge.exe.config. (Copy the text from the browser and put into a file with that name. But check to see if you get any extraneous characters that the browser throws in. If so, please let me know and I'll see what I can do.)

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.

Introduction

As you know, traditional linking of object code is no longer necessary in .NET. A .NET program will usually consist of multiple parts. A typical .NET application consists of an executable assembly, a few assemblies in the program directory, and a few assemblies in the global assembly cache. When the program is run, the runtime combines all these parts to a program. Linking at compile time is no longer necessary.

But sometimes, it is nevertheless useful to combine all parts a program needs to execute into a single assembly. For example, you might want to simplify the deployment of your application by combining the program, all required libraries, and all resources, into a single .exe file.

A single project

If all parts of your program are written by yourself in the same language, you can obviously just add all source files to a single project. The result will be a single DLL or EXE containing all dependencies.

Collapse
csc /target:winexe /out:Program.exe
MainProgram.cs ClassLibrary1.cs ClassLibrary2.cs
However, if your program is written in multiple languages or if you are using binary third party libraries, you are out of luck.

.NET Modules

The .NET compilers already contain options for exactly this. If you compile a project, there is an option to create a module, which is similar to an assembly but without a manifest file. You can then use the al.exe tool to combine some of these modules to a single assembly. This feature makes it possible to create a single assembly that contains multiple languages.

First, you would compile the program and the class libraries to netmodules using the module target. Then you can use the assembly linker al.exe to combine these modules to a single assembly.


csc /target:module /out:ClassLibrary1.netmodule ClassLibrary1.cs
vbc /target:module /out:ClassLibrary2.netmodule ClassLibrary2.vb
vbc /target:module /out:Program.netmodule Program.vb
al /target:winexe /out:Program.exe ClassLibrary1.netmodule
ClassLibrary2.netmodule Program.netmodule
But unfortunately, this method only works if you have all the required parts of your program either as source code or as .NET modules. If you are useing a third party class library in assembly form, you are again out of luck.

ILMerge

Since a .NET module is basically just an assembly without an assembly manifest, it should be possible to convert an assembly to a .NET module, at least that is what I thought. When researching this on Google, I found a tremendously useful tool on Microsoft research called ILMerge. This little gem makes it possible to link multiple assemblies to a single one.

First, you would compile your libraries to DLLs and your program to an EXE referencing the DLLs. This is exactly what Visual Studio would do if you had multiple libraries and a program referencing these libraries, so there is no need to do this on the command line.

Collapse
csc /target:library /out:ClassLibrary1.dll ClassLibrary1.cs
vbc /target:library /out:ClassLibrary2.dll ClassLibrary2.vb
vbc /target:winexe /out:Program.exe
/reference:ClassLibrary1.dll,ClassLibrary2.dll Program.vb
This will produce a normal .exe that requires the two DLLs in the program directory or in the global assembly cache to run.

Now you can link these parts to a single self-contained EXE, using ILMerge:

Collapse
ilmerge /target:winexe /out:SelfContainedProgram.exe
Program.exe ClassLibrary1.dll ClassLibrary2.dll
The nice thing about this is that you can also merge third party assemblies like commercial class libraries into your program. And you do not have to modify your build process. All you have to do is to merge the assemblies to a single EXE before deploying.