5.6. Design-Time Usage Protection
It is a common scenario when software developers use class libraries authored in-house. Such libraries are not made available to third-parties but they are extensively used throughout the application.
Eazfuscator.NET provides a way to protect such libraries from unsolicited usage by third-parties in design time.
5.6.2. How It Works
Design-time usage protection feature of Eazfuscator.NET is represented by two techniques:
Component Designer Suppression
Component designer suppression is achieved by injecting special checks into obfuscated assembly when design-time usage protection is enabled. The injected checks ensure that components can only be instantiated at runtime context, thus effectively preventing their unsolicited usage in designer.
Let's take a look on example. Suppose the application has
ContosoWindowsFormsControlLibrary assembly that defines
ContosoUserControl UI component. When the solution is in
Debug configuration and is not obfuscated, the developer is able to use Toolbox panel and play with
ContosoUserControl in Visual Studio designer:
Let's switch the solution to
Release configuration and build it with enabled obfuscation and design-time usage protection:
Please note that designer now shows "Design-time usage is not allowed" message. This is the expected error message because the control library was obfuscated and protected from the usage in designer.
Component designer suppression is automatically applied to Component Model and Windows Forms components defined in a class library when design-time protection is on.
Public API Surface Shrink
Public API surface is a set of public types and their members exposed by a class library. By default, Eazfuscator.NET preserves public API surface so that it can be consumed by other modules. However not all data are needed in runtime. For example, method parameters can be renamed to obfuscated titles without loosing runtime functionality.
When design-time usage protection is enabled, Eazfuscator.NET automatically renames public API method parameters to obfuscated equivalents. This process is called public API surface shrink. It allows to achieve a better obfuscation coverage.
5.6.3. Default Behavior
Design-time usage protection is disabled by default unless an obfuscation directive presented below is specified.
Please follow the instructions below to enable design-time usage protection for your assembly:
Instructions on enabling design-time usage protection
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.cswith the following content (C#):
[assembly: Obfuscation(Feature = "design-time usage protection", Exclude = false)]
For Visual Basic .NET, fill
ObfuscationSettings.vbwith the following content:
<Assembly: Obfuscation(Feature:="design-time usage protection", Exclude:=False)>
By default, component designer suppression and public API surface shrink are active when design-time usage protection is enabled for your assembly. You may prefer to turn off the component designer suppression or configure public API shrink options. In order to do that, please read the notes below.
The full notation of a custom attribute for design-time usage protection has the following form:
[assembly: Obfuscation(Feature = "design-time usage protection [flags]", Exclude = false)]
[flags] is an optional enumeration of flags separated by spaces.
The list of available flags is presented in the table below.
Table 5.1. The list of flags for design-time usage protection attribute
Default behavior (flag not specified)
Disables the component designer suppression
Component designer suppression is enabled
Disables the renaming of method parameters. Applies to public API methods only
Eazfuscator.NET automatically decides which method parameters to rename during public API surface shrink
This is the default setting. Optional parameters' names are kept intact. Non-optional parameters are renamed
All method parameters are renamed during public API surface shrink. Note that this setting may cause troubles with optional parameters if they are referenced by names in source code
Let's take a look on example.
Example 5.7. Enable design-time usage protection without component designer suppression. Rename all method parameters during public API surface shrink
[assembly: Obfuscation(Feature = "design-time usage protection [no-cds arguments=rename]", Exclude = false)]