Dotfuscator User's Guide
Configuring and Running Dotfuscator with Application Analytics

PreEmptive Analytics Options

PreEmptive Analytics configuration options are available on the Settings TabGlobal Options property page in Dotfuscator. From within Visual Studio, the Global Options property page is available from the Dotfuscator project's properties dialog.

 

From the standalone user interface, the Options property page is available on the Settings tab.

There are six options for Instrumentation (Tamper Detection, Shelf Life, Exception Reporting, and PreEmptive Analytics): Analytics Version, Enable, Merge Runtime, Send Analytics Messages, Send Shelf Life Messages, and Send Tamper Messages.

Analytics Version

The Analytics Version option allows you to specify the maximum version of the Instrumentation API to inject. Normally you should not have to adjust this setting from the default provided, unless directed by PreEmptive Solutions support.

Enabling Instrumentation (Tamper Detection, Shelf Life, and PreEmptive Analytics)

The Enable option turns Tamper Detection, Shelf Life, and PreEmptive Analytics on (default) and off. If this is turned off, Dotfuscator ignores all Tamper Detection, Shelf Life, and Application Analytics attributes contained within the input assemblies.

Merging or Referencing the Runtime

If set to "Yes" (default), the Merge Runtime option tells Dotfuscator to add the runtime code required for Tamper Detection, Shelf Life, and PreEmptive Analytics to one of the input assemblies. Distribution of the PreEmptive Analytics DLL is not required.

If set to "No", Dotfuscator outputs the runtime code in a separate assembly and adds the appropriate assembly references to the input assemblies. The new DLL must be distributed along with the application. Dotfuscator will still need to inject instrumentation helper methods into each assembly that is configured for Tamper Detection, Shelf Life, or PreEmptive Analytics.

Regardless of how the merge is set, Dotfuscator still needs to inject code into one of the input assemblies in order to use the PreEmptive Analytics library. Dotfuscator performs a dependency analysis of the input assemblies in order to choose the best one. It chooses in such a way as to minimize new dependencies among input assemblies; however, adding new dependencies is unavoidable in some cases. You can override the assembly that the PreEmptive Analytics runtime code will be injected into by specifying a Project Property with the name accesspoint and the value being the name of the assembly where the code will be inserted.

Strong Names

If any of the input assemblies are strong named, Dotfuscator will strong name the runtime DLL and sign it transparently. If none of the input assemblies are strong named, Dotfuscator will not strong name the runtime DLL.

Sending Tamper or Application Analytics Messages

By default, assemblies that contain a method decorated with an InsertTamperCheck attribute are instrumented with code to send tamper notification messages when tampering is detected. This functionality is configurable and is controlled by the Send Tamper Messages option.

If the Send Analytics Messages option is set to "Yes", Dotfuscator will add code, based on the specified attributes, to send application start and stop messages, session start and stop messages, and feature usage messages.

Assembly Level Configuration Options

Dotfuscator allows granular control of instrumentation attribute handling (e.g. tamper detection, shelf life, and application analytics). The developer can tell Dotfuscator to honor or ignore and whether to keep or remove these attributes. These settings can be applied at the assembly level.

From within Visual Studio, assembly level options are available on the properties tool window when an input assembly has the focus.

From the standalone user interface, the assembly level options are available on the Input tab.

Honor Instrumentation Attributes

Set Honor Instrumentation Attributes to "True" (the default) to tell Dotfuscator to process these attributes and perform the indicated instrumentation on the target assembly. Setting the property to "False" tells Dotfuscator to ignore any Instrumentation attributes.

A "False" setting is useful in testing scenarios and in advanced scenarios where a set of assemblies must be run through Dotfuscator multiple times.

Strip Instrumentation Attributes

Set Instrumentation attributes to "True" (the default) to tell Dotfuscator to remove these attributes from the target output assembly. Setting this property to "False" tells Dotfuscator to leave the attributes in the output assembly.

Like the Honor Instrumentation Attributes option, a "False" setting is useful in testing scenarios and in advanced scenarios where a set of assemblies must be run through Dotfuscator multiple times.

The table below indicates the results when combining these two options in different ways.

Honor Instrumentation Attributes Strip Instrumentation Attributes Notes
True True Default settings. The assembly is instrumented and attributes are removed.
False True The assembly is not instrumented and the attributes are stripped out. This is useful for creating test builds that do not include Tamper Detection or Application Analytics functionality.
True False The assembly is instrumented and the attributes are left in. This is currently not a recommended combination.
False False The assembly is not instrumented and the attributes are left in. This is useful for assemblies that need to be obfuscated but will need to have Tamper Detection or Application Analytics added in a subsequent step.

PreEmptive Analytics and other Dotfuscator Features

When using Application Analytics, other Dotfuscator features are available. The injected runtime code is annotated with obfuscation attributes so user configuration (beyond what is necessary for the input assemblies) is not required to perform renaming, removal, or other transforms on applications using Application Analytics.

 

 


© 2016 PreEmptive Solutions, LLC. All Rights Reserved.

www.preemptive.com