|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
Declarative Obfuscation Using Custom Attributes
The .NET Framework version 2.0 provides two new custom attributes designed to make it easy to automatically obfuscate assemblies without having to set up configuration files. This section outlines how you can use these attributes with Dotfuscator. It is assumed that you are familiar with custom attributes and how to apply them in your development language.
This attribute is used at the assembly level to tell Dotfuscator how to obfuscate the assembly as a whole. Setting the AssemblyIsPrivate property to false tells Dotfuscator to run the assembly in library mode. If you set it to true, Dotfuscator will not run the assembly in library mode and will rename as much as possible, including public types and members.
This attribute is used on types and their members and tells Dotfuscator how to obfuscate the item.
This string property has a default value of "all". This property is provided so that you can configure multiple obfuscation transforms independently by tagging an item with multiple ObfuscationAttributes, each with a different feature string.
Dotfuscator maps the "default" and "all" feature strings to "renaming".
Here is a list of other feature strings that Dotfuscator understands.
|renaming||attribute configures renaming|
|controlflow||attribute configures control flow obfuscation.|
|stringencryption||attribute configures string encryption|
|trigger||attribute configures pruning by marking the annotated item as an entry point|
|conditionalinclude||attribute configures pruning by conditionally including the annotated item|
If necessary, you can map other feature strings to "renaming" using the "Feature Map Strings" property sheet on the Setup Tab.
Dotfuscator ignores attributes with feature strings that it does not understand.
This Boolean property has a default value of True. When True, it indicates that the tagged item should be excluded from the transforms implied by the Feature property. When False, it indicates that the tagged item should be included.
The current version of Dotfuscator supports one value of the Exclude property for any given transform. Dotfuscator will ignore rules that have unsupported Exclude values. The following list summarizes.
|Feature String||Supported Exclude Value|
This Boolean property has a default value of True. When the attribute is applied to an assembly or a type, a True value indicates that the operation should be applied to all the members (including nested types) of selected types as well. If false, the operation is applied to types only and not their members (or nested types).
Enabling or Disabling Declarative Obfuscation
Dotfuscator allows you to switch Declarative Obfuscation on or off for all input assemblies. If not enabled, Dotfuscator will ignore obfuscation related custom attributes. You can also switch it off for specific assemblies.
Stripping Declarative Obfuscation Attributes
Dotfuscator can strip out the obfuscation attributes when processing is complete, so your output assemblies will not contain clues about how it was obfuscated. Both of the declarative obfuscation attributes include a Boolean "StripAfterObfuscation" property whose default value is true
Dotfuscator also has configuration settings that interact with the value of the StripAfterObfuscation property at obfuscation time.
The settings that effect declarative obfuscation attribute stripping and how they interact are summarized in the below table.
|Dotfuscator is Honoring Attributes||Dotfuscator is Stripping Attributes||Attribute's StripAfterObfuscation Property||Result|
|Yes||Yes||True or False||Strip Attribute|
|No||Yes||True or False||Strip Attribute|
|No||No||True or False||Keep Attribute|
Using Feature Map Strings
Dotfuscator allows you to map values contained in an Obfuscation Attribute's Feature property to feature strings that Dotfuscator understands.
For example, you can annotate your application with obfuscation attributes that reference a feature called "testmode". Dotfuscator by default will not understand this feature string; therefore it will ignore the attributes. If later on you want Dotfuscator to use these attributes to configure renaming and controlflow obfuscation, you can map the feature string "testmode" to Dotfuscator's built in "renaming" and "controlflow" strings.