Injection Configuration
The Injection screen is used to configure Dotfuscator code injection which includes Checks and Instrumentation features.
You can access this screen in Dotfuscator Community's navigation list by selecting Injection. This screen contains four tabs: an informational "Getting Started" tab, a tab each for configuring Checks and Instrumentation, and a general "Options" tab.
Getting Started Tab
This tab provides general information about Checks and Instrumentation.
Instrumentation Tab
The Instrumentation tab allows you to add, edit, and review the attributes that configure Dotfuscator's Instrumentation features.
This tab displays a tree view of the input assemblies, including the instrumentation attributes (which can be edited) that decorate each assembly or method.
Note: For new configs, the default setting for instrumentation injection is enabled. However, telemetry is disabled by default. See the Options Tab section for how to change these settings.
The tab is divided into two sections. The left side presents the structure of your input assemblies in a code tree, including the instrumentation attributes that annotate each assembly or method. Selecting one of these attributes will display the attribute's properties on the right side of the tab, allowing for the attribute's configuration.
Defining Instrumentation Attributes from the GUI
In addition to specifying attributes in your source code, you may also add attributes to your config from the Dotfuscator Community GUI. These attributes will be saved in the Dotfuscator config file, not in your source code. These attributes are known as extended attributes.
To add an extended attribute:
In the code tree, select the assembly or method that you wish to annotate.
Right-click the selected item and choose Add Attribute.
Select the appropriate attribute from the list of available attributes and click OK.
The extended attribute is added as a child of the item, listed in blue text. Expand the item's subtree and select the newly-added attribute.
The right side of the tab now displays the properties of the attribute. You may edit properties that are recognized by Dotfuscator Community; properties exclusive to Dotfuscator Professional are grayed out.
For instance, a BusinessAttribute
can be added to an assembly by right-clicking the assembly in the left-hand side tree view, selecting Add Attribute, and choosing PreEmptive.Analytics.BusinessAttribute
.
The attribute's CompanyName property can be configured by selecting the attribute in the tree view, then modifying the CompanyName entry in the right-hand side property view.
To edit an extended attribute:
Select the attribute within the code tree on the left side of the screen.
The Attribute properties section on the right side of the screen can be used to edit the selected attribute's various properties. See here for details on how to edit these properties.
You can remove an extended attribute from the config by right-clicking on the attribute in the code tree and choosing Remove Attribute.
Working with In-Code Instrumentation Attributes
The Instrumentation tab also displays instrumentation attributes specified in your source code. When working with these in-code attributes, there are a few things to keep in mind:
In-code attributes will be displayed in the code tree in black text. Extended attributes will be displayed in blue text.
You can override an in-code attribute with an extended attribute. Dotfuscator will then ignore the in-code attribute and not display it in the code tree. The extended attribute will be used instead. Overriding happens when either of the following occurs:
You edit the properties of an in-code attribute via the GUI. Because Dotfuscator does not access the source code, this causes an extended attribute to be created with the changed values.
You add an extended attribute to an assembly or method that already has an in-code attribute of the same type.
If you remove an extended attribute that was overriding an in-code attribute, the in-code attribute will once again take effect.
You cannot remove in-code attributes using the Dotfuscator Community GUI. If you wish to remove such an attribute, you must remove it from the source code itself.
Checks Tab
The Checks tab allows you to add, edit, and remove Checks.
This tab displays a table listing all of the Checks that are configured in the current Dotfuscator config file and any Checks that may be configured via custom attributes in the input assemblies.
Table Columns:
The first column only shows icons if you are using in-code attributes to define Checks.
The Check Type column indicates which of the possible Check Types this Check is.
The Description column describes the locations in the input assemblies that have this Check.
- Method signatures in this column are abbreviated, and only the common namespace is displayed if there is more than one location for the check. To see a full, unabbreviated listing of these method signatures, you can look at the tool tip for the Check's description.
Defining Checks in the GUI
To add a Check:
Click the button that corresponds to the type of check you want to create: Add Debugging Check..., Add Tamper Check..., Add Shelf Life Check..., or Add Root Check.... An editor for the new Check will open.
In the grid on the left side of the editor, configure the properties for your Check. See the section on Property Editing for more detailed instructions.
In the code tree on the right side of the editor, select the Locations in your input assemblies that you wish to be injected with this Check. Each location can only be associated with one Check of a particular check type.
Click OK to save. A new row in the table will appear for the Check.
You can edit a Check by highlighting the Check in the table and then clicking the Edit button. The Check's editor will open, and you can edit its properties as well as change its locations.
You can remove a Check from the config by highlighting the Check in the table and then clicking the Remove button.
Working with Checks Defined by In-Code Attributes
The Checks tab also displays check attributes specified in your source code. When working with these in-code attributes, there are a few things to keep in mind:
You can override an in-code attribute-defined Check with a user interface-defined Check. Dotfuscator will then ignore the in-code attribute and will not represent it with its own row in the table of Checks. The user interface-defined Check will be used instead. Overriding happens when either of the following occurs:
You edit the properties of or add a location to an in-code attribute-defined Check via the GUI. Because Dotfuscator does not access the source code, this causes a user interface-defined Check to be created with the changed values and/or additional locations.
You add a location to a user interface-defined Check such that the location already has an in-code attribute of the same Check Type.
If you remove a user interface-defined Check that was overriding an in-code attribute, the in-code attribute will once again take effect.
You cannot remove in-code attributes using the Dotfuscator UI. If you wish to remove a Check defined by an in-code attribute, you must remove it from the source code itself.
The first column of the Checks table will display icons if you are using in-code attributes to configure Checks:
No icon is displayed if the Check was added from the user interface and does not override a Check defined by an in-code attribute.
is displayed if the Check is fully specified by an in-code attribute.
is displayed if the user interface-defined Check overrides at least one in-code attribute.
Editing Properties
Modifying properties of instrumentation attributes and checks is usually straightforward; the supported fields will accept free text (for most string properties), provide a drop-down list of supported values, or provide a date picker.
However, some properties, when selected, will also display a "..." icon. Clicking it will display an additional editor for populating the field. These editors are described in the following subsections.
In addition, there are property listing documentation pages that explain what each of the specific properties means and what behavior it controls.
Endpoint Selection Dialog
On the StaticEndpoint property of a SetupAttribute
, clicking the "..." icon will open the following dialog:
From here, you can choose one of PreEmptive Solutions' predefined endpoints or specify your own URL.
Owner Type Selection Dialog
An Owner property of sources and sinks, such as OptInSourceOwner, specifies a type within the config. On these Owner properties, clicking the "..." icon will open the following dialog:
From here, you can choose which type the property will reference.
GUID Generator
On various Guid properties and the CompanyKey property of a BusinessAttribute
, clicking the "..." icon will generate a new GUID for the property.
Browse Dialog
On the ActivationKeyFile property of a ShelfLifeCheckAttribute
or a SignOfLifeAttribute
, clicking the "..." icon will allow you to browse to and select a Shelf Life Activation Key.
Options Tab
This tab allows you to configure the injection process at the config level.
There are several options available:
Enable injection: Acts as a master switch for the entire injection process. If checked, injection will be performed as specified by the injection settings configured in Dotfuscator as well as by all instrumentation attributes and check attributes contained with the input assemblies. If unchecked, no injection of any kind will occur.
This setting can also be controlled by right-clicking on the Injection line in the navigation list, and checking or unchecking Enable.
Even if injection is disabled, any in-code Check or Instrumentation attributes will be removed from the processed assemblies. This behavior is controlled by each input assembly's Strip injection attributes option, which cannot be disabled in Dotfuscator Community.
Send application analytics messages: Enables the injected app to transmit Instrumentation Telemetry.
This setting must be enabled in order to track sessions, features, and exceptions.
If you want to use Instrumentation attributes only for the purpose of setting up Check Telemetry, you may disable this option.
Send debug check messages: Enables the injected app to transmit Check Telemetry from Debugging Checks.
- If disabled, Debugging Checks and their associated Check Actions still occur.
Send shelf life notification messages: Enables the injected app to transmit Check Telemetry from Shelf Life Checks.
If disabled, Shelf Life Checks and configured exit behaviors still occur.
This option also controls the message sent by the
SignOfLifeAttribute
.
Send tamper check messages: Enables the injected app to transmit Check Telemetry from Tamper Checks.
- If disabled, Tamper Checks and their associated Check Actions still occur.
Embed the analytics library in an output assembly: Causes the Analytics API code to be injected into an existing input assembly, rather than being put into a separate assembly. For more details about the behavior this option controls, see the Analytics API section of the Instrumentation Overview.
- Cannot be disabled in Dotfuscator Community.
Analytics Version: Determines the internal Analytics API used for injection. Normally, you should not have to adjust this setting from the default provided, unless directed by PreEmptive Solutions support.