4.9. Assemblies Embedding
Assemblies embedding allows to embed assembly's dependencies into assembly itself. This may be beneficial from the deployment and security points of view.
Assemblies embedding is similar to merging. The main difference is that the assemblies are not merged into a single assembly when they are embedded. They just get encrypted and packed as the assembly resources. As a result, there is a single assembly at the output, and it contains the packed dependencies at the same file.
4.9.2. Embedding vs. Merging
Assemblies merging delivers the best performance for the resulting assemblies. They can be NGEN'ed; they work in all constrained environments (Windows Phone, Compact Framework, etc.). File mappings and JIT'ted code can be cached by the operating system for such assemblies, bringing the blinding fast application startups. Assembly merging definitely rocks.
However, there are two possible downsides of assembly merging:
- It's not always possible to apply it without breaking the application
- The resulting assembly may become extremely large to the point where it negatively affects the performance
So this is where assemblies embedding comes to the rescue.
Embedded assemblies are easy goals to achieve, and they work out of the box. Downsides? Well, they are present. Embedded assemblies cannot be NGEN'ed; they do not work in some constrained environments (Xbox, Windows Phone and Compact Framework). The extraction of embedded assemblies during the application load is a performance penalty (the penalty is pretty small, so it's unlikely you can notice it).
Assemblies embedding brings some benefits as well. The embedded assemblies are encrypted, so this is a security hardening against the hackers. Embedded assemblies are compressed, bringing the size reduction of the resulting assembly. And of course, assemblies embedding is the easiest way to achieve single-file deployment, making your application to consist of a single .exe (or .dll) file.
To enable assemblies embedding, you should apply specially formed attribute(s) to your assembly. To do that, you can use the instructions below.
Instructions on enabling assemblies embedding
-
Open obfuscatable project inside the IDE
-
Add new source file to the project and call it
ObfuscationSettings.cs
(for C#) orObfuscationSettings.vb
(for Visual Basic .NET). You may prefer to use another name instead ofObfuscationSettings.cs
orObfuscationSettings.vb
-
Fill
ObfuscationSettings.cs
with the following content (C#):using System;
using System.Reflection;
[assembly: Obfuscation(Feature = "embed XXXXXX.dll", Exclude = false)]For Visual Basic .NET, fill
ObfuscationSettings.vb
with the following content:Imports System
Imports System.Reflection
<Assembly: Obfuscation(Feature:="embed XXXXXX.dll", Exclude:=False)>NoteChange XXXXXX.dll with the file name of the assembly you want to embed.
ImportantIt is recommended to obfuscate the embedded assemblies.
TipEazfuscator.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 = @"embed $(InputDir)\Lib\AssemblyToEmbed.dll", Exclude = false)]
TipIf you want to embed several assemblies, then just add several attributes:
[assembly: Obfuscation(Feature = "embed Assembly1.dll", Exclude = false)]
[assembly: Obfuscation(Feature = "embed AnotherAssembly2.dll", Exclude = false)]
…TipYou can use assembly mask syntax to bulk select the assemblies you want to embed:
[assembly: Obfuscation(Feature = "embed Contoso.Dal.*.dll", Exclude = false)]
Embedded assemblies are compressed and encrypted by default. You may prefer to turn off the compression, encryption, or both. To do that, please read the notes below.
The full notation of a custom attribute for assembly embedding has the following form:
[assembly: Obfuscation(Feature = "embed [flags] XXXXXX.dll", Exclude = false)]