5.6. Design-Time Usage Protection

5.6.1. Overview

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
• Public API surface shrink

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.

5.6.4. Instructions

Please follow the instructions below to enable design-time usage protection for your assembly:

Instructions on enabling design-time usage protection

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 = "design-time usage protection", Exclude = false)]

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

   Imports System
   Imports System.Reflection
   
   <Assembly: Obfuscation(Feature:="design-time usage protection", Exclude:=False)>

5.6.5. Tuning

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)]

where [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

Flag	Description	Default behavior (flag not specified)
no-cds	Disables the component designer suppression	Component designer suppression is enabled
arguments=keep	Disables the renaming of method parameters. Applies to public API methods only
arguments=auto	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
arguments=rename	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

using System;
using System.Reflection;

[assembly: Obfuscation(Feature = "design-time usage protection [no-cds arguments=rename]", Exclude = false)]