Design-Time Usage Protection

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.

How It Works

Eazfuscator.NET injects special checks into obfuscated assembly and shrinks public API surface 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.

Component Designer Suppression

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:

Visual Studio designer before obfuscation with enabled design-time usage protection

Let's switch the solution to Release configuration and build it with enabled obfuscation and design-time usage protection:

Visual Studio designer after obfuscation with enabled design-time usage protection

Please note that designer now shows "Design-time usage is not allowed" message. This is expected error message because the control library was obfuscated and protected from usage in designer.

Component designer suppression is automatically applied to Component Model and Windows Forms components defined in class library when design-time protection is on.

Public API Surface Shrink

Public API surface is a set of public classes and their members exposed by a class library. By default, Eazfuscator.NET preserves public API surface of class library so that it can be consumed by other modules. However not all data are needed in runtime. For example, method arguments can be renamed to obfuscated titles without loosing runtime functionality.

What Eazfuscator.NET does is essentially this: it automatically renames method arguments to obfuscated equivalents when design-time protection is on. This process is called public API surface shrink. It allows to achieve better obfuscation coverage.

Instructions

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.cs or ObfuscationSettings.vb

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

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
no_cds	Disables the component designer suppression
arguments=keep	Disables the method arguments renaming
arguments=auto	Eazfuscator.NET automatically decides which arguments to rename during public API surface shrink. This is the default setting
arguments=rename	All method arguments are renamed during public API surface shrink. Note that this seeting may cause troubles with optional parameters if they are referenced by names in source code

Let's take a look on example.

Example 5.5. Enable design-time usage protection without component designer suppression. Rename all method arguments during public API surface shrink

using System;
using System.Reflection;

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