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 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:
Open a Dotfuscator command prompt.
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 Dotfuscator Professional 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.
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
For Instrumentation set up:
Build-time:
A
BusinessAttribute
on the method's assembly.An
ApplicationAttribute
on the method's assembly.
Runtime: None.
For session start message generation:
All of the above, and
Build-time: Send application analytics messages global option enabled.
Runtime: The user did not opt-out.
Properties
StaticEndpoint: Required. The URL, without the protocol, to which Instrumentation Telemetry and Check Telemetry should be transmitted.
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 signaturebool()
.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
.
Applies to: Method
Prerequisites
For Instrumentation shut down:
Build-time:
A
BusinessAttribute
on the method's assembly.An
ApplicationAttribute
on the method's assembly.
Runtime: Instrumentation is set up (via a call to a method annotated with
SetupAttribute
).
For session stop message generation:
All of the above, and
Build-time: Send application analytics messages global option enabled.
Runtime: The user did not opt-out at setup time.
Properties: None in Dotfuscator Community.
FeatureAttribute
Indicates that Dotfuscator should inject feature tracking code into the annotated method. The injected code will generate a feature message.
Note: Dotfuscator Community only supports up to 10 uses of the
FeatureAttribute
in a config. Dotfuscator Professional does not have this limitation.
Applies to: Method (multiple attributes on a single method permitted)
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 at setup time.
Properties:
FeatureEventType: Required. Specifies the type of feature message to send. Defaults to "Tick".
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 Dotfuscator Community) or MethodPrerequisites
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>
orIDictionary
method argument, field, or property; or a method with the signatureIDictionary<string,string>()
orIDictionary()
. 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".
Applies to: Method
Prerequisites
Build-time:
Send shelf life notification messages global option enabled.
A
SetupAttribute
on some method in some input assembly
Runtime: Instrumentation is set up (via a call to a method annotated with
SetupAttribute
).
Properties:
- ActivationKeyFile: Required. The path to a valid Shelf Life Activation Key file at build time.