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

In addition to the attributes configured via the Instrumentation Editor, there are several instrumentation-related options in the Dotfuscator GUI that apply to the entire Dotfuscator project, as well as individual assemblies.

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 seven options for Instrumentation: Analytics Version, Enable, Merge Runtime, Send Analytics Messages, Send Debug Check 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

The Enable option turns Checks, Exception Tracking, and PreEmptive Analytics on (default) and off. If this is turned off, Dotfuscator ignores all such attributes contained within the input assemblies or configured in Dotfuscator.

Merging or Referencing the Runtime

If set to "Yes" (default), the Merge Runtime option tells Dotfuscator to add the runtime code required for instrumentation 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 instrumentation.

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.

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.

Enabling Telemetry

Telemetry from PreEmptive Analytics, Debug Checks, Shelf Life Checks (and Sign of Life messages), and Tamper Checks can be enabled using the Send Analytics Messages, Send Debug Check Messages, Send Shelf Life Messages, and Send Tamper Messages options, respectively.

Note: These settings are "No" by default. You must enable them in order for the instrumented application to send messages.

Assembly Level Configuration Options

Dotfuscator allows granular control of instrumentation attribute handling. 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 Checks 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.

See Also

GUI Guide

 

 


© 2016 PreEmptive Solutions, LLC. All Rights Reserved.

www.preemptive.com