Instrumentation Attributes Reference
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 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 command prompt.
Run the command
where PreEmptive.Attributes.dll
and copy the result.
Note: Dotfuscator's installer automatically adds Dotfuscator to the PATH.
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:
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 Analytics Messages option enabled.
Runtime: The user did not opt-out.
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 signaturestring()
.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 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.
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 signaturestring()
.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 signaturebool()
.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 andfalse
if it was not.May be a
bool
field or property; or a method, delegate field, or delegate method argument with signaturevoid(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
orIDictionary<string, string>
field, property, or method argument; or a method with signatureIDictionary()
orIDictionary<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:
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 Analytics Messages option enabled.
Runtime: The user did not opt-out at setup time.
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
orIDictionary<string, string>
field, property, or method argument; or a method with signatureIDictionary()
orIDictionary<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:
Build-time:
Send Analytics Messages 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
)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.
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
orIDictionary<string, string>
field, property, or method argument; or a method with signatureIDictionary()
orIDictionary<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>
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.
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 signaturevoid(System.Exception)
.If "None" (default), the application is not notified of the encountered exception. 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 signatureSystem.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
orIDictionary<string, string>
field, property, or method argument; or a method with signatureIDictionary()
orIDictionary<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:
Build-time:
Send Shelf Life Messages 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.
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
orIDictionary<string, string>
field, property, or method argument; or a method with signatureIDictionary()
orIDictionary<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:
Build-time:
Send Analytics Messages 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
).The user did not opt-out.
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
orIDictionary<string, string>
field, property, or method argument; or a method with signatureIDictionary()
orIDictionary<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:
Build-time:
Send Analytics Messages 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
).The user did not opt-out.
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
orIDictionary<string, string>
field, property, or method argument; or a method with signatureIDictionary()
orIDictionary<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.