Exception Tracking
Exception Tracking is an Instrumentation feature that allows an injected application to report when caught, thrown, or unhandled exceptions occur. The injected application can also be configured to respond to the occurrence of such exceptions.
Exception Tracking can be configured at the method level to detect exceptions that occur within the method and at the assembly level to detect exceptions that occur anywhere in the assembly.
Configuration
To track exceptions:
Using either in-code attributes or extended attributes, add
ExceptionTrackAttribute
s to appropriate assemblies and methods.Configure the properties of these attributes appropriately.
Build your Dotfuscator config.
The output assemblies will now contain injected code for Exception Tracking.
Supported Application Types
Exception Tracking can be used on methods within all assemblies supported by instrumentation. Exception Tracking can also be used on those assemblies themselves except for the following cases:
- XNA assemblies
Note that if you are injecting the Generic Exception Dialog, then additional restrictions apply.
Exception Detection
By default, Dotfuscator will inject code to automatically detect exceptions in the following ways (depending on the configured ExceptionType:
Caught: Dotfuscator will inject code that tracks exceptions right after they enter a
catch
block.Thrown: Dotfuscator will inject code that tracks exceptions right before being thrown by a
throw
statement.Unhandled: Dotfuscator will inject code that tracks exceptions either at the method level by wrapping the method in a try/catch block and re-throwing the exception with the original stack trace, or at the assembly level by injecting handlers for the
AppDomain.UnhandledException
event and similar events.
Multiple ExceptionTrackAttribute
s may be defined on a single assembly or method to combine these detections.
Alternatively, you may wish to detect exceptions with your own code and provide them to the injected code via a source defined with the ExceptionTrackAttribute
called ExceptionSource.
ExceptionTrackAttribute
s cannot define an ExceptionSource and must use Dotfuscator's injected, exception detection code.
Application Notification
Optionally, the application code may be informed of an exception's occurrence. The application can then react to the exception in a customized way, such as by sending third-party telemetry.
The detection of an Exception is communicated via a sink defined with the ExceptionTrackAttribute
called ExceptionNotificationSink.
The injected code forwards the Exception
object which was detected to the sink.
For instance, consider the following attribute and its properties:
At runtime, when ExceptionExample.ApplicationNotification.ExceptionTrackLocation
is called, the injected code will detect unhandled exceptions (because the ExceptionType is set to Unhandled in this example).
If an exception is detected, it will be passed to the static method ExceptionExample.ApplicationNotification.OnExceptionDetected(Exception)
.
The OnExceptionDetected
method can then perform application-specific behavior based on the detected exception.
null
.
Report Info
When an exception occurs, it may be helpful for the user to provide additional information, such as what scenario triggered the error. Additionally, the user may consent to sending an exception report even if they previously opted-out of telemetry. You can have your application provide this information, or you can have the injected code ask the user for the information.
Application-Provided
This information is communicated via a source defined with the ExceptionTrackAttribute
called ReportInfoSource.
The source defines either an IDictionary
or an IDictionary<string,string>
.
There are three keys that the injected code will look up in this dictionary:
consent
: value is the stringtrue
orfalse
, indicating whether the user opted-in to transmitting this exception report.If
true
, the exception report will always be sent, even if the user opted-out of telemetry.If
false
(or any other string), the exception report will never be sent, even if the user opted-in to telemetry.If not specified, the general telemetry opt-in preference will be honored.
comment
: value is a user-provided comment about what the application was doing when the exception occurred.- If specified, this information will be included in the fault message.
contact
: value is an unstructured, user-provided piece of contact information.- If specified, this information will be included in the fault message.
Collecting user-specified report information is optional. If using this application-provided report information strategy, you can choose to populate any or all of these values without actually soliciting the information from the application's user.
Generic Exception Dialog
Dotfuscator can have the injected code ask the user for information, instead of calling out to application code.
To do this, on the ExceptionTrackAttribute
's ReportInfoSourceElement property, choose the "DefaultAction" value.
Behavior
This dialog will use the following information, if provided:
- The name of the application from
ApplicationAttribute
's Name property. - The name of the company from
BusinessAttribute
's CompanyName property. - The privacy policy URI from the
ExceptionTrackAttribute
's PrivacyPolicyUri property.
The user can provide additional details (the comment and contact information) by clicking the Add Details button. If they click the Send Error Report button, the report will be sent. If they close the dialog in any other way, the report will not be sent. The general telemetry opt-in preference will be ignored in all cases.
Dialog-compatible Application Types
The generic exception dialog can be used on assemblies supported by Exception Tracking and methods within those assemblies, except for the following:
- .NET Compact Framework assemblies
- Windows Phone assemblies
- Universal Windows Platform (UWP) assemblies
- Xamarin assemblies
- Unity assemblies
The assembly must target version 1.1 (or higher) of the .NET Framework or Silverlight version 2 (or higher).
Additionally, in a Silverlight assembly, the generic exception dialog can only be used for assembly-level Exception Tracking; it cannot be used for method-level tracking.
When using the built-in dialog on the .NET Framework, the dialog will be constructed and displayed using the Windows Forms API. This may have unintended consequences for console or service applications; it may be preferable to use application-provided report information in these situations. If the assembly does not already reference the appropriate Windows Forms libraries, references will be added.
Messages
Exception Tracking only generates one type of message: Fault.
Fault
Generated when an unhandled exception is detected in the assembly or method annotated with an ExceptionTrackAttribute
and the user consents to it being sent.
Includes the following data:
- Session ID
- Timestamp
- Exception type
- Exception message
- Exception stack trace
- List of loaded assemblies
- Comment and contact information, if provided
- Extended Keys if configured