Dotfuscator's Instrumentation features add pre-built application usage, feature usage, and exception tracking to your application, without requiring you to write any additional code. This process is known as code injection. An application that undergoes this process is known as an injected application. At runtime, the code injected into the application will transmit telemetry to a PreEmptive Analytics endpoint.
The development workflow for injecting instrumentation code into an application is similar to that for obfuscating an assembly. Both require configuring Dotfuscator to work with the specific assemblies, and both produce a set of output assemblies that match the input assemblies. The only difference is the specific configuration elements that are used. The output assemblies will contain all the run-time code necessary to collect and deliver the telemetry data.
The diagram below illustrates the workflow from the developer's point of view.
When using code injection, other Dotfuscator features are available. The injected runtime code is annotated with obfuscation attributes so user configuration (beyond what is necessary for the input assemblies and the details of your application's code) is not required to perform renaming, removal, or other transforms on the code Dotfuscator injects in to your application.
- The listing of Instrumentation Attributes
- Instrumentation Configuration in the GUI
- Instrumentation Configuration via In-code Attributes
Supported Application Types
Dotfuscator Community Edition (Dotfuscator CE) can perform instrumentation processing for all .NET assemblies except for the following:
- Assemblies that target .NET 1.0
- Managed C++ assemblies containing native and managed code
- Multi-module assemblies
- Xamarin assemblies
- Unity assemblies
- .NET Core assemblies
When a sufficient number of messages have been generated, and the injected application is not under high load, the messages will be packaged into an HTTP POST body, called an envelope, which is then transmitted to the configured endpoint.
The process of generating these messages and sending them to an endpoint is called telemetry. The messages themselves may also be called telemetry.
End User Opt-in
Injected applications can provide the end user an option to enable or disable telemetry. The injected Instrumentation code will honor this option, if it is provided by the application code, during Instrumentation setup.
The preference is communicated via a source defined with the
SetupAttribute called OptInSource.
The source defines a
bool value which is
true if the user opts-in and
false if the user opts-out.
If no source is provided for a
SetupAttribute, the injected code will act as if the user opted-in.
For instance, consider the following attribute and its properties:
At runtime, when
HelloWorld.Hello.Main is called, the injected code will first call the static method
If the result of the call is
true, messages will be generated and transmitted during the application's run.
If the result of the call is
false, most regular messages will not be generated.
There are a couple of cases where messages will still be generated and transmitted, regardless of the opt-in setting:
Sign-of-life messages ignore the telemetry opt-in setting.
Check Telemetry ignores the telemetry opt-in setting.
Personally Identifiable Information
In Dotfuscator Community Edition, personally identifiable information (PII) is omitted from Instrumentation tracking. Including PII in collected telemetry data is a feature exclusive to Dotfuscator Professional Edition.
If an injected application cannot connect to the specified endpoint at runtime, generated messages will be lost. Dotfuscator Professional Edition can inject additional code to handle network outages by saving the generated messages to disk until the endpoint is available.
PreEmptive Solutions offers a number of endpoints to which your application can send messages.
Note: Transmissions from an application injected by Dotfuscator Community Edition will not be encrypted. Encrypted transmission via SSL is a feature exclusive to Dotfuscator Professional Edition.
PreEmptive Analytics Workbench
PreEmptive Analytics Workbench accepts, processes, transforms, and aggregates telemetry for display in a web browser. It is highly configurable and customizable so that it can provide role-based, real-time visibility into application usage, adoption, user behavior, and software quality - saving you time and money.
To learn more, please read about PreEmptive Analytics Workbench on our website.
PreEmptive Solutions hosts a publicly-accessible Analytics Workbench, called the Community Workbench. This allows you to monitor how many times your application is run, which features are being used, and how stable it is, for free.
Note: The Community Workbench comes with no guarantees or service level agreements. All data received is visible to all users, without authentication. Certain features of the Community Workbench are restricted, compared to the commercial product.
To configure your application to send to the Community Workbench:
- Use the CompanyKey
- Use the StaticEndpoint
To view your data:
- Navigate to http://community.analytics.preemptive.com/ in a compatible browser.
- From the Date Range drop-down, select the time period to view.
- From the Applications drop-down, select your application.
The Analytics API contains code related to sending messages, managing offline storage, and general instrumentation setup.
There are two ways that this API can be accessible from your application's injected code:
Dotfuscator can inject the Analytics API's runtime code into one of the input assemblies.
- In this scenario, you do not need to separately distribute the PreEmptive Analytics DLL.
Dotfuscator can output the Analytics API's runtime code in a separate assembly and add the appropriate assembly references to the input assemblies.
- This method is only available in Dotfuscator Professional Edition.
Dotfuscator still needs to inject code into one of the input assemblies in order to use the Analytics API. Dotfuscator performs a dependency analysis of the input assemblies in order to choose the best one. It chooses in such a way as to minimize new dependencies among input assemblies; however, adding new dependencies is unavoidable in some cases.
You can override the assembly that this code will be injected into by adding a Project Property with the name "accesspoint" and setting its value to the name of the assembly where the code will be inserted. You can add this Project Property on the Build Settings screen's Project Properties tab.