PreEmptive Protection - Dotfuscator 4.31
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.

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.

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.

    • 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: The URL, without the protocol, to which Instrumentation Telemetry and Check Telemetry should be transmitted. Defaults to the URL of the PreEmptive Analytics endpoint. Required if EndpointSource is not specified.

    • EndpointSourceElement: Specifies a source providing the URL, without the protocol, to which Instrumentation Telemetry and Check Telemetry should be transmitted. Required if StaticEndpoint is not specified.

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

      • If "ApplicationSetting", may be a setting defined in the standard .NET configuration in desktop and web applications.

      • If "None" (default), the URL will be obtained from StaticEndpoint.

      • "DefaultAction" is simply an alias for "None".

    • EndpointSourceName: Specifies the name (or key in the case of "ApplicationSetting") of that source.

    • EndpointSourceOwner: Specifies the declaring type of that source.

    • UseSSL: Specifies whether to use the HTTPS protocol (when set to "True") or the HTTP protocol (when set to "False") when sending telemetry to a PreEmptive Analytics Endpoint. Defaults to "True".

    • 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.

    • OmitPII: Specifies whether to exclude personally identifiable information from telemetry. Defaults to "False".

    • InstanceIdSourceElement: Specifies a source which tells the injected code what Application Instance ID to include in generated messages.

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

      • If "None", no application instance IDs will be included in generated messages.

    • InstanceIdSourceName: Specifies the name of that source.

    • InstanceIdSourceOwner: Specifies the declaring type of that source.

    • OfflineStateSourceElement: Specifies a source which tells the injected code if the application currently lacks network connectivity and should therefore use Offline Storage for generated messages.

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

      • If "DefaultAction" (default), the injected application will support Offline Storage and Dotfuscator will inject default connectivity detection code.

      • If "None", offline storage will not be used in the injected application.

    • OfflineStateSourceName: Specifies the name of that source.

    • OfflineStateSourceOwner: Specifies the declaring type of that source.

    • OfflineStorageResultSinkElement: Specifies a sink which the injected code uses to report true if the most recent attempt to save generated messages to Offline Storage was successful and false if it was not.

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

      • If "None" (default), the injected application will not report the result of attempting to save to Offline Storage.

      • If "DefaultAction", the injected application will immediately exit if an attempt to save messages to Offline Storage fails.

    • OfflineStorageResultSinkName: Specifies the name of that sink.

    • OfflineStorageResultSinkOwner: Specifies the declaring type of that sink.

    • ExtendedKeyMethodArguments: Specifies which (if any) arguments of the annotated method should be sent as user-defined data with the session start message. See Automatically Sending Method Parameters as Extended Keys for more detail on how to configure this property.

    • ExtendedKeySourceElement: Specifies a source which the injected code should use to obtain user-defined data to send with the session start message.

      • May be an IDictionary or IDictionary<string, string> field, property, or method argument; or a method with signature IDictionary() or IDictionary<string, string>().

      • If "None" (default), a source is not used to obtain user-defined data to send with the session start message.

    • ExtendedKeySourceName: Specifies the name of that source.

    • ExtendedKeySourceOwner: 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.

  • Applies to: Method

  • Prerequisites:

  • Properties:

    • ExtendedKeyMethodArguments: Specifies which (if any) arguments of the annotated method should be sent as user-defined data with the session stop message. See Automatically Sending Method Parameters as Extended Keys for more detail on how to configure this property.

    • ExtendedKeySourceElement: Specifies a source which the injected code should use to obtain user-defined data to send with the session stop message.

      • May be an IDictionary or IDictionary<string, string> field, property, or method argument; or a method with signature IDictionary() or IDictionary<string, string>().

      • If "None" (default), a source is not used to obtain user-defined data to send with the session stop message.

    • ExtendedKeySourceName: Specifies the name of that source.

    • ExtendedKeySourceOwner: Specifies the declaring type of that source.

FeatureAttribute

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

  • 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.

    • ExtendedKeyMethodArguments: Specifies which (if any) arguments of the annotated method should be sent as user-defined data with the feature message. See Automatically Sending Method Parameters as Extended Keys for more detail on how to configure this property.

    • ExtendedKeySourceElement: Specifies a source which the injected code should use to obtain user-defined data to send with the feature message.

      • May be an IDictionary or IDictionary<string, string> field, property, or method argument; or a method with signature IDictionary() or IDictionary<string, string>().

      • If "None" (default), a source is not used to obtain user-defined data to send with the feature message.

    • ExtendedKeySourceName: Specifies the name of that source.

    • ExtendedKeySourceOwner: Specifies the declaring type of that source.

ExceptionTrackAttribute

Indicates that Dotfuscator should inject code to detect and optionally report exceptions occurring within the specified assembly or method.

  • Applies to: Assembly 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 report 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.
    • ExceptionNotificationSinkElement: Specifies a sink the injected code should use to inform the application of the encountered Exception.

      • May be a System.Exception field or property; or a method, delegate field, or delegate method argument with signature void(System.Exception).

      • If "None" (default), the application is not notified of the encountered excpetion. This does not affect whether or not exception telemetry is sent.

    • ExceptionNotificationSinkName: Specifies the name of that sink.

    • ExceptionNotificationSinkOwner: Specifies the declaring type of that sink.

    • ExceptionSourceElement: Specifies a source from which injected code can obtain Exceptions as they occur. Must be set to "DefaultAction" if this ExceptionTrackAttribute annotates an assembly.

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

      • If "DefaultAction" (default), Dotfuscator will inject code to automatically detect exceptions.

      • "None" is simply an alias for "DefaultAction".

    • ExceptionSourceName: Specifies the name of that source.

    • ExceptionSourceOwner: Specifies the declaring type of that source.

    • ExceptionType: Specifies what kind of exception occurrences should be detected. May be one of:

      • "Unhandled" (default)

      • "Caught"

      • "Thrown"

    • SendReport: Specifies whether to send exception telemetry (which includes the optional exception report information) when an exception is encountered. Defaults to "True".

    • ExtendedKeyMethodArguments: Specifies which (if any) arguments of the annotated method should be sent as user-defined data with the fault message. See Automatically Sending Method Parameters as Extended Keys for more detail on how to configure this property.

    • ExtendedKeySourceElement: Specifies a source which the injected code should use to obtain user-defined data to send with the fault message.

      • May be an IDictionary or IDictionary<string, string> field, property, or method argument; or a method with signature IDictionary() or IDictionary<string, string>().

      • If "None" (default), a source is not used to obtain user-defined data to send with the fault message.

    • ExtendedKeySourceName: Specifies the name of that source.

    • ExtendedKeySourceOwner: Specifies the declaring type of that source.

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".

  • Applies to: Method

  • Prerequisites:

  • Properties::

    • ActivationKeyFile: Required. The path to a valid Shelf Life Activation Key file at build time.

    • ExtendedKeyMethodArguments: Specifies which (if any) arguments of the annotated method should be sent as user-defined data with the sign-of-life message. See Automatically Sending Method Parameters as Extended Keys for more detail on how to configure this property.

    • ExtendedKeySourceElement: Specifies a source which the injected code should use to obtain user-defined data to send with the sign-of-life message.

      • May be an IDictionary or IDictionary<string, string> field, property, or method argument; or a method with signature IDictionary() or IDictionary<string, string>().

      • If "None" (default), a source is not used to obtain user-defined data to send with the sign-of-life message.

    • ExtendedKeySourceName: Specifies the name of that source.

    • ExtendedKeySourceOwner: Specifies the declaring type of that source.

PerformanceProbe

Indicates that Dotfuscator should inject code to obtain and report application performance-related information. See System Metrics for more detail.

  • Applies to: Method

  • Prerequisites:

  • Properties::

    • Name: The name of this instance of the PerformanceProbeAttribute. This can be used to distinguish between performance measurements taken at different points during execution.

    • InjectionPoint: Where in the method to inject the generated code. Defaults to "Beginning".

      • "Beginning": Inject performance metrics-gathering code at the beginning of the method.

      • "End": Inject performance metrics-gathering code at the end of the method.

    • ExtendedKeyMethodArguments: Specifies which (if any) arguments of the annotated method should be sent as user-defined data with the performance metrics. See Automatically Sending Method Parameters as Extended Keys for more detail on how to configure this property.

    • ExtendedKeySourceElement: Specifies a source which the injected code should use to obtain user-defined data to send with the performance metrics.

      • May be an IDictionary or IDictionary<string, string> field, property, or method argument; or a method with signature IDictionary() or IDictionary<string, string>().

      • If "None" (default), a source is not used to obtain user-defined data to send with the performance metrics.

    • ExtendedKeySourceName: Specifies the name of that source.

    • ExtendedKeySourceOwner: Specifies the declaring type of that source.

SystemProfile

Indicates that Dotfuscator should inject code to obtain and report information about the system on which the application is running. See System Metrics for more detail.

  • Applies to: Method

  • Prerequisites:

  • Properties::

    • ExtendedKeyMethodArguments: Specifies which (if any) arguments of the annotated method should be sent as user-defined data with the system metrics. See Automatically Sending Method Parameters as Extended Keys for more detail on how to configure this property.

    • ExtendedKeySourceElement: Specifies a source which the injected code should use to obtain user-defined data to send with the system metrics.

      • May be an IDictionary or IDictionary<string, string> field, property, or method argument; or a method with signature IDictionary() or IDictionary<string, string>().

      • If "None" (default), a source is not used to obtain user-defined data to send with the system metrics.

    • ExtendedKeySourceName: Specifies the name of that source.

    • ExtendedKeySourceOwner: Specifies the declaring type of that source.

Dotfuscator Version 4.31.0.6091. Copyright © 2017 PreEmptive Solutions, LLC