PreEmptive Protection - Dotfuscator
Community Edition User Guide

Instrumentation Attributes

This page lists the attributes that control the injection of Instrumentation features.

All of the following attributes are defined in the PreEmptive.Attributes namespace, which for brevity will be omitted from the titles of the sections below.

Some properties are only recognized by Dotfuscator Professional Edition and are thus not listed in this documentation.

Note that injection in general is controlled by the Enable injection global option. If this option is disabled, no code will be injected despite any attributes.

Referencing the Attributes

Dotfuscator ships with a reference assembly that defines the Instrumentation attributes. The assembly is named PreEmptive.Attributes.dll and is located in the same directory where Dotfuscator is installed.

The easiest way to find the path to this assembly is to:

  1. Open a Dotfuscator command prompt.

  2. Run the command where PreEmptive.Attributes.dll and copy the result.

You can then add a reference to this assembly to your project. Note that the assembly has no dependencies besides the framework itself, so it can be copied to a different location if desired. While injecting code, Dotfuscator by default removes references to this DLL; therefore, the DLL is not required at application runtime and does not need to be distributed with the application. Check the value of the Strip injection attributes option to ensure that it still has this default setting.

Attribute Listing

This section lists the attributes that Dotfuscator recognizes to configure the injection of Instrumentation features.

Attributes and Properties that are only recognized by Professional Edition are omitted.

BusinessAttribute

Identifies the company that owns the assembly being injected. Required for Instrumentation Telemetry and Check Telemetry.

  • Applies to: Assembly

  • Prerequisites: None

  • Properties

    • CompanyKey: Required. A GUID string that uniquely identifies the company. Typically, this is provided by PreEmptive Solutions, so that data of particular companies may be routed correctly. If you are using the Community Workbench, then this value should be 7d2b02e0-064d-49a0-bc1b-4be4381c62d3 (the default value in the GUI).

    • CompanyName: Recommended. A string identifying the company, used for easier human readability when data is aggregated in an Analytics server.

ApplicationAttribute

Identifies the application of the assembly being injected. Required for Instrumentation Telemetry and Check Telemetry.

  • Applies to: Assembly

  • Prerequisites: None

  • Properties

    • Guid: Required. A GUID string that uniquely identifies the application within the company and that should not change over the lifetime of the application. The application ID allows endpoints to aggregate application data across name and version number changes.

    • Name: Recommended. A string identifying the application, used for easier human readability when data is aggregated in an Analytics server. If blank, the filename of the assembly will be used instead (if possible to obtain via reflection at runtime).

    • Version: Optional. A string identifying the version of the application, for filtering data aggregated in an Analytics server. If blank, the assembly's version will be used instead (if possible to obtain via reflection at runtime).

    • ApplicationType: Optional. A string identifying the type of the application, for filtering data aggregated in an Analytics server. If blank, the assembly's type (e.g., .exe) will be used instead (if possible to obtain via reflection at runtime).

BinaryAttribute

Identifies the assembly being injected. If present on an assembly, it is used for reporting the originating assembly of Instrumentation Telemetry and Check Telemetry.

  • Applies to: Assembly

  • Prerequisites: None

  • Properties

    • Guid: Required. A GUID string that uniquely identifies the assembly within the application.

SetupAttribute

Indicates that Dotfuscator should inject start-of-session code at the start of the annotated method. The injected code sets up Instrumentation and generates a session start message.

A method with a SetupAttribute must be called at runtime before any Telemetry can be transmitted, so it should be placed as close as possible to the normal application startup logic.

This attribute specifies the destination endpoint of Telemetry reporting via its StaticEndpoint property. Additionally, this attribute can implement user opt-in/opt-out behavior.

  • Applies to: Method

  • Prerequisites

  • Properties

    • StaticEndpoint: Required. The URL, without the protocol, to which Instrumentation Telemetry and Check Telemetry should be transmitted. Defaults to the URL of the free Analytics endpoint.

    • OptInSourceElement: Specifies a source indicating the user's intent to opt-in.

      • May be a bool method argument, field, or property; or a method with the signature bool().

      • If "None" (default), the user is always opted-in.

    • OptInSourceName: Specifies the name of that source.

    • OptInSourceOwner: Specifies the declaring type of that source.

TeardownAttribute

Indicates that Dotfuscator should inject end-of-session code into the annotated method's exit points. The injected code generates a session stop message, transmits any queued messages, and shuts down Instrumentation.

This attribute should be used in "normal" exit conditions, preferably as close as possible to the point at which the application stops. The annotated 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. Because the code indicated by this attribute is injected at the method's exit points, it may be placed on the same method as the SetupAttribute.

FeatureAttribute

Indicates that Dotfuscator should inject feature tracking code into the annotated method. The injected code will generate a feature message.

Note: Community Edition only supports up to 10 uses of the FeatureAttribute in a project. Professional Edition does not have this limitation.

  • Applies to: Method (multiple attributes on a single method permitted)

  • Prerequisites

  • Properties:

    • FeatureEventType: Required. Specifies the type of feature message to send. Defaults to "Tick".

      • Tick: The entry point of this method indicates a Feature Tick.

      • Start: The entry point of this method indicates the beginning of a Start/Stop Feature.

      • Stop: The exit points of this method indicate the end of a Start/Stop Feature.

    • Name: Required. The name of the feature.

ExceptionTrackAttribute

Indicates that Dotfuscator should inject code to report on unhandled exceptions occurring within the specified assembly or method.

When applied to an assembly, Dotfuscator injects handlers for the AppDomain.UnhandledException event and similar events. If invoked, these handlers generate a fault message.

When applied to a method, Dotfuscator injects code that catches any exception that would leave the method unhandled, generates a fault message, and then re-throws the exception with the original stack trace.

  • Applies to: Assembly (.exe only in Community Edition) or Method

  • Prerequisites

    • Build-time: A SetupAttribute on some method in some input assembly.

    • Runtime:

      • Instrumentation is set up (via a call to a method annotated with SetupAttribute)

      • The user did not opt-out. Depending on the Report Info gathered, the user may override their earlier setup-time opt-in preference for the exception report.

  • Properties:

    • ReportInfoSourceElement: Specifies a source containing user-specified information.

      • May be a IDictionary<string,string> or IDictionary method argument, field, or property; or a method with the signature IDictionary<string,string>() or IDictionary(). See Application-provided Report Information for what key-value pairs may be included.

      • If "DefaultAction", the injected code will use Dotfuscator's generic exception dialog.

      • If "None" (default), the injected code will obey the opt-in preference that was specified at setup-time.

    • ReportInfoSourceName: Specifies the name of that source.

    • ReportInfoSourceOwner: Specifies the declaring type of that source.

    • PrivacyPolicyUri: A URL to a privacy policy covering the transmission of exception reports, to be used in Dotfuscator's generic exception dialog.

      • If ReportInfoSourceElement is not "DefaultAction", this property is ignored.

SignOfLifeAttribute

Indicates that Dotfuscator should inject code to report that the application has been executed. The injected code generates a sign-of-life message.

A Shelf Life Activation Key is required to use this attribute.

Unlike the injected code of other Instrumentation attributes, this attribute's injected code does not honor the user's opt-in preference.

Its deprecated name is "InsertSignOfLifeAttribute".

Dotfuscator Version 5.32.0.6134. Copyright © 2017 PreEmptive Solutions, LLC