Dotfuscator config files contain information about how a given application is to be protected. The config file is an XML document conforming to dotfuscator_v2.6.dtd (or one of its predecessors) and usually has the .xml extension.
This page documents Dotfuscator's config file format, with detailed descriptions of each configuration option. You can use this page as guidance when editing a config file in a text editor. There are additional ways to work with config files, such as generating a config file with the MSBuild targets or the command palette.
Property List and Properties
The optional <propertylist> section allows for the definition and assignment of variables known as <properties> that may be used later in the config file. Property definitions defined in this section are referred to as config properties.
Config Properties:
<!-- define expandable properties -->
<!-- optional -->
<propertylist>
<property name="name" value="myapp"/>
<property name="outdir" value="c:\myapp\out"/>
</propertylist>
Variables, or property references, may be used in the config file without being defined in this section. For example, they may be defined on the command line or come from the environment. Properties work via string substitution, using the following algorithm to find a value associated with the property:
- Check the external property list for a value.
- If not found, check for an environment variable with the same name as the property,
- If not found, check for a config definition in the propertylist section of the config file,
- If still not found, use the empty string as the value.
Properties are useful for creating config files that act as templates for multiple applications, for different versions of the same application, or for simple portability across different build environments. A property is referenced with the following syntax:
Property Syntax:
${property_name}Property references are case sensitive, therefore ${OutDir} references a different property than does ${outdir}. Property values can reference other property values.
A property reference is interpreted literally in any other place in the config file.
Here is an example of a property reference in use:
<output>
<file dir="${testdir}/output"/>
</output>Global Option Section
The global option section is for defining configuration options that apply across the entire run. This section describes each option in detail.
Note: Options are not case sensitive.
Verbose, Quiet, and Investigate Options
These options are the same as the corresponding command line options and can be enabled either in the config file or from the command line. There is no way to unset an option from the command line.
Verbose, Quiet, and Investigate Options:
<global>
<!-- run in verbose mode -->
<option>verbose</option>
<!-- run in quiet mode -->
<option>quiet</option>
<!-- investigate only and generate a map -->
<option>investigate</option>
</global>SuppressIldasm Global Option
Setting this option tells Dotfuscator to prevent Microsoft's ILdasm utility from displaying the assembly IL. This is only valid for assemblies targeting .NET 2.0 and above.
SuppressIldasm Global Option:
<global>
<option>suppressildasm</option>
</global>Input Assembly List
The input assembly list contains the file names and directories of the assemblies and/or packages you want to obfuscate. It also contains configuration options that are set at the package or assembly level.
If you have a multi-module assembly, only list the module containing the manifest.
Input Assembly List:
<input>
<asmlist>
<inputassembly>
...
<file dir="c:\temp" name="myproj.dll"/>
</inputassembly>
...
</asmlist>
</input>Library Mode By Assembly
To specify Library Mode for an input assembly, a library option is automatically added to its <inputassembly> element.
<inputassembly>
<option>library</option>
...
</inputassembly>Note: To disable Library Mode for the assembly, simply comment out / delete the option tag.
Declarative Obfuscation By Assembly
Enabling or Disabling Declarative Obfuscation
To enable Declarative Obfuscation for an input assembly, add an honoroas option to its <inputassembly> element.
<inputassembly>
<option>honoroas</option>
...
</inputassembly>Stripping Obfuscation Attributes
To enable obfuscation attribute stripping for an input assembly, add a stripoa option to its <inputassembly> element.
<inputassembly>
<option>stripoa</option>
...
</inputassembly>Transform XAML By Assembly
This setting tells Dotfuscator that a particular input assembly may contain markup, either XAML as found in Universal Windows applications or compiled XAML resources (BAML) as found in Windows Presentation Foundation applications; and any markup should be analyzed and included for renaming. For Dotfuscation purposes, markup that is transformed has identifiers renamed in conjunction with any code-behind references of the elements. Properties that are referenced from markup resources have their property metadata retained but are renamed.
To specify Transform XAML mode for an input assembly, add an <option> element to its <inputassembly> element.
Transform XAML Mode by Assembly:
<inputassembly>
<option>transformxaml</option>
</inputassembly>For more information, see TransformXaml.
Output Directory
This is the directory where output assemblies are written. The application always overwrites files in this directory without prompting the user.
Output Directory:
<!-- destination directory is required -->
<output>
<file dir="c:\work"/>
</output>Renaming Section
The renaming section allows you to specify options that are specific to renaming, input and output mapping file locations, and fine-grained rules for excluding items from renaming.
The renaming section is optional. If not present, the following defaults apply:
- Default renaming (namespaces are removed).
- New names are chosen using the lowalpha renaming scheme.
- The mapping file is written to
{CurrentWorkingDir}/Dotfuscator/Map.xml. - No exclusions beyond those dictated by your application type.
Renaming Options
When you use the disable option, Dotfuscator skips the renaming step altogether, regardless of what's in the rest of the renaming section.
Disable Renaming Option:
<renaming>
<!--Skip renaming, ignoring rest of section-->
<option>disable</option>
...
</renaming>Dotfuscator allows several options that govern how namespaces are treated by the renaming algorithm. These are: "keepnamespace" and "keephierarchy" and are explained in detail in the section on identifier renaming.
You can change the renaming algorithm to rename types and members in a way that's compatible with the XML Serializer.
Change Renaming Algorithm to be Compatible with XML Serializer:
<renaming>
<!-- XML Serialization compatibility. -->
<option>xmlserialization</option>
...
</renaming>You can prevent managed resources from being renamed by using the keepManagedResourceNames option.
<renaming>
<!-- this prevents managed resources from being renamed -->
<option>keepManagedResourceNames</option>
...
</renaming>Note: Renaming options are not case sensitive.
Renaming Exclusion
There may be times when you need to make many specific exclusions for a particular coding convention. And even then, when a developer adds more code that follows that convention, they would have to remember to make yet another specific exclusion for their new code.
The solution to this is Custom Exclusion Rules. Let's say you figured out that all types with names ending in "Dungeon", and specific types of fields within those types, need to be excluded from renaming for some reason. Rather than creating a bunch of specific exclusions, you can make one custom rule as follows:
- Enter
.*Dungeonin the Name field. - Claim regex as true to indicate that the name should be treated as a regular expression. This way the node matches types whose names end in "Dungeon".
- Add a child node and name it .* to indicate that it should be treated as a regular expression.
- Restrict the rule to only cover fields which have the public access modifier (by setting speclist as +public), and whose signature is string[], as both are necessary in this scenario.
This example produces the following configuration:
<excludelist>
<type name=".*Dungeon" regex="true">
<field name=".*" speclist="+public" signature="string[]"
regex="true" />
</excludelist>Another example, Methods with System.Web.Services attributes translates to the following custom rule:
<excludelist>
<type name=".*" regex="true" excludetype="false">
<comment>Exclude all methods that are decorated with attributes
from the System.Web.services namespace.</comment>
<method name=".*" regex="true">
<customattribute name="System.Web.Services.*" regex="true" />
</method>
</type>
</excludelist>For more information, see Exclusion Rules.
Output Mapping File
This feature of Dotfuscator produces a log of all the renaming mappings used by Dotfuscator during a specific run. It also provides a statistics section.
Specifying this option instructs Dotfuscator's renamer to keep track of how things were renamed for both your immediate review and for possible use as input in a future Dotfuscator run.
<renaming>
...
<mapping>
<file dir="c:\work" name="testout.xml"/>
</mapoutput>
</mapping>
</renaming>SmartObfuscation
Smart Obfuscation allows Dotfuscator to auto detect elements that cannot be renamed or removed based on specific rules for the application type. Smart Obfuscation is turned on by default, and in most cases should be left on. It can be turned off by setting the disable option in this section in cases where the user believes that aggressive obfuscation does not hurt the application.
Smart Obfuscation includes a reporting facility and this section allows you to configure the verbosity of the report. Allowed values for the verbosity attribute are all, warningsonly, and none. The default value is all.
The Smart Obfuscation report can optionally be written to disk. Dotfuscator automatically renames an existing Smart Obfuscation report with the same name before overwriting it with a new version.
SmartObfuscation:
<smartobfuscation>
<!-- Skip smart obfuscation, ignoring rest of section -->
<option>disable</option>
<smartobfuscationreport verbosity="all" overwrite="true">
<!-- Specifying a destination report file is optional -->
<file dir="c:\myapp" name="smartobfuscation.xml"/>
</smartobfuscationreport>
</smartobfuscation>Configure Checks
Each Check targets one or more methods within the application code. These methods are known as a Check's location and are specified by <type name> tag.
The Location where the check will be injected follows the project structure by specifying:
Project name -> Class where injection will happen -> Method within the class where the injection will happen
Method signature needs to be provided as well. The signature is the return type and parameters of the method. For example:
A method that has a return type of void and no parameters has a signature of void(). If it has two string parameters, the signature is void(string,string) and if it has one integer parameter, the signature is void(int)
Check example:
<sos />
<extattributes>
</extattribute>
<extattribute name="PreEmptive.Attributes.TamperCheckAttribute">
// this attribute activates Tamper Check. You can also change it to:
PreEmptive.Attributes.DebuggingCheckAttribute -> for Debugging Check
PreEmptive.Attributes.RootCheckAttribute -> for Root Check
PreEmptive.Attributes.ShelfLifeCheckAttribute -> for Shelf Life Check
<type name="<projectname>.<class>"> // replace project name and class for example :
"DotfuscatorCommunitySample.Hello"
<method name="<methodname>" signature="void()" /> // replace <methodname> with
the name of the method where injection will happen for example: “LogIn”
</type>
<propertylist>
<property name="Action" value="Exit" /> // Read more on Action values
<property name="ActionProbability" value="1" /> // Read more on Action Probability
<property name="ApplicationNotificationSinkName" value="" />
<property name="ApplicationNotificationSinkOwner" value="" />
<property name="ApplicationNotificationSinkElement" value="None" />
</propertylist>
</extattribute>
</extattributes>To enable multiple checks on one project, you need to include them within the <extattributes> tag.
For example:
<sos />
<extattributes>
</extattribute>
…..
</extattribute>
</extattribute>
…..
</extattribute>
</extattributes>