Dotfuscator User's Guide
SetupAttribute

Summary

The SetupAttribute is an instrumentation time attribute for methods. This attribute can be used to guide Application Analytics instrumentation.

When applied to Application Analytics, Dotfuscator will insert PreEmptive Analytics initialization code into methods with this attribute. There must be one or more methods with this attribute in an assembly or application that uses PreEmptive Analytics code. At runtime, the initialization code will send PreEmptive Analytics application and session start messages when this method is called. To further configure PreEmptive Analytics message sending, the developer can optionally specify information about an application instance ID and an "opt in" flag. Dotfuscator will use this information when generating the initialization code.

To configure the endpoint or destination of the analytics messages, Dotfuscator allows the StaticEndpoint property to be set to an endpoint of your choice.

Instance ID

The application instance ID (such as a serial number) is typically unique to a particular instance of the application and is determined by the application at runtime. The developer can make the instance ID available at runtime to the PreEmptive Analytics initialization code by specifying values for the InstanceIdSourceName, InstanceIdSourceElement, and (optionally) InstanceIdSourceOwner properties. These fields are used to generate code that makes the instance ID available to send in PreEmptive Analytics messages.

The InstanceIdSourceElement may be a string property, a string field, a no argument method that returns a string, or a string method argument.

If it is a property or field, it should be writable, accessible from the attributed method, and of string type. If it is a method, it should also be accessible from the attributed method. If the property, method, or field is not static, it must be defined on the same class as the attributed method, and the attributed method must not be static. The name of the property, method, or field must be specified in InstanceIdSourceName. The type defining the field, method, or property should be specified in InstanceIdSourceOwner; if InstanceIdSourceOwner is left unset, Dotfuscator will look for the property, method, or field on the type defining the attributed method.

If the InstanceIdSourceElement is a method argument, the named argument should be of type string. The name of the method argument must be specified in InstanceIdSourceName. InstanceIdSourceOwner is unused

Offline Storage of Usage Data

PreEmptive Analytics instrumented applications have the ability to store usage data in situations when network access is unavailable and then transmit the data when connectivity is restored. Usage data is stored in Isolated Storage. This behavior is enabled by default and default connectivity detection code is injected into instrumented applications. Developers can override the default behavior by changing the OfflineStateSourceElement. If the OfflineStateSourceElement value is changed to None then usage data will not be stored when the application is unable to connect to the network and that usage data will be dropped. Developers also have the ability to write their own network detection code and make the network connectivity state available to the PreEmptive Analytics code by specifying the applications offline state in a boolean value in the instrumented method's parameters, as the return value of a method or in a field or property. This is accomplished by setting the OfflineStateSourceElement property to the appropriate value and setting the OfflineStateSourceName and OfflineStateSourceOwner.

The application can also be notified of the success or failure of an attempt to store usage data to the offline storage mechanism via the OfflineStorageResultSinkElement. If the value is None then no notification will be made of the success or failure of the data storage. If the value is DefaultAction then if the storage mechanism is unable to store any usage data the application will exit immediately. Developers can write code to react to the success or failure of offline storage by setting the OfflineStorageResultSinkElement to the appropriate value and setting the OfflineStorageResultSinkName and OfflineStorageResultSinkOwner. The selected application code will be called with a parameter value or the boolean property or field will be set with the result of the most recent attempt to save usage data to the offline storage mechanism.

Opt In

The Opt-In flag is another runtime determined value that indicates if the user of the application has given permission for the application to send PreEmptive Analytics data. The developer can make the opt-in flag available at runtime to the PreEmptive Analytics initialization code by specifying values for the OptInSourceName, OptInSourceElement, and (optionally) OptInSourceOwner properties. These fields are used to generate code that makes the opt-in preference available to the PreEmptive Analytics message sender.

The OptInSourceElement may be a boolean property, a boolean field, a no argument method that returns a boolean, or a boolean method argument.

If it is a property or field, it should be writable, accessible from the attributed method, and of boolean type. If it is a method, it should also be accessible from the attributed method. If the property, method, or field is not static, it must be defined on the same class as the attributed method, and the attributed method must not be static. The name of the property, method, or field must be specified in OptInSourceName. The type defining the field, method, or property should be specified in OptInSourceOwner; if OptInSourceOwner is left unset, Dotfuscator will look for the property, method, or field on the type defining the attributed method.

If the OptInSourceElement is a method argument, the named argument should be of type boolean. The name of the method argument must be specified in OptInSourceName. OptInSourceOwner is unused

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

SetupAttribute
Copy Code
public class SetupAttribute : Attribute

Constructor Members

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

Property Members

Name Summary
EndpointSourceElement : EndpointSourceElements Indicates if the StaticEndpoint or a runtime determined endpoint will be used. Specifying None or DefaultAction will use the endpoint specified by the StaticEndpoint attribute.
EndpointSourceName : String The name of the property, field, method, method parameter, or appSettings key that will contain the endpoint URL. If this property is set, EndpointSourceElement is required to be set to something other than None or DefaultAction.
EndpointSourceOwner : Type If the EndpointSourceElement is a field, method or property, EndpointSourceOwner 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.
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 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.
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 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.
InstanceIdSourceElement : SourceElements Indicates how to access the instance ID at runtime, at the time that the setup method is called (e.g. a field, property, or method parameter). To use this property, InstanceIdSourceName must also be set. If InstanceIdSourceElement is a field or property, InstanceIdSourceOwner must also be set unless the field or property is defined on the same class as the attributed method.
InstanceIdSourceName : String The name of the property, field, or method parameter that will contain the instance ID at runtime, at the time that the setup method is called. If this property is set, InstanceIdSourceElement is required to be set as well. If this property is not set, Dotfuscator will not generate code that sends an instance Id with PreEmptive Analytics messages.
InstanceIdSourceOwner : Type If the InstanceIdSourceElement is a field or property, InstanceIdSourceOwner indicates the name of the type that defines the field or property. If not set, the named source element is searched for on the attributed method’s type.
OfflineStateSourceElement : SourceElements Indicates how to access the applications offline/online state at runtime, at the time that the setup method is called (e.g. a field, property, or method parameter). If neither DefaultAction nor None is selected then OfflineStateSourceName must also be set. If OfflineStateSourceElement is a field or property, OfflineStateSourceOwner must also be set unless the field or property is defined on the same class as the attributed method. If the value of this property is DefaultAction then application usage data will be automatically stored by the offline storage mechanism (using Isolated Storage) when the analytics data endpoint is unavailable. If the value of this property is None then application usage data will not be stored when the analytics data endpoint is unavailable.
OfflineStateSourceName : String The name of the property, field, or method parameter that will contain the offline state of the application at runtime, at the time that the setup method is called. If this property is set, OfflineStateSourceElement is required to be set as well.
OfflineStateSourceOwner : Type If the OfflineStateSourceElement is a field or property, OfflineStateSourceOwner indicates the name of the type that defines the field or property. If not set, the named source element is searched for on the attributed method’s type.
OfflineStorageResultSinkElement : SourceElements Indicates how the application is notified when usage data is stored to the offline storage mechanism. If this property is not DefaultAction or None then OfflineStorageResultSinkName must also be set. If OfflineStorageResultSinkElement is a field or property, OfflineStorageResultSinkOwner must also be set unless the field or property is defined on the same class as the attributed method. If the value of this property is None then no notification will take place when application usage data is saved to the offline storage mechanism.  If the value of this property is DefaultAction then the application will exit immediately when a storage failure occurs
OfflineStorageResultSinkName : String The name of the property, field, or method parameter that will contain the most recent result of the application storing usage data to the offline storage mechanism If this property is set, OfflineStorageResultSinkElement is required to be set as well.
OfflineStorageResultSinkOwner : Type If the OfflineStorageResultSinkElement is a field or property, OfflineStorageResultSinkOwner indicates the name of the type that defines the field or property. If not set, the named source element is searched for on the attributed method’s type.
OptInSourceElement : SourceElements Indicates how to access the opt-in flag at runtime, at the time that the setup method is called (e.g. a field, property, or method parameter). To use this property, OptInSourceName must also be set. If OptInSourceElement is a field or property, OptInSourceOwner must also be set unless the field or property is defined on the same class as the attributed method.
OptInSourceName : String The name of the property, field, or method parameter that will contain the opt-in flag at runtime, at the time that the setup method is called. If this property is set, OptInSourceElement is required to be set as well. If this property is not set, Dotfuscator will generate code that sends PreEmptive Analytics messages all the time.
OptInSourceOwner : Type If the OptInSourceElement is a field or property, OptInSourceOwner indicates the name of the type that defines the field or property. If not set, the named source element is searched for on the attributed method’s type.
StaticEndpoint : String Defines the destination URI for PreEmptive Analytics messages.  This URI must represent the endpoint for a web service which will consume PreEmptive Analytics messages. If this property is not set, null, or empty, PreEmptive Analytics messages will be sent to the well-known URI representing PreEmptive's commercial analytics endpoint.
UseSSL : Boolean Use HTTPS protocol when sending PreEmptive Analytics messages to a PreEmptive Analytics Endpoint. Default value is true.
OmitPII : Boolean Specifies whether to exclude personally identifiable information from analytics reporting. Default value is false.
See Also

References

Instrumentation

 

 


© 2016 PreEmptive Solutions, LLC. All Rights Reserved.

www.preemptive.com