Assemblies Merging

Eazfuscator.NET

previous page next page

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

  1. Open obfuscatable project inside the IDE
  2. 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

  3. 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] Note

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

    [Tip] 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] 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] 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

  1. Open the source code of a class

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

  1. Open obfuscatable project inside the IDE
  2. 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

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

previous page start next page