Dotfuscator User's Guide
ExceptionTrackAttribute

Summary

The ExceptionTrackAttribute is an instrumentation time attribute for both assemblies and methods. Dotfuscator will insert exception tracking code into any assembly or method with this attribute. At runtime, the exception tracking code can detect caught, thrown, or unhandled exceptions. Multiple ExceptionTrackAttributes may be defined on an assembly or method to combine these detections. Once detected, the exception tracking code can collect details from the user and report the detected exception to a PreEmptive Analytics endpoint. A user can explicitly allow an exception report to be sent even if he or she has previously opted out of sending PreEmptive Analytics messages, and can provide comment and contact information to be sent along with the report. In addition, the developer can specify a custom action be taken when an exception is detected. In order to send Exception Tracking report messages, your application must contain methods marked with a Setup and Teardown attribute. Do not put the ExceptionTrackAttribute on the same method containing the Setup Attribute. Methods with this attribute must be executed after the method containing the Setup Attribute.

Exception Notification

A SinkElement may be used to specify a method to call, or a property or field to set in the application when an exception is detected. Unlike other SinkElement types which are always called when a check is performed, the ExceptionNotificationSinkElement is only called when an exception of the configured type is detected within the attributed assembly or method.

If the SinkElement is a property, the property's type must be Exception and its value will be set to the exception that was detected when detection occurs. If using method-level exception tracking, the property should be writable and accessible from the attributed method. If the property is not static, it must be defined in the same class as the attributed method, and the attributed method must not be static. If using assembly-level exception tracking, the property must be public, static, and writable. The name of the property must be specified in ExceptionNotificationSinkName. The type defining the property should be specified in ExceptionNotificationSinkOwner. If using method-level exception tracking, this can be left unset; in that case, Dotfuscator will look for the property on the type defining the attributed method. ExceptionNotificationSinkOwner must be set when using assembly-level exception tracking.

If the SinkElement is a field, the field's type must be Exception and its value will be set to the exception that was detected when detection occurs. If using method-level exception tracking, the field should be accessible from the attributed method. If the field is not static, it must be defined on the same class as the attributed method, and the attributed method must not be static. If using assembly-level exception tracking, the field must be public and static. The name of the field must be specified in ExceptionNotificationSinkName. The type defining the field should be specified in ExceptionNotificationSinkOwner. If using method-level exception tracking, this can be left unset; in that case, Dotfuscator will look for the field on the type defining the attributed method. ExceptionNotificationSinkOwner must be set when using assembly-level exception tracking.

If the SinkElement is a method, the method will be called with a single parameter of type Exception when detection occurs. If using method-level exception tracking, the target method should be accessible from the attributed method. If the target method is not static, it must be defined in the same class as the attributed method, and the attributed method must not be static. If using assembly-level exception tracking, the method must be public and static. The name of the target method must be specified in ExceptionNotificationSinkName. The type defining the target method should be specified in ExceptionNotificationSinkOwner. If using method-level exception tracking, this can be left unset; in that case, Dotfuscator will look for the target method on the type defining the attributed method. ExceptionNotificationSinkOwner must be set when using assembly-level exception tracking.

If the SinkElement is a method argument, the named argument should be a Delegate type and the Delegate must have this signature: void( System.Exception ). The Delegate will be invoked with the Exception argument set to the value of the detected exception when detection occurs. The name of the method argument must be specified in ExceptionNotificationSinkName. ExceptionNotificationSinkOwner is unused.

If the SinkElement is a Delegate, it should be a field of Delegate type. The Delegate will be invoked with the argument of type Exception set to the exception that was detected when detection occurs. If using method-level exception tracking, the field should be accessible from the attributed method. If the field is not static, it must be defined on the same class as the attributed method, and the attributed method must not be static. If using assembly-level exception tracking, the field must be public and static. The name of the field must be specified in ExceptionNotificationSinkName. ExceptionNotificationSinkOwner is unused.

If the ExceptionNotificationSinkElement is set to DefaultAction or None, Dotfuscator will not inject any code to react to the detected exception. Dotfuscator will still generate code to send the appropriate message to a PreEmptive Analytics Endpoing if configured to do so via the SendReport attribute property.

Dotfuscator will remove this custom attribute from the metadata after instrumentation.

ExceptionTrackAttribute
Copy Code
public class ExceptionTrackAttribute : Attribute

Constructor Members

Name Summary
ExceptionTrackAttribute() Initializes a new instance of the class.

Property Members

Name Summary
ExceptionNotificationSinkElement : SinkElements Indicates whether and how to take action upon detection of an exception of the configured ExceptionType. A sink element may be a writable field or settable property of type Exception, a void( System.Exception ) method to call, or a Delegate to invoke. To use this property, ExceptionNotificationSinkName must also be set. If using method-level exception tracking and ExceptionNotificationSinkElement is a field, method, or property, ExceptionNotificationSinkOwner must also be set unless the field, method or property is defined on the same class as the attributed method. If using assembly-level exception tracking, ExceptionNotificationSinkOwner must always also be set. If the SinkElement is set to “None” or “DefaultAction”, Dotfuscator will not inject any code to react to the detected exception. If the SendReport property is set to true, code to send an exception report will still be injected regardless of whether this property has been set to “None” or “DefaultAction”.
ExceptionNotificationSinkName : String The name of the property, field, method to set or call when an exception of the configured type is detected. If using assembly-level exception tracking, this property, field, or method must be public, static, and writable. If this property is set, ExpirationNotificationSinkElement is required to be set as well. If this property is not set, Dotfuscator will not inject any code to react to the detected exception. If the SendReport property is set to true, code to send an exception report will still be injected regardless of whether this property is set.
ExceptionNotificationSinkOwner : Type If the ExceptionNotificationSinkElement is a field, method or property, ExceptionNotificationSinkOwner indicates the name of the type that defines the field, method or property. If not set, the named source element is searched for on the attributed method’s type. ExceptionNotificationSinkOwner must be set for assembly-level exception tracking.
ExceptionSourceElement : SourceElements Indicates how to access the exception object at runtime. The default value is DefaultAction. If this property is set to DefaultAction or None, Dotfuscator will generate code that detects the exception object based on the current execution context. If this property is set to any other value, ExceptionSourceName must also be set. If using method-level exception tracking and ExceptionSourceElement is a field, method, or property, ExceptionSourceOwner must also be set unless the field, method or property is defined on the same class as the attributed method. If using assembly-level exception tracking, this property is unavailable in the UI. If it is set to anything other than DefaultAction on an assembly-level attribute a build error will occur.
ExceptionSourceName : string The name of the property, field, method, or method parameter that will contain the exception object at runtime, at the time that the attributed method is called.
ExceptionSourceOwner : Type If the ExceptionSourceElement is a field, method or property, ExceptionSourceOwner indicates the name of the type that defines the field, method or property. If not set, the named source element is searched for on the attributed method’s type.
ExceptionType : ExceptionTypes The type of exceptions to track with this ExceptionTrackAttribute (caught, thrown, or unhandled). The default is Unhandled.
ExtendedKeyMethodArguements : string A pattern indicating which parameter names and values should be automatically added to the messages extended key data at runtime. See Automatically Sending Method Parameters as Extended Keys for details on supported patterns.
ExtendedKeySourceElement : SourceElements Indicates how to access the extended key dictionary at runtime, at the time that the attributed method is called (e.g. a field, property, method, or method parameter). To use this property, ExtendedKeySourceName must also be set. If using method-level exception tracking and ExtendedKeySourceElement is a field, method, or property, ExtendedKeySourceOwner must also be set unless the field, method or property is defined on the same class as the attributed method. If using assembly-level exception tracking, ExtendedKeySourceOwner must always also be set.
ExtendedKeySourceName : string The name of the property, field, method, or method parameter that will contain the extended key dictionary at runtime, at the time that the attributed method is called. If using assembly-level exception tracking, this property, field, or method must be public, static, and writable. If this property is set, ExtendedKeySourceElement is required to be set as well. If this property is not set, Dotfuscator will not generate code to send extended key information.
ExtendedKeySourceOwner : Type If the ExtendedKeySourceElement is a field, method or property, ExtendedKeySourceOwner indicates the name of the type that defines the field, method or property. If not set, the named source element is searched for on the attributed method’s type. ExtendedKeySourceOwner must be set for assembly-level exception tracking.
PrivacyPolicyUri : string URL to a privacy policy covering the transmission of exception reports. This property is only used if the ReportInfoSourceElement is set to DefaultAction. In this case, a link to the PrivacyPolicyUri is included on the built-in exception report dialog. If this property is not set, the exception report dialog will not contain a privacy policy link.
ReportInfoSourceElement : SourceElements Indicates how to access the user-specified report information dictionary at runtime, at the time an exception is detected. The default value is None. If this property is set to None, Dotfuscator will not generate code that obtains user-specified exception report information. If this property is set to DefaultAction, Dotfuscator will generate code that displays a built-in dialog that shows the exception message and prompts the user for his or her address, comments, and consent to send the report. If this property is set to any other value, ReportInfoSourceName must also be set. If using method-level exception tracking and ReportInfoSourceElement is a field, method, or property, ReportInfoSourceOwner must also be set unless the field, method or property is defined on the same class as the attributed method. If using assembly-level exception tracking, ReportInfoSourceOwner must always also be set. See Collecting User-specified Exception Report Information for a description of the key-value pairs recognized in the user-specified report information dictionary.
ReportInfoSourceName : string The name of the property, field, method, or method parameter that will contain the user-specified report information dictionary at runtime, at the time that the attributed method is called. If using assembly-level exception tracking, this property, field, or method must be public, static, and writable. If this property is set, ReportInfoSourceElement is required to be set as well. If this property is not set, Dotfuscator will not generate code that obtains user-specified exception report information.
ReportInfoSourceOwner : Type If the ReportInfoSourceElement is a field, method or property, ReportInfoSourceOwner indicates the name of the type that defines the field, method or property. If not set, the named source element is searched for on the attributed method’s type. ReportInfoSourceOwner must be set for assembly-level exception tracking.
SendReport : bool Whether or not to send an exception report when an exception is tracked. The default value is true. If this property is set to false, the ReportInfoSource properties will be ignored. A custom action (via the ExceptionNotifiationSink properties) will always be taken if one has been configured, regardless of the value of this property.
See Also

Exception Tracking

Instrumentation

References

 

 


© 2016 PreEmptive Solutions, LLC. All Rights Reserved.

www.preemptive.com