Assemblies Merging

Introduction

Assemblies merging allows to merge several assemblies into one. This may be beneficial from the deployment and security points of view.

By default, assemblies merging is not used during obfuscation of the assembly.

Instructions

To enable assemblies merging you should apply specially formed attribute(s) to your assembly. In order to do that you can use the instructions below.

Instructions on enabling assemblies merging

Open obfuscatable project inside the IDE
Add new source file to the project and call it ObfuscationSettings.cs (for C#) or ObfuscationSettings.vb (for Visual Basic .NET). You may prefer to use another name instead of ObfuscationSettings.cs or ObfuscationSettings.vb

Fill ObfuscationSettings.cs with the following content (C#):

using System;
using System.Reflection;

[assembly: Obfuscation(Feature = "merge with XXXXXX.dll", Exclude = false)]

For Visual Basic .NET, fill ObfuscationSettings.vb with the following content:

Imports System
Imports System.Reflection

<Assembly: Obfuscation(Feature:="merge with XXXXXX.dll", Exclude:=False)>

	Note
	Change XXXXXX.dll with the file name of the assembly you want to merge with.

	Tip
Eazfuscator.NET automatically finds the assembly path when only the file name is supplied. If you prefer to specify the exact file path to assembly then you can use script variables: [assembly: Obfuscation(Feature = @"merge with $(InputDir)\Lib\AssemblyToMerge.dll", Exclude = false)]

Tip

Eazfuscator.NET automatically finds the assembly path when only the file name is supplied.
If you prefer to specify the exact file path to assembly then you can use script variables:

[assembly: Obfuscation(Feature = @"merge with $(InputDir)\Lib\AssemblyToMerge.dll", Exclude = false)]

	Tip
If you want to merge with several assemblies then just add several attributes: using System; using System.Reflection; [assembly: Obfuscation(Feature = "merge with Assembly1.dll", Exclude = false)] [assembly: Obfuscation(Feature = "merge with AnotherAssembly2.dll", Exclude = false)] …

Tip

If you want to merge with several assemblies then just add several attributes:

using System;
using System.Reflection;

[assembly: Obfuscation(Feature = "merge with Assembly1.dll", Exclude = false)]
[assembly: Obfuscation(Feature = "merge with AnotherAssembly2.dll", Exclude = false)]
…

	Note
	Usage of assemblies merging may lead to some side effects which may make obfuscation to fail. If such is the case then use the principle of the least common denominator – merge just those assemblies which do not cause obfuscation failure. Assemblies embedding can be used in conjunction or as an alternative to assemblies merging.

Tuning

The satellite assemblies are not merged by default. You may prefer to change that by instructing Eazfuscator.NET to automatically merge them for you. In order to do that, please read the notes below.

The full notation of a custom attribute for assembly merging has the following form:

[assembly: Obfuscation(Feature = "merge with [flags] XXXXXX.dll", Exclude = false)]

where [flags] is an optional enumeration of flags separated by spaces.

The list of available flags is presented in the table below.

Table 4.6. The list of flags for assembly merging attribute

Flag	Description
satellites	Enables automatic merging of satellite assemblies
internalization=auto	Instructs Eazfuscator.NET to automatically decide which public merged types should be internalized. This is the default setting. The typical decision is to internalize a given type. At the same time the type internalization can be inhibited, for example, by the fact that some kinds of WPF controls cannot have `internal` visibility
internalization=none	Disables the internalization of public merged types
internalization=full	Instructs Eazfuscator.NET to internalize all public merged types

Let's take a look on examples.

Example 4.26. Merge with assembly and its satellite assemblies

using System;
using System.Reflection;

[assembly: Obfuscation(Feature = "merge with [satellites] XXXXXX.dll", Exclude = false)]

Example 4.27. Merge with assembly and its satellite assemblies; do not internalize public merged types

using System;
using System.Reflection;

[assembly: Obfuscation(Feature = "merge with [satellites internalization=none] XXXXXX.dll", Exclude = false)]

Internalization

Internalization changes the visibility of merged classes from public to internal. By default, classes from merged assemblies are automatically internalized in order to improve obfuscation coverage.

That's fine for the most scenarios but sometimes you may want to change that for some specific classes. Please follow the instructions below to achieve it.

Instructions on disabling internalization for specific class

Open the source code of a class

Add a custom attribute as shown below (C#):

using System;
using System.Reflection;

[Obfuscation(Feature = "internalization", Exclude = true)]
public class YourClass
{
    ...
}

For Visual Basic .NET:

Imports System
Imports System.Reflection

<Obfuscation(Feature:="internalization", Exclude:=True)> 
Class YourClass
    ...    
End Class

	Important
	Conditional obfuscation is not available for this feature.

Custom Parameters for Merging

Sometimes you may need to pass custom parameters for assembly merging. For example, you may prefer to control class internalization yourself or use some tricky merging feature.

Historically Eazfuscator.NET relied on ILMerge utility in the past. Now it is equipped with its own compatible merger since version 4.1. The new merger understands most of ILMerge configuration parameters and can be configured in the very same way. Please refer to ILMerge documentation for the list of available parameters.

Instructions on passing custom parameters to merger

Open obfuscatable project inside the IDE
Add new source file to the project and call it ObfuscationSettings.cs (for C#) or ObfuscationSettings.vb (for Visual Basic .NET). You may prefer to use another name instead of ObfuscationSettings.cs or ObfuscationSettings.vb

Fill ObfuscationSettings.cs with the following content (C#):

using System;
using System.Reflection;

[assembly: Obfuscation(Feature = "ilmerge custom parameters: <parameters>", Exclude = false)]

For Visual Basic .NET, fill ObfuscationSettings.vb with the following content:

Imports System
Imports System.Reflection

<Assembly: Obfuscation(Feature:="ilmerge custom parameters: <parameters>", Exclude:=False)>

	Note
	Change <parameters> with the parameters you want to pass to merger. Eazfuscator.NET passes /internalize /ndebug parameters by default when no attribute defined. If you do not want to pass any parameters to merger then change <parameters> with none string.