Merge multiple .NET assemblies into a single Assembly using ILMerge Utility

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.

If you aren’t aware about Assemblies, do read this introduction article here

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. 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. 

Download the ILMerge tool here [.msi format]

Currently, ILMerge works only on Windows-based platforms. It does not yet support Rotor or Mono. You can find more information about this tool here the ILMerge web site.

To read more on the Side-by-Side Assemblies and WinSxS folder, I would recommend you check this article which was written sometime ago!

Also read,

How does the CLR Locates Assemblies in Applications?

To successfully deploy your .NET Framework application, you must understand how the common language runtime locates and binds to the assemblies that make up your application. By default, the runtime attempts to bind with the exact version of an assembly that the application was built with. This default behavior can be overridden by configuration file settings. The common language runtime performs a number of steps when attempting to locate an assembly and resolve an assembly reference. Each step is explained in the following sections. The term probing is often used when describing how the runtime locates assemblies; it refers to the set of heuristics used to locate the assembly based on its name and culture.

Note You can view binding information in the log file using the Assembly Binding Log Viewer (Fuslogvw.exe), which is included in the .NET Framework SDK.

For Further Reading, Please refer – http://msdn.microsoft.com/en-us/library/yx7xezcf(VS.71).aspx

How to add WinSxS assemblies into a MSI package?

If you need to install Win32 side by side assemblies globally, you should use the MsiAssembly and MsiAssemblyName tables to do so. Your InstallExecuteSequence table should also include the MsiPublishAssemblies and MsiUnpublishAssemblies standard actions. There is more information on these tables in MSDN and the sample sequence.msi package provided with the Windows Installer SDK (of the Windows SDK) provides a recommended sequence number for those standard actions.

You can refer this article to get the basics of Assemblies

A win32 assembly is an unmanaged assembly (native code). An assembly that is installed to the GAC is actually a managed assembly or otherwise known as a .NET assembly. While the concept of the assembly unit is the same, there are quite a few differences between the two. Typically .NET assemblies are contained within a single module that includes an embedded manifest. For Win32 assemblies, the manifest and catalog file are separate from the binary itself.

You can review the assembly structure yourself by taking a look at the following folders on a Windows Vista machine:

.NET assemblies
%windir%\assembly

Win32 assemblies
%windir%\winsxs

A good starting point on MSDN is http://msdn2.microsoft.com/en-us/library/aa367757.aspx.

What is the WinSxS folder which is present in C:\Windows?

In the early days Microsoft recommend installing DLLs to c:\windows\system32 if you wanted to share them with other applications. This lead to “DLL Hell” since one applications installer would install one version of a DLL and another installer would install another version overwriting the existing DLL. If the new version of the DLL wasn’t compatible the older application would suddenly break and stop working. With SxS technology, applications can install DLLs to version specific directories tell Windows what version of the DLL should be used when they load a DLL by that name.

You can refer this article to get the basics of Assemblies

Windows OSes which have SxS will look for an application’s manifest information to determine which version to load from SxS. A manifest is a fairly simple XML description of all the SxS DLLs that might be loaded by the application and which version to use. The manifest can either be embedded in the application EXE/DLL file as a resource or stored separately on the filesystem as a .manifest file. In the second case, the manifest file for app.exe would be called app.exe.manifest.

The manifest resolution algorithm is fairly complex and I won’t get into all the details here, but it can include among other things searching based on the user’s locale (i.e. Look for French/German version first). As well, to eliminate security disasters like what happened with gdiplus.dll, SxS DLLs have a “force upgrade” mechanism implemented as separate security policy files (also XML files). This mechanism allows Microsoft to override version number request by applications in the case where some gaping security hole is discovered in a shared library that effects thousands of applications. For example, an application manifest may say “I want version 1.0.0.0 of xyz.dll”, but Microsoft can push a policy file update that says “redirect all request of version 1.0.0.0 to 1.0.0.5”.

Best Practices and Guidelines: Packaging .NET Assemblies

This is a MSDN extract; I have still posted it because many of us do not follow these rules while packaging .NET applications. The Installer can install, remove and update Win32 and .NET assemblies, including side-by-side and private assemblies in Windows XP. To avoid common problems, follow these rules when using assemblies:

General:

  • A component should contain no more than one assembly.
  • All of the files in an assembly should be in a single component.
  • Each component that contains an assembly should have an entry in the MsiAssembly table.
  • The strong assembly cache name of each assembly should be authored into the MsiAssemblyName table.
  • Use the Registry table instead of the Class table when you register COM Interop for an assembly.
  • Assemblies that have the same strong name are the same assembly. When the same assembly is installed by different applications, the components that contain the assembly should use the same value for the ComponentId in their Component tables.

Win32 Assemblies:

  • Do not use the manifest file or the catalogue file as the KeyPath in the Component table for the component containing the Win32 assembly.
  • The KeyPath value in the Component table for a component that contains a Win32 policy assembly should be Null.
  • Add a row to the MsiAssemblyName table for each name and value pair that are listed in the <assemblyIdentity> section of the Win32 assembly’s manifest.

.NET Assemblies:

  • The KeyPath value in the Component table for a component that contains the assembly should not be Null.
    When you install an assembly used by the common language runtime to the global assembly cache, the value in the File_Application column of the MsiAssembly table must be Null.
  • Add a row to the MsiAssemblyName table for each attribute of the assembly’s strong name. All assemblies must have the Name, Version, and Culture attributes that are specified in the MsiAssemblyName table. A publicKeyToken attribute is required for a global assembly.

How to add Assemblies to Global Assembly Cache (GAC)

Installation of assemblies should not be dealt using gacutil.exe (Custom action) in an application installation suite. Gacutil is not designed to be used during installation. Gacutil.exe works, but it is a developer tool, and developer tools go into SDKs and not runtime packages typically. It isn’t really appropriate to put more tools into the runtime because that causes it to get larger, which makes it more difficult for applications to redistribute because of increased download, size, etc.

In general, installing an assembly to the GAC is an application deployment activity, and is most often done during application setup. One should use Windows Installer to install your application. Starting with version 2.0, Windows Installer has built-in functionality to install assemblies to the GAC – the MsiAssembly and MsiAssemblyName tables in particular. Its always better to use a MSI as an installer and directly authoring files, registry and GAC installation steps using built-in Windows Installer functionality instead of using a batch script, regsvr32 and Gacutil. We can gain a lot of benefits from using an MSI (clean rollback; uninstall, serviceability, deployment options, etc). Therefore we should use this built-in functionality to handle GAC installation and un-installation.

This means that if we want to obtain Windows Vista Logo certification for our application, we should use Windows Installer and the built-in GAC installation functionality for our setup.

Reference: Aaron Stebner’s WebLog

Basics and Introduction to .NET Framework Assemblies

An Assembly is a logical unit of code. Assembly physically exist as DLLs or EXEs. One assembly can contain one or more files. The constituent files can include any file types like image files, text files etc. along with DLLs or EXEs. When you compile your source code by default the exe/dll generated is actually an assembly, Unless your code is bundled as assembly it can not be used in any other application. Every assembly file contains information about itself. This information is called as Assembly Manifest.

What is assembly manifest?

Assembly manifest is a data structure which stores information about an assembly. This information is stored within the assembly file(DLL/EXE) itself. The information includes version information, list of constituent files etc.

What is private and shared assembly?

The assembly which is used only by a single application is called as private assembly. Suppose you created a DLL which encapsulates your business logic. This DLL will be used by your client application only and not by any other application. In order to run the application properly your DLL must reside in the same folder in which the client application is installed. Thus the assembly is private to your application.

Suppose that you are creating a general purpose DLL which provides functionality which will be used by variety of applications. Now, instead of each client application having its own copy of DLL you can place the DLL in ‘global assembly cache’. Such assemblies are called as shared assemblies.

What is Global Assembly Cache?

Global assembly cache is nothing but a special disk folder where all the shared assemblies will be kept. It is located under <drive>:\WinNT\Assembly folder.

How assemblies avoid DLL Hell?

As stated earlier most of the assemblies are private. Hence each client application refers assemblies from its own installation folder. So, even though there are multiple versions of same assembly they will not conflict with each other. Consider following example:

  • You created assembly Assembly1
  • You also created a client application which uses Assembly1 say Client1
  • You installed the client in C:\MyApp1 and also placed Assembly1 in this folder
  • After some days you changed Assembly1
  • You now created another application Client2 which uses this changed Assembly1
  • You installed Client2 in C:\MyApp2 and also placed changed Assembly1 in this folder
  • Since both the clients are referring to their own versions of Assembly1 everything goes on smoothly

Now consider the case when you develop assembly that is shared one. In this case it is important to know how assemblies are versioned. All assemblies has a version number in the form: major.minor.build.revision. If you change the original assembly the changed version will be considered compatible with existing one if the major and minor versions of both the assemblies match. When the client application requests assembly the requested version number is matched against available versions and the version matching major and minor version numbers and having most latest build and revision number are supplied.

How to Handle .NET Framework Native Images in Software MSI Installation Packages?

When you find in a file which is suffixed by “.ni” in an application capture (For eg: Aclayers.ni.dll), this is an indication that it is a native image for an assembly. (The base assembly can be found in the application installation directory). These files cannot be added directly to the MSI package. Instead, it needs to be done through a .NET executable(ngen.exe).
In this below article, we look at the basics and implementation of this process.

Overview of Native Image Generator:

The Native Image Generator (ngen.exe) creates a native image from a managed assembly and installs it into the native image cache on the local computer. The native image cache is a reserved area of the global assembly cache. Once you create a native image for an assembly, the runtime automatically uses that native image each time it runs the assembly. You do not have to perform any additional procedures to cause the runtime to use a native image. Running Ngen.exe on an assembly allows the assembly to load and execute faster, because it restores code and data structures from the native image cache rather than generating them dynamically.

How Native Generator Works

Ngen.exe does not use standard assembly probing rules to locate the assemblies you specify on the command line. Ngen.exe looks only in the current directory for assemblies that you specify. Therefore, to allow Ngen.exe to locate your assemblies, you should either set your working directory to the directory that contains the assemblies you want to create native images for or specify exact paths to the assemblies.

This tool can be located at <drive>:\WINNT\Microsoft.NET\Framework\<version>\ngen.exe

This tool is used to create a native Image from a .NET assembly and installs it into the native image cache on that computer. Since assembly image is present on the local machine cache loading of the assembly becomes faster because .NET reads data from the native image than generating them dynamically (JIT). Pre-compiling assemblies with Ngen.exe can improve the startup time for applications, because much of the work required to execute code has been done in advance.

The default usage for NGen is extremely simple: ngen install aclayer.dll

This will generate native images for aclayer.dll and all of its dependencies and create a native image for this dll in C:\Winnt\Assembly\Native Images as aclayer.ni.dll.

This process can be quite slow. For larger applications you may wish to use the /queue option which will queue up aclayer.dll, and all of its dependencies, so that they will be converted by the Native Image Service. This will happen in the background, at the service’s earliest convenience. Once the native image is generated it will be stored in the native image cache and used automatically.

Usage:

While Installing:
Identify the Assembly which creates these native images, mention the same path in these scripts. Example: C:\Program FIles\DWG TrueView 2008\AcLayer.dll. For multiple assemblies use the function mentioned.

Use this script in your MSI Package.

Option Explicit
Dim wshShell, ngen, FSO, windir, assembly,PrgFiles
Set wshShell = CreateObject(“WScript.Shell”)
Set FSO = CreateObject(“Scripting.FileSystemObject”)
windir = wshShell.ExpandEnvironmentStrings(“%Windir%”)
PrgFiles = wshShell.ExpandEnvironmentStrings(“%ProgramFiles%”)
ngen = windir & “\Microsoft.NET\Framework\v2.0.50727\ngen.exe”

if FSO.FileExists(ngen) then
assembly=chr(34) & PrgFiles & “\DWG TrueView 2008\AcLayer.dll” & chr(34)
Generate(assembly)
end if

set FSO = nothing
set wshShell = nothing

Function Generate (Byval file)
Dim strCmd,wshShell1
Set wshShell1 = CreateObject(“WScript.Shell”)
strCmd= chr(34) & ngen & chr(34) & ” install ” & file
wshShell1.run strCmd,0
Set WshShell1 = nothing
End function

While Un-Installing:

Option Explicit
Dim wshShell, ngen, FSO, windir, assembly,PrgFiles
Set wshShell = CreateObject(“WScript.Shell”)
Set FSO = CreateObject(“Scripting.FileSystemObject”)
windir = wshShell.ExpandEnvironmentStrings(“%Windir%”)
PrgFiles = wshShell.ExpandEnvironmentStrings(“%ProgramFiles%”)
ngen = windir & “\Microsoft.NET\Framework\v2.0.50727\ngen.exe”

if FSO.FileExists(ngen) then
assembly=chr(34) & PrgFiles & “\DWG TrueView 2008\AcLayer.dll” & chr(34)
DeleteImages(assembly)
end if

Function DeleteImages (Byval file)
Dim strCmd,wshShell1
Set wshShell1 = CreateObject(“WScript.Shell”)
strCmd= chr(34) & ngen & chr(34) & ” uninstall ” & file
wshShell1.run strCmd,1
Set WshShell1 = nothing
End function

Note: To run Ngen.exe, you must have administrative privileges. Hence, run this CA in deferred/System Context mode.