PreEmptive Dotfuscator and Analytics CE

PreEmptive Dotfuscator and Analytics Community Edition 5.5
PreEmptive Dotfuscator and Analytics CE
www.preemptive.com

Glossary Item Box

Dotfuscator is the leading .NET obfuscator and compactor that helps protect programs against reverse engineering while making them smaller and more efficient. Dotfuscator and Analytics also provides a way of injecting additional pre-built functionality that provides usage tracking, tamper detection, and expiration into your .NET applications.

In the PreEmptive Dotfuscator and Analytics CE Documentation

Introduction

Explains the benefits of using PreEmptive Dotfuscator and Analytics Community Edition 5.5.

Getting Started

Explains how to launch PreEmptive Dotfuscator and Analytics Community Edition 5.5 and register your product.

Configuration Options

Explains how to obfuscate your application using renaming. Then explains how to add feature usage tracking, tamper detection, and expiration to your application using Dotfuscator's code injection capabilities.

Results

Shows a visual representation of your application after Dotfuscator and Analytics rebuilds it.

Beyond Obfuscation

Explains the new category of detective control in Dotfuscator and Analytics CE, allowing you to better monitor, manage, and protect your applications

Free Runtime Intelligence Services Portal

Describes the freely available reports and dashboards that give you insight into how your application is being used.

See Also

Introduction
Introduction

Getting Started
Getting Started

Configuration Options
Configuration Options

Results
Results

Beyond Obfuscation
Beyond Obfuscation

Portal
Free Runtime Intelligence Services Portal

© 2002-2012 PreEmptive Solutions. All rights reserved.


Introduction

Introduction

Glossary Item Box

Your copy of Microsoft Visual Studio 11 includes a free license for PreEmptive Dotfuscator and Analytics Community Edition 5.5 (Dotfuscator and Analytics CE 5.5). Like earlier versions of Dotfuscator and Analytics CE included in Visual Studio 2010, 2008, 2005 and 2003, it provides you with tools to protect and harden your .NET applications. Dotfuscator and Analytics CE 5.5 works on compiled assemblies without the need for additional programming or even access to source code.

Dotfuscator and Analytics CE 5.5 also offers a range of services for developers, architects and testers. Examples of the code protection, monitoring and management capabilities included in Dotfuscator and Analytics CE 5.5 are:

  • Exception tracking to monitor unhandled, handled, or thrown exceptions occurring within the application.
  • Tamper defense to detect the execution of tampered applications, transmit incident alerts, and terminate tampered sessions.
  • Application expiration behaviors that encode an “end-of-life” date, transmit alerts when applications are executed after their expiration date, and/or terminate expired application sessions.
  • Session tracking to determine what applications have been executed, what versions of those applications, and for how long.
  • Feature usage tracking to determine what features are being used, in what sequence, and for how long.

In this section

Capabilities

Upgrades

See Also

Introduction
Capabilities
Upgrades


Capabilities

Capabilities

Glossary Item Box

This section focuses on the capabilities of Dotfuscator and Analytics CE 5.5 with some references to advanced options available through upgrades.

Dotfuscator and Analytics CE 5.5 is a post-build system for .NET applications. With Dotfuscator and Analytics CE 5.5, Visual Studio users are able to obfuscate assemblies and inject tamper detection, application expiration, session monitoring, and feature tracking functionality – all without programming or access to the original source code. This information can be directed to one or more endpoints (or clouds) for reporting and analysis.

Application Protection

Intellectual Property theft, piracy, and tampering each materially increase financial, operational, and reputational risk – for both application suppliers and consumers. Dotfuscator and Analytics CE 5.5 includes baseline obfuscation to reduce the risk of unauthorized access to source code through reverse engineering.

Application Defense

Advances in application architectures and distributed computing have made application components increasingly vulnerable to attack and more difficult to defend on instance-by-instance and session-by-session bases. Dotfuscator and Analytics CE 5.5 includes the ability to inject logic that detects the execution of tampered code and, optionally, transmit an incident alert to a developer-specified endpoint and/or terminate the tampered session – all in real-time, across devices, platforms, and distribution models.

Application Measurement

Access to detailed information regarding the behavior of .NET applications once they’ve been deployed to users – whether in beta, early release or general availability – has been a dream of application developers. Dotfuscator and Analytics CE 5.5 can help answer such questions as:

  • How often does my application crash and how often are handled exceptions encountered?
  • What applications are my users running, by version?
  • What features are being executed and in what order?
  • How long do those features take to execute and what is the trend over time?
  • Just how stable is the users' experience in the real world?

Traditionally, the impact of gathering this information on end-user performance has meant that few development teams have taken the steps to get access to such information. And when they do, the complexity of maintaining the analytics makes it brittle and hard to adapt to changes.

Dotfuscator and Analytics CE 5.5 makes it easy for developers, testers and architects to obtain this information with little or no impact on end-user performance. Dotfuscator and Analytics CE 5.5 can inject session, feature, and exception monitoring down to the method level and transmit runtime data to one or more endpoints. Whether you are managing a beta cycle, a portfolio of web services, or a product evaluation lifecycle, Dotfuscator and Analytics CE 5.5 can provide powerful insight into adoption, user behavior, stability, and ultimately, the business impact of software.

Application Management

Application portfolio management is becoming a critical issue for ISVs and enterprises alike, which means it’s becoming an issue for developers. As software becomes easier to build and more difficult to track, organizations are looking for ways to safely and reliably encode business rules and IT policies directly into their software.

The challenge becomes how to deliver on these requirements without the need to make significant changes to the software. To meet this challenge, Dotfuscator and Analytics CE 5.5 can enforce end-of-life deadlines and transmit audit streams to track attempted usage on or after an application’s expiration date.


Upgrades

Upgrades

Glossary Item Box

Professional developers requiring ongoing support, maintenance and product updates will want to upgrade their copy of Dotfuscator and Analytics CE 5.5 to a commercial edition of Dotfuscator that meets the unique needs of their application development organization. For more information on the advanced application security, monitoring, measurement, and management capabilities of the full Dotfuscator product, including a detailed comparison of all editions of Dotfuscator, please visit The Dotfuscator Family Overview. Fully-supported trials of Dotfuscator are available on request.

Commercial versions of Dotfuscator include enhanced security, tighter integration with Visual Studio, and other major extensions to the monitoring and management capabilities of Dotfuscator and Analytics CE 5.5. These include:

  • Application protection: Access to the full range of expanded obfuscation transforms, as well as the ability to embed watermarking and the ability to link and/or prune assemblies.
  • Application defense: The ability to inject custom application defense behaviors and activate tamper incident reporting services.
  • Application measurement: The ability to create extensible data “signals”, create encrypted transmissions, track an unlimited number of features and methods, access a rich set of application analytics services, and the ability to report on caught or thrown exceptions (in addition to unhandled).
  • Application management: The ability to inject custom behaviors, add a warning date, obtain reporting analytics and encrypt transmissions.

See Also

The Dotfuscator Family Overview


Getting Started

Getting Started

Glossary Item Box

To begin using Dotfuscator and Analytics CE, follow these steps:

  • Launch Visual Studio.
  • From the Visual Studio menubar, click Tools > PreEmptive Dotfuscator and Analytics.

When PreEmptive Dotfuscator and Analytics CE opens, the Start screen displays on your desktop:

The program consists of three panels: the navigation tree, work area, and build output.

From the Start screen, you may perform several actions. If Dynamic Content is enabled, then you can view the release notes about the latest version of Dotfuscator Pro and see the latest news releases from PreEmptive Solutions. If Dynamic Content is disabled, then the option to set user preferences displays on the Start screen. The option to register Dotfuscator and Analytics is visible at all times. Dynamic Content can be enabled or disabled in User Preferences.

Setting User Preferences

In the Start screen, if Dynamic Content is disabled, there is a link you may click to set User Preferences, or you may click Tools > User Preferences. Regardless of which path you choose to get to User Preferences, this dialog box displays:

If necessary, enter the configuration details of your network's proxy server requirements in the Network settings section of the User Preferences dialog. Proxy information is not required if you do not have a proxy server or if those settings are controlled via Internet Explorer.

If you wish to use an XML viewer for viewing Dotfuscator XML files that is not your system's default viewer, you may click Browse... in the XML viewer application section and locate the application you wish to use.

In the News and updates section, you may opt to allow Dotfuscator to periodically check for updates. Also, this section is where you can enable Dynamic Content to be displayed in the Start screen.

Latest Version of Dotfuscator and Analytics

The work area contains a link to the latest release notes for Dotfuscator and Analytics. If Dynamic Content is disabled, this link will take you to the Dotfuscator and Analytics version history page at www.preemptive.com.

Registration Status

You can register Dotfuscator and Analytics CE via the Register Now link. Clicking this link displays the registration dialog.

Register your product to receive updates and enhancements to Dotfuscator and Analytics CE. Enter your information within each field. For automated submission, select Register by web.

Clicking Next takes you to the second page of the Registration dialog. If necessary, enter the configuration details of your network's proxy server requirements. Click Submit upon completion.

Once your registration request is received and processed, you will receive a confirmation email from PreEmptive Solutions containing your registration verification code and credentials to the registered support area of www.preemptive.com where you will be able to access updated versions of Dotfuscator and Analytics CE.

You are now ready to begin obfuscating and instrumenting your application with Dotfuscator and Analytics CE.

In this section

Inputs

Properties

See Also

Dotfuscator Change Log

Getting Started
Inputs
Properties


Inputs

Inputs

Glossary Item Box

To start using Dotfuscator and Analytics CE, add one or more input assemblies or packages to your project. To add inputs to your project, you need to have the Inputs screen open in your work area. You can activate this screen by right-clicking the project node in the navigation tree and selecting Add Inputs or by selecting the Inputs option in the navigation tree.

To add your input assemblies or packages to the list of Inputs you may drag and drop your .exe/.dll files or directories into the Inputs section of the page.

You may also click the "Add Input" button or right click in the Inputs area and choose Add Input. When adding inputs this way, you can browse to where your input is located and select it or enter the path to the input manually.

Input Properties

In the Properties section of the work area panel, select or de-select:

Honor instrumentation attributes: Selecting Honor instrumentation attributes tells Dotfuscator to process these attributes and perform the indicated instrumentation transformations on the target assembly. De-selecting this option tells Dotfuscator to ignore any instrumentation attributes.

Instrumentation attributes are custom attributes that can be applied in your source code to track application stability, features, usage, and to add shelf life functionality.

Honor obfuscation attributes: Selecting Honor obfuscation attributes tells Dotfuscator to process these attributes and perform the indicated obfuscation transformations on the target assembly. De-selecting this option tells Dotfuscator to ignore any obfuscation attributes.

Obfuscation attributes are custom attributes that can be applied in your source code to explicitly declare the inclusion or exclusion of types, methods, enums, interfaces, or members from various types of obfuscation. The attribute you would use to include or exclude types, methods, enums, interfaces, and members from obfuscation is System.Reflection.ObfuscationAttribute. If you want to denote that a specific assembly will have its items included or excluded from obfuscation, you would use System.Reflection.ObfuscateAssemblyAttribute. Dotfuscator and Analytics CE only supports renaming. Additional obfuscation functionality is available in the commercial version of Dotfuscator.

Library mode: This setting tells Dotfuscator that the selected input assembly constitutes a library. For obfuscation purposes, a library is defined as an assembly that is referenced from other components not specified as one of the inputs in this run. When an assembly is obfuscated in Library Mode, publicly visible items are not renamed, thus keeping your public API accessible to external callers.

Strip obfuscation attributes: Dotfuscator can strip out all of the obfuscation attributes when processing is complete, so output assemblies will not contain clues about how it was obfuscated. Selecting this option tells Dotfuscator to remove these attributes from the target output assembly. De-selecting this option tells Dotfuscator to leave the attributes in the output assembly unless the individual attributes designate that they should be stripped via the StripAfterObfuscation property.

Transform XAML: Dotfuscator can rename items in XAML resources as used in Silverlight applications as well as the compiled XAML resources (BAML) of Windows Presentation Foundation applications. The default value is True, which tells Dotfuscator to attempt to rename items in the markup resources and match the renaming to the items references in the code-behind. Leaving this option enabled significantly strengthens the obfuscation of Windows Presentation Foundation and Silverlight applications as well as decreases the number of items that must be manually excluded from renaming.

Input Information

This section of the Inputs work area provides general data about the currently selected assembly, including the file name, file path, expanded file path (useful if ${configdir} or other properties are used), file size, last modified date, and version.


Properties

Properties

Glossary Item Box

The Properties item on the navigation tree brings up the Properties configuration in the work area. It contains six tabs, three of which are available to Dotfuscator and Analytics CE users.

Project Properties

Project Properties can be thought of as simple string substitution macros that may be used wherever a filename or path is required. The Project Properties screen is where you can view, delete, and manually add user-defined name/value pairs as Project Properties and to view External Properties. External properties are those either defined by Dotfuscator (e.g. configdir, appdatadir) or those passed on the command line via the /p switch. Project Properties are especially useful in creating obfuscation build templates to support multiple projects and configurations. Properties are referenced with the following syntax:

Property Reference Syntax Copy Code
${property_name}

Property references are case sensitive, therefore ${MyProjectDir} references a different property than does ${myprojectdir}. Property references are interpreted literally and may not be nested. Currently, property references may only be used as values in the dir or name attributes of the <file> element.

Dotfuscator uses 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 project property.
  • If still not found, use the empty string as the value.

External Properties

The Property column contains the name of the property, and the Value column contains the value of that property. Dotfuscator and Analytics CE defines the following three Properties and Values:

  • applicationdir reflects Dotfuscator and Analytics’ installation directory where the Dotfuscator application files are located.
  • appdatadir reflects Dotfuscator and Analytics' local data directory.
  • configdir reflects the directory in which the current project's configuration file resides.

Project Properties

This section allows for the definition and assignment of arbitrary additional properties that will be used during the build process. These properties will be evaluated in the same manner as the external properties. In the above example, projectdir is the Property and myproject is the Value of the Property.

Feature Map Strings

The Feature Map Strings section is used for Declarative Obfuscation. Declarative Obfuscation is implemented via attribute decoration within the source code while it is being written. The attributes that are used to control Declarative Obfuscation are System.Reflection.ObfuscateAssemblyAttribute and System.Reflection.ObufscationAttribute. System.Reflection.ObfuscateAssemblyAttribute controls the obfuscation of the assembly as a whole. System.Reflection.ObufscationAttribute controls the obfuscation of individual types and their members. Feature Map Strings enable you to declare, within the source code, what should and should not be obfuscated by using attributes.

In this section, you can add, edit, and remove feature map strings. To add a map string, click in the Map String field and type the name of the string. When you do this, a row of checkboxes displays beneath the current row containing the feature you can select. For example,

  • testmode is the name of the Map string that was entered
  • renaming is the Feature of the Map string that was selected from the row beneath.

In Dotfuscator and Analytics CE, renaming is the only available feature. Commercial versions of Dotfuscator support additional features as follows:

Feature String | Action
*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

By decorating items with an obfuscation attribute and ensuring that their input assemblies are set to honor obfuscation attributes, you can specify which items in you application should not be renamed. In the following code sample your method is invoked via reflection and should be excluded from renaming.

Invoked via Reflection, Excluded from Renaming: Copy Code
[System.Reflection.Obfuscation(Exclude=true, Feature="renaming")]
public void CalledFromReflection(int someValue) {

If you need to exclude a method from obfuscation in a specific build configuration, then create a Feature Map declaration and set the feature value of the obfuscation attribute to match. In the screenshot above, we have set a Feature Map string of "testmode" that will be used to exclude items from being renamed. In the code sample below, we have decorated our method so that it will be renamed by Dotfuscator unless the "testmode" feature string is defined.

Testmode Feature Map Declaration: Copy Code
[System.Reflection.Obfuscation(Exclude=true, Feature="testmode")]
public void OnlyCalledFromReflectionInTestMode(int someValue){

Build Settings

This is where you set the destination directory, build configuration, and global obfuscation settings.

Directories

The Destination directory: is required as that is where the output from the build will reside. For example, you would type ${projectdir}\output in this field, or click Browse to determine its location.

Build Configuration

Selecting Investigate only shows you what will occur as a result of processing the input assemblies, without actually writing output assemblies. This is useful for creating map files and reports.

Build output verbosity: enables you to determine the am

The Temporary directory: is optional and is used to store temporary files during processing. By default Dotfuscator and Analytics CE uses your Windows Temporary directory. If you wish to specify this directory, enter the name of the directory in this field. For example, you could enter ${projectdir}\temp in this field, or click Browse to determine its location.

ount of information presented to you in the Build Output panel. Selecting Quiet keeps the output information minimal. Selecting Verbose provides you detailed information about all actions occurring during the build process. The Verbose option is especially helpful if you are attempting to fine-tune your results.

Global Obfuscation Settings

In this section, you can select or deselect Inherit obfuscation attributes and Smart obfuscation. Inherit obfuscation attributes specifies whether an obfuscation attribute that is put on a type will also be applied to derived types. Smart Obfuscation uses static analysis to determine what elements should be excluded from renaming. Sometimes a rule can recognize that an action needs to be taken, but cannot determine what specific action to take because static analysis does not yield enough information. When this happens, the rule issues a warning.

You can also determine if you want Smart obfuscation reporting by selecting All for all messages, None for no messages, or Warnings only. When Smart Obfuscation is enabled, and the project is built, a Smart Obfuscation report will be presented in its own tab near the Build Output tab and if any Smart Obfuscation warnings are generated, they will be presented in the Smart Obfuscation Warnings tab.

Assembly Load Path, Build Events, and Signing

These features are exclusive to Dotfuscator Professional Edition. To request information and a free 14-day evaluation (where applicable), click the Try Now button on the toolbar. To learn how to purchase Dotfuscator Professional Edition, click the Buy Now button on the toolbar. Alternatively, you may select these options from the Help menu.


Configuration Options

Configuration Options

Glossary Item Box

The Configuration Options section is where you can set renaming options and exclusions, choose built-in renaming rules, and configure analytics settings.

Options such as Control Flow Obfuscation, String Encryption, Removal, Linking, and PreMark are exclusive to Dotfuscator Professional Edition. To request information and a free 14-day evaluation (where applicable) click the Try Now button on the toolbar. To learn how to purchase Dotfuscator Professional Edition, click the Buy Now button on the toolbar. Alternatively, you may select these options from the Help menu.

In this section

Renaming

Analytics

See Also

Configuration Options
Renaming
Analytics


Renaming

Renaming

Glossary Item Box

The Renaming editor displays four configuration tabs: the Getting Started tab, which describes various application protection features and explains how to configure renaming settings and exclusions; the Exclusions tab, which is used to graphically set custom exclusion rules; the Options tab, which is used to configure other options related to renaming; and the Built-in Rules tab, which displays pre-configured renaming exclusion rules that apply to specific application types or technologies.

Renaming Exclusions

The Renaming Exclusions tab lets you determine which parts of your program are to be excluded from the renaming process. You may exclude specific items from renaming by browsing the navigation tree and checking those items.

The Rename Exclusions Tab gives you complete granular control over all parts of your program that you may wish to exclude from the renaming process.

You may exclude specific items from renaming by browsing the tree view of your application and checking the items you want to exclude. In addition, you may visually create your own custom rules for selecting multiple items for exclusion.

Custom rules can be defined to exclude larger selections of items without requiring you to individually select them for exclusion in the treeview. Rules can be defined to exclude namespaces, classes, methods, properties, events, and fields based on their name. Additionally, a Regular Expression can be used to provide a way to specify a pattern with any items that match that pattern from being excluded from obfuscation.

To help you fine-tune your exclusion rules, you can preview their cumulative effects at any time by clicking the Preview button. The application tree view shades all items selected for exclusion.

To preview a specific rule, right click on the rule whose effects you wish to see, select Preview, and Dotfuscator highlights items that will be excluded due to that rule.

Excluding a namespace will exclude all types and their members in the specified namespace. To exclude a namespace select the Add Namespace button and enter the name of the namespace you wish to exclude in the Name field. If you wish to use a regular expression to match multiple namespaces ensure that the Regular Expression box is checked and that the Name field contains the regular expression you wish to match against.

Types can be excluded by either matching only on their names or by optionally including a set of attribute specifiers that will further restrict the types excluded from renaming. Nested classes can be excluded by using a backslash “\” as a delimiter between the outer and inner class. By checking the Regular Expression box the value in the Name field will be matched as a regular expression rather than a literal string when determining which items to exclude from obfuscation. Type exclusion can follow inheritance rules. If the Apply to Derived Types option is selected then the exclusion rule will additionally be applied to the matched types and any types that inherit from them.

A number of other exclusion options are available and are defined as child rules to a containing type rule. To create a child rule right click on the type rule you wish to enhance and select the particular child rule implementation you wish to add.

Rules to exclude methods, fields, properties, and events are set by creating a type rule for the type(s) that contain those items and adding a child rule for the appropriate item. As with namespaces and types, the exclusion of other items can be based on their literal name or a regular expression.

Types, methods, fields, and properties can be selected for exclusion by annotating them with custom attributes, then creating a type exclusion rule containing a CustomAttribute child rule. Matching on the name of the CustomAttribute is used to determine if an item should be excluded and regular expression matching logic will be implemented if the Regular Expression option is selected. Exclusion by custom attribute can also be propagated down the inheritance hierarchy by using the Allow Inheritance option which additionally excludes any subtypes or overriding methods and properties with the specified attribute.

Supertypes can also be excluded from obfuscation by adding a supertype child rule to a type rule definition. An item is excluded from obfuscation if it inherits from one or more supertypes that match the supertype exclusion condition.

In order to specify that an exclusion rule apply only to a method, field, property, event, supertype, or custom attribute and to include the containing type in obfuscation, select the Exclude Type option when defining the type rule. This option leaves the type included for renaming purposes and only evaluates the child rules.

Renaming Built-in Rules

The Renaming Built-in Rules tab displays pre-configured renaming exclusion rules that apply to specific application types or technologies. Each rule has a description that displays on the screen when the rule is selected. You can apply a built-in rule to your project by checking it.

Renaming Options

The Renaming Options tab is used to set renaming options and to identify map file output options. The Renaming Options section contains configuration settings that control how renaming is performed.

  • Enable renaming - Select this to enable renaming. You may also right click on Renaming in the navigation tree and check Enable to enable renaming. Likewise, if renaming is enabled, you may disable it by right clicking on Renaming in the navigation tree and unchecking Enable. If this option is unchecked, Dotfuscator will not perform renaming when your project is built.
  • Ensure compatibility with XML serializer - Select this to configure renaming in such a way as to allow XML serialization.
  • Introduce explicit method overrides when renaming - Select this to allow overriding methods to have different names from those of the methods they override.

You may also select the appropriate Namespace handling options:

  • Flatten and rename removes the namespaces.
  • Rename only renames the namespaces, but keeps the hierarchy.
  • Preserve keeps the namespaces exactly as they are in the input assembly.

The Output map section is where the destination of the output map file is set. You also have the option of overwriting the output file each time you build the application without generating a backup of any existing map files.


Analytics

Analytics

Glossary Item Box

Analytics adds pre-built application usage tracking, exception reporting, binary tamper detection, and application expiration to your applications without requiring any additional code. Dotfuscator and Analytics injects the required code for you. You can define injection points either via custom attributes in your source code or via extended attributes specified within the Dotfuscator and Analytics user interface.

The Analytics editor allows you to add, edit, and review custom and extended attributes. In Dotfuscator and Analytics CE, the Analytics editor displays three configuration tabs: the Getting Started tab, the Attributes tab and the Options tab. The Getting Started tab describes the various analytics options available and how to configure them. The Attributes tab is where you add new extended attributes to methods or modify custom attributes that are already present. The Options tab is where you select which types of messages - application analytics, shelf life notification, and tamper alert - you want to send to the Runtime Intelligence Service.

Assembly Attributes

Assembly attributes are attributes that may be applied at the assembly level. Assembly attributes are used by the code injection process to add unique identification data to an assembly, such as company information, or to track exceptions across the entire assembly.

Required Assembly Attributes

To instrument your application for Runtime Intelligence Services, there are two required assembly attributes. These attributes are added to the application by right clicking on an assembly node in the Select the attribute to modify: tree.

BusinessAttribute

The BusinessAttribute is required and contains values that are used to identify the company that owns the application being instrumented. This attribute consists of a CompanyKey, which should be set to "7d2b02e0-064d-49a0-bc1b-4be4381c62d3" for use with the Free Runtime Intelligence Services Portal. For your convenience, the CompanyKey is set to this GUID by default. If you target a different endpoint, please use the CompanyKey provided by PreEmptive Solutions or generate a new unique identifier by pressing the "..." button associated with the CompanyKey entry area. The CompanyName may be left empty; however, you are encouraged to enter the name of the company for Runtime Intelligence Services Portal personalization.

ApplicationAttribute

The ApplicationAttribute is required and contains values that are used to identify the instrumented application:

  • ApplicationType. This identifies the type of application being instrumented such as a Windows application.
  • GUID. This is a unique identifier for the application that is generated by clicking the "..." in this field.
  • Name. This is the name of the application. If you leave this blank, the name will be filled in via reflection (if allowed at runtime). Only fill it in if you want a name in the portal that is different from the name in the assembly, or if reflection can't be used by your application at runtime (e.g. it is a Silverlight application).
  • Version.This is the version of the application. If you leave this blank, the name will be filled in via reflection (if allowed at runtime). Only fill it in if you want a version in the portal that is different from the version in the assembly, or if reflection can't be used by your application at runtime (e.g. it is a Silverlight application).

BinaryAttribute

The BinaryAttribute contains a value that is used to identify the specific assemblies that make up the instrumented application. The GUID is the unique identifier for the assembly and is used to specify which assembly was altered when tampering was detected. Although this attribute is not required, if you are using tamper detection, you should set a binary attribute on each assembly so the notifications can include the assembly information.

ExceptionTrackAttribute (Assembly level)

The ExceptionTrackAttribute is used to track unhandled exceptions at both the assembly and method level. The assembly level ExceptionTrackAttribute can be used to detect exceptions that occur anywhere in an assembly. When Dotfuscator and Analytics encounters an ExceptionTrackAttribute, it adds code that detects unhandled exceptions by registering an UnhandledException event handler on the current AppDomain (for .NET Framework applications) or current Application (for Silverlight applications). A explicit exception report opt-in can be set through a built-in or custom-built exception dialog, which can also present a privacy policy URI and collect end user contact information or information about the context in which the exception happened as written by the end user.

Functional Attributes

Functional Attributes can be used to track application stability, feature usage, tampering attempts, and the frequency of an application's use. They may also be used to make an application cease to function after a specified date.

SetupAttribute

The SetupAttribute is used to track when an application has started. Dotfuscator and Analytics injects startup code for message sending and sends the startup message. There must be one or more methods with this attribute in an assembly or application that uses Runtime Intelligence. This attribute should be placed as closely as possible to the normal application startup logic. At runtime, the functionality generated by this attribute will begin sending usage data back to the Runtime Intelligence Services Portal. Optionally, you may specify the location in your code of functionality that controls the transmission of messages (opt-in or opt-out behavior). Dotfuscator and Analytics will use this information when generating the initialization code.

When you add the SetupAttribute, you may set the Custom Endpoint destination of the messages.The endpoint options include the free Runtime Intelligence Services Portal as a default, the commercially available Runtime Intelligence Services Portal, or a custom endpoint of your own choosing.

The SetupAttribute also provides the ability to implement either opt-in or opt-out functionality within your application. This functionality enables your users to elect to provide their usage data or not. To provide the setting determining if execution and usage data will be collected and sent to the Runtime Intelligence Services Portal, you can specify either a method, method argument, field, or property containing or returning a boolean value. If the value is true then the application will transmit usage data as configured. If the value is false then no usage data will be transmitted by the application.

To configure the opt-in/opt-out behavior you must configure the OptInSourceElement property with the appropriate type of code element that will contain the Boolean value. The OptInSourceName must be the name of the element that contains the Boolean value to be used to determine if Runtime Intelligence data will be collected and transmitted. At runtime, the source value should be set by your application code before the setup method is called. The OptInSourceOwner property may be left off if the element is defined in the same class as the method attributed with the SetupAttribute. If the OptInSourceElement is a method argument then it must correspond to a method parameter on the method that is annotated with the SetupAttribute.

TeardownAttribute

The TeardownAttribute is used to track when an application has successfully stopped. Dotfuscator and Analytics injects teardown code for message sending and sends the shutdown message. There must be one or more methods with this attribute in an assembly or application that uses Runtime Intelligence analytics. The teardown method does not necessarily have to be the last method called, but it should have the property that it is executed exactly once when the application shuts down, as close as possible to exit.

FeatureAttribute

The FeatureAttribute is for tagging features you wish to track using the Runtime Intelligence Service. This attribute may be placed on any method or property. Runtime Intelligence tracks features using the name provided in this property. Multiple methods can be given the same name which will cause the same usage indicator on the Runtime Intelligence Services Portal to be updated. A feature can be either an atomic event or the execution duration can be measured. To simply track that a feature has been executed, use a FeatureEventType of 'Tick.' To measure the execution duration of the feature, use two feature attributes with the same name, one with a FeatureEventType of 'Start' and the second with a FeatureEventType of 'Stop.' In the Feature Scorecard report on the Portal, you will see the minimum, maximum, and average durations for each feature execution.

InsertShelfLifeAttribute

Add an InsertShelfLifeAttribute to any property or method where you would like an application expiration check to occur. At runtime, your application can send an expiration notification message to the Runtime Intelligence Services Portal if the application is executed after the expiration date has occurred. Upon expiration, the default behavior is to send the expiration notification message; however, you may set the ExpirationNotificationSinkElement property to DefaultAction, which will optionally send an expiration message to the Runtime Intelligence Services Portal and cause the application to immediately exit. In order for the expiration notification messages to be sent, the application must contain methods marked with a Setup and Teardown attribute.

A Shelf Life Activation Key (SLAK) is required to instrument your application with this feature. To obtain a SLAK, please go to our Support site: http://www.preemptive.com/support/index.html.

InsertSignofLifeAttribute

The InsertSignofLifeAttribute sends a message each time the method tagged with this attribute is called. At runtime, the sign of life code sends a message indicating that the application has been executed. In order to use this attribute, the application must contain methods marked with a Setup and Teardown attribute.

A Shelf Life Activation Key (SLAK) is required to instrument your application with this feature. To obtain a SLAK, please go to our Support site: http://www.preemptive.com/support/index.html.

InsertTamperCheckAttribute

The InsertTamperCheckAttribute injects code that detects if a user has modified your assemblies. If it detects that the assemblies have been altered, it can send a tamper notification message to the Runtime Intelligence Services Portal. Upon detection, the default behavior is to send the tamper notification message and exit the application; however, you may set the ApplicationNotificationSinkElement property to DefaultAction, which will cause the application to immediately exit. If you wish to send Runtime Intelligence tamper messages, do not put this attribute on the same method containing the Setup Attribute. Also, ensure that any methods marked with the tamper check attribute are executed after the method containing the setup attribute.

ExceptionTrackAttribute (Method level)

The method level ExceptionTrackAttribute can be used to detect locally unhandled exceptions that pass through a particular method. When Dotfuscator and Analytics encounters a method level ExceptionTrackAttribute, it adds code that wraps the method in a try/catch block and re-throws the exception. Method-level ExceptionTrackAttributes can collect the same opt-in and extra information as assembly level ExceptionTrackAttributes.

Analytics Options

The Analytics Options tab is where you may configure the behavior of your instrumented applications. Instrumentation (code injection) of your applications may be enabled or disabled for your current project by either un-checking the Process PreEmptive analytics attributes check box, or by right clicking on Analytics in the navigation tree and un-checking the Enable option. If this option is unchecked, Dotfuscator will not perform code injection when your project is built.

The Runtime Intelligence configuration section of this tab is where you may select which message types will be sent to the Runtime Intelligence Services Portal. The Send application analytics messages option enables the sending of messages related to feature usage. The Send shelf life notification messages option enables the sending of shelf life expiration and sign of life messages. The Send tamper alert messages option enables the sending of tamper notification messages. Un-checking either the Shelf Life or Tamper message options will only affect the transmission of those messages; if you have selected the DefaultAction to occur, your application will still exit as expected.

See Also

PreEmptive Solutions Support


Results

Results

Glossary Item Box

Once your project is built, you can inspect the results in the Results Tab.

Here you can browse the tree view and see how Dotfuscator and Analytics renamed your types, methods, and fields. The new names appear as child nodes under the original nodes in the tree. This information is also saved to the map file as configured in the Renaming Options.


Beyond Obfuscation

Beyond Obfuscation

Glossary Item Box

Dotfuscator and Analytics CE combines its trusted obfuscation technology with injection technology to provide near real-time views into application deployment, stability, and usage. In addition to obfuscation, Dotfuscator and Analytics CE offers a new category of detective control to better monitor, manage, and protect your applications. Dotfuscator and Analytics CE can:

  • Provide a near real-time view into application integrity and activity at runtime.
  • Instrument applications to detect if they have been tampered with and if so, optionally send a message to the Runtime Intelligence Service.
  • Instrument applications with expiration, de-activation, and notification logic that reacts to application expiration by exiting the application and/or sending a Runtime Intelligence Services message.

In this section

Introduction to Active Tamper Defense

Application Expiration

Application Analytics

Exception Tracking

See Also

Beyond Obfuscation
Introduction to Active Tamper Defense
Application Expiration
Application Analytics
Exception Tracking


Application Analytics

Application Analytics

Glossary Item Box

Runtime Intelligence is a service and a technology that gives application authors and users insight into how their applications are being used. Dotfuscator and Analytics can be used to Runtime Intelligence Enable .NET applications and components.

Dotfuscator and Analytics is used to instrument an application such that a message is sent when the application starts and stops and when designated features are being used. The Runtime Intelligence Service aggregates this lifecycle data from the application and exposes it through the Runtime Intelligence Portal.

In this section

Supported .NET Application Types

See Also

Beyond Obfuscation
Supported .NET Application Types


Supported .NET Application Types

Supported .NET Application Types

Glossary Item Box

Dotfuscator can perform Runtime Intelligence processing for all .NET assemblies except for the following:

  • Managed C++ input assemblies containing native and managed code.
  • Multi-module input assemblies.
  • Input assemblies that target .NET 1.0


Exception Tracking

Exception Tracking

Glossary Item Box

Exception Tracking is a method for automatically detecting and responding to exceptions in the target application as they occur. Dotfuscator and Analytics injects code that can detect caught, thrown, or unhandled exceptions. Once detected, the exception tracking code can collect details from the user and report the detected exception to a Runtime Intelligence endpoint. A user can explicitly allow an exception report to be sent even if he or she has previously opted out of sending Runtime Intelligence messages, and can provide comment and contact information to be sent along with the report. In addition, the developer can specify a custom action be taken when an exception is detected.

To facilitate the common use case of unhandled exception reporting, Dotfuscator and Analytics can inject a pre-made Exception Report Dialog which provides a consistent user experience for reporting exceptions. Minimal configuration is needed to instruct Dotfuscator and Analytics to track unhandled exceptions, display the exception report dialog which will obtain explicit user consent and collect optional comment and contact information from the user, and send the report to the configured Runtime Intelligence endpoint.

In this section

Exception Reporting and the ExceptionTrack Attribute

Collecting User-specified Exception Report Information

See Also

Beyond Obfuscation
Exception Reporting and the ExceptionTrack Attribute
Collecting User-specified Exception Report Information


Exception Reporting and the ExceptionTrack Attribute

Exception Reporting and the ExceptionTrack Attribute

Glossary Item Box

Exception Reporting

Once an exception is detected, it can be reported to the configured Runtime Intelligence endpoint by setting the SendReport property of the ExceptionTrack attribute to true (the default). The sending of exception reports will honor the opt-in setting of the user if an OptInSource has been configured. Dotfuscator and Analytics can be configured to obtain explicit consent from the user to send the exception report message. In this case, the user's explicit consent will override the Runtime Intelligence opt-in setting if one has been configured. To obtain explicit consent to send the exception report message, specify a ReportInfoSource.

Dotfuscator and Analytics can also be configured to obtain information from the user such as a description of the actions leading to the exception and a contact address that the developer can use to solicit additional information or provide notification of an issue that has been fixed. This information will be attached to the exception report message. To obtain this type of user-provided information, specify a ReportInfoSource.

The report info source settings are optional. If they are omitted, no user-provided information will be collected, and the sending of the exception report messages will be controlled by the Runtime Intelligence opt-in setting.


Collecting User-specified Exception Report Information

Collecting User-specified Exception Report Information

Glossary Item Box

When using Exception Tracking, Dotfuscator and Analytics can be configured to obtain explicit user consent to collect comment and contact information from the user. These are provided in the form of key-value pairs that are read at runtime during the construction of an exception report message.

To provide this user-specified report information, specify a ReportInfoSource on the attribute corresponding to the message you wish to send. Dotfuscator and Analytics uses the ReportInfoSource to generate code that gathers the key-value pairs at runtime. The ReportInfoSource is an IDictionary or IDictionary<string,string> valued property, method, field, or when using method-level exception tracking, method argument; it is the developer's responsibility to ensure that correct values are available in the ReportInfoSource at the time an exception is detected.

Using the Built-in Exception Report Dialog as the ReportInfoSource

Dotfuscator and Analytics can inject a pre-made Exception Report Dialog to ease configuration for most scenarios and provide a consistent user experience for exception reporting. To use the built-in dialog, your assembly must target version 1.1 (or higher) of the .NET Framework, or Silverlight version 2 (or higher). To instruct Dotfuscator and Analytics to use the built-in dialog as the ReportInfoSource, set the ReportInfoSourceElement value to "DefaultAction".

When using the built-in dialog on the .NET Framework, the dialog will be constructed and displayed using the Windows Forms API. This may have unintended consequences for console or service applications; it may be preferable to use a custom ReportInfoSource in these situations. If your assembly does not already reference the appropriate Windows Forms libraries, references will be added.

Using a Custom ReportInfoSource

The ExceptionTrackAttribute defines three properties for specifying a ReportInfoSource:

  • ReportInfoSourceElement. The ReportInfoSourceElement can be any of the values defined in the SourceElements enumeration: a field, a property, a method, or when using method-level exception tracking, a method argument. If the ReportInfoSourceElement is a method argument, it must correspond to a method parameter on the method to which the attribute is attached.
  • ReportInfoSourceOwner. If the ReportInfoSourceElement is a field, method, or property, ReportInfoSourceOwner must indicate the class that defines the field, method, or property.
  • ReportInfoSourceName. The ReportInfoSourceName should be set to the name of the field, method, property, or method argument of type IDictionary or IDictionary<string, string> that contains the user-specified report information at runtime.

There are three key-value pairs that may be included in the dictionary provided by the ReportInfoSource:

  • consent. This is a string representation of a boolean that indicates whether the user has explicitly opted-in or out of sending the current exception report message. This consent is independent of and overrides the global Runtime Intelligence opt-in setting.
  • comment. This is a custom comment that is optionally provided by the user. It can be used to solicit feedback from the user, such as what he or she was doing when the exception occurred.
  • contact. This is a contact point that is optionally provided by the user. Its content is not structured, and may for example contain an e-mail address, phone number, or username for a social networking website. The built-in dialog requests the user provide this as an e-mail address.

Any key-value pairs other than those described above will be ignored.

Collecting user-specified report information is optional. If the retrieved dictionary is null, does not contain a consent key, or the value for the consent key is null or does not parse to a boolean, the global Runtime Intelligence opt-in setting is respected. If the comment or contact keys are omitted, the resulting Runtime Intelligence message does not include this information.

Sample ExceptionTrack attribute usage with ReportInfoSource defined as a method called "GetDictionary":

Exception Track Attribute Usage with ReportInfoSource Copy Code
[ExceptionTrack(
   ReportInfoSourceElement = SourceElements.Method,
   ReportInfoSourceName = "GetDictionary"
)]
private void Foo() {
  ...
}

// Creates and populates a dictionary with user-specified report information
public IDictionary<string, string> GetDictionary() {
  Dictionary<string, string> dict = new Dictionary<string, string>();
  dict.Add("consent", "true");
  dict.Add("comment", "The Foo() method threw an exception.");
  dict.Add("contact", "foo@bar.com");
  return dict;
}


Introduction to Active Tamper Defense

Introduction to Active Tamper Defense

Glossary Item Box

Dotfuscator and Analytics CE provides a way for your applications to detect and optionally notify you if they have been tampered with since they were instrumented with tamper notification.

To detect tampering, place InsertTamperCheck attributes on one or more methods in the application that are always executed. When Dotfuscator and Analytics encounters an InsertTamperCheck attribute during its processing, it adds code that performs an assembly level integrity check at runtime. If the integrity check fails, it sends a tamper detected message to the Runtime Intelligence service. It can also call code that exits the application. InsertTamperCheck attributes are not required at runtime; therefore, Dotfuscator and Analytics strips them from the output application.

An application can contain any number of InsertTamperCheck attributes. In the event that an application has been tampered with, multiple tamper detected messages from the same application session will be sent with the same group ID.

Do not put this attribute on the same method containing the Setup Attribute. Methods with this attribute must be executed after the method containing the Setup Attribute.

In Dotfuscator and Analytics CE, InsertTamperCheck attributes may only be placed in assemblies that are EXEs. Dotfuscator and Analytics CE does not support tamper detection on library assemblies (DLLs).

In this section

Simulating Tampering

Supported .NET Application Types

See Also

Beyond Obfuscation
Simulating Tampering
Supported .NET Application Types


Simulating Tampering

Simulating Tampering

Glossary Item Box

Dotfuscator ships with a simple command line utility that ‘tampers’ with an assembly. It is called TamperTester.exe and is installed in the same folder as Dotfuscator itself.

Usage Copy Code
tampertester <file_name> [destination folder]

By running your Dotfuscator and Analytics assemblies through this utility, you can test that the tamper notification messages are being generated and sent as expected. You can also test any application code you have written to execute in response to tamper detection.


Supported .NET Application Types

Supported .NET Application Types

Glossary Item Box

Dotfuscator and Analytics CE can perform Tamper Notification processing for all .NET assemblies except for the following:

  • Managed C++ input assemblies containing native and managed code.
  • Multi-module input assemblies.
  • Input assemblies that target .NET 1.0
  • .NET Compact Framework assemblies.
  • Silverlight assemblies.
  • Any library assemblies.


Application Expiration

Application Expiration

Glossary Item Box

Shelf Life is an application inventory management function that allows you to embed expiration, or de-activation, and notification logic into an application via code injection. Dotfuscator and Analytics injects code that reacts to application expiration by exiting the application and/or sending a Runtime Intelligence message. This functionality is helpful with beta applications, as it enables applications to self regulate and it enforces aging and expiry policies. You can schedule your application’s expiration/de-activation for a specific date or a number of days after application instrumentation.

In this section

Shelf Life Activation Key Overview

See Also

Beyond Obfuscation
Shelf Life Activation Key Overview


Shelf Life Activation Key Overview

Shelf Life Activation Key Overview

Glossary Item Box

A Shelf Life Activation Key (SLAK) is a data file that is required to inject Shelf Life functionality into the appropriate locations within your application.

A Shelf Life Activation Key is issued by PreEmptive and provided to Dotfuscator and Analytics by the user during shelf life configuration. To obtain a Shelf Life Activation Key, contact PreEmptive Solutions. PreEmptive will issue you a data file containing the Shelf Life Activation Key that is to be stored on your Build Machine.

Once you obtain a Shelf Life Activation Key, you can add the Shelf Life Attribute to a method or group of methods. In the Analytics tab in the Attribute Editor: section, in the ActivationKeyFile field you must select the path to the Shelf Life Activation Key file, thereby activating Shelf Life within your application.


Free Runtime Intelligence Services Portal

Free Runtime Intelligence Services Portal

Glossary Item Box

Once your application has been instrumented, it will begin sending usage data to the Free Runtime Intelligence Services Portal where you may view a variety of reports generated from the accumulated data. The free Runtime Intelligence Services Portal provides for limited storage of usage data and has no minimum service level agreement and no user authentication; therefore, your data are considered public. For permanent data storage, additional summary and detail views of your data, and guaranteed SLAs, please contact us for an evaluation of our commercially available version.

The free Runtime Intelligence Services Portal provides the following reports:

  • Application Overview - provides a high level, visual representation of the Operating Systems, environments, frameworks, and stability of your applications.
  • Application Scorecard - provides high level textual representation of the usage of your applications broken down by the version information embedded in your applications.
  • Feature Overview - provides a visual representation of the feature usage data gathered from your applications.
  • Feature Scorecard - provides a high level textual representation of the feature usage gathered from your applications.

To begin viewing how your users are using your applications please go to http://free.runtimeintelligence.com and enter the CompanyKey that you used when instrumenting your application as the user name.

More detailed information about the reports is available from the Help topics located on the free Runtime Intelligence Services Portal.


Empty Index Entry

Glossary Item Box

Empty Index Entry

The index entry you selected has no target topics associated with it.

If you have chosen a parent entry, please select a child entry.


Topic Not Found

Glossary Item Box

Topic Not Found

The link you just clicked was not able to connect to the target page.

Some possible reasons and remedies are as follows:

Reason | Remedy
Destination topic is not part of the area you specified in the Filtered by field. | Either select another filter or select (no filter).
The URL of the destination topic is incorrect or has changed. | Use the index or the search function instead.
Problems with the help installation. | Rerun Setup for the product this help is related to and select the 'Repair' option.

Additional help is available for filters, search, and the index.

Click Back to return to the page you were on.

The target parameters are:

Keyword:
Index Moniker:
URL:


Cover

Glossary Item Box

PreEmptive Dotfuscator and Analytics
Community Edition Users' Guide

Version 5.5

© 2002-2012 by PreEmptive Solutions, LLC

All rights reserved.

Manual Version 5.5-092911

www.preemptive.com

TRADEMARKS

Dotfuscator, Overload-Induction, the PreEmptive Solutions logo, and the Dotfuscator logo are trademarks of PreEmptive Solutions, LLC

.NET™ , MSIL™, and Visual Studio™ are trademarks of Microsoft, Inc.

All other trademarks are property of their respective owners.

THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS PUBLICATION COULD CONTAIN TYPOGRAPHIC ERRORS AND/OR TECHNICAL INACCURACIES. UPDATES AND MODIFICATIONS MAY BE MADE TO THIS DOCUMENT AND/OR SUPPORTING SOFTWARE AT ANY TIME.

PreEmptive Solutions, LLC has intellectual property rights relating to technology embodied in this product. In particular, and without limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and/or other countries.

This product is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product may be reproduced in any form by any means without prior written authorization of PreEmptive Solutions, LLC.

©2012. All Rights Reserved.


a
about
after
against
all
along
also
although
am
among
an
and
are
as
at
be
became
because
been
being
between
but
by
can
caution
come
could
details
did
do
does
doing
done
during
each
early
far
finally
for
found
from
had
has
have
he
her
here
his
how
however
I
if
in
include
including
information
into
is
it
its
late
later
made
many
may
me
med
might
more
most
near
no
non
none
nor
not
note
of
off
on
only
or
other
over
saw
see
seen
several
she
since
so
some
such
than
that
the
their
them
then
there
these
they
this
those
through
tip
to
too
under
until
up
us
use
very
warning
was
we
were
when
where
which
while
who
with
you