Dotfuscator User's Guide
Entry Point Attributes

To send any kind of PreEmptive Analytics Data, identify appropriate entry point methods in the application to be processed. Then add Setup attributes to the entry point methods. When Dotfuscator encounters a Setup attribute during its processing, it adds PreEmptive Analytics initialization code to the start of the entry point method. If Dotfuscator is configured to send analytics messages, it adds code to send a startup message to a PreEmptive Analytics Endpoint. Setup attributes are not required at runtime; therefore, Dotfuscator strips them from the output application.

An entry point method is a method in the application that is executed as part of the application's startup sequence. It does not have to be the first method called by the runtime or framework when the application starts, but it must have the property that is executed every time the application is run.

Example entry point methods for different application types:

Application Type Possible Entry Point Method
Console Application Main or method always called from Main
Windows Forms Application Main Form’s constructor

The Setup attribute has several arguments or properties, all in order to support privacy and data security scenarios.

Privacy and Security Settings

Opt-in

Applications that allow the user to opt-in or opt-out of PreEmptive Analytics Data gathering must communicate the user's choice to the PreEmptive Analytics code when the application starts.

To accomplish this, the Setup attribute is used to specify an OptInSource, which Dotfuscator uses to generate code that acquires the user's opt-in preference at runtime. The OptInSource is a Boolean-valued property, field, or method argument; it is the developer's responsibility to ensure that a correct value is stored in the OptInSource at the time the entry point method is executed.

The Setup attribute defines three properties for specifying an OptInSource:

The opt-in settings are optional. If they are omitted, the PreEmptive Analytics code sends all messages (i.e. it assumes opt-in).

Sample Setup attribute usage with OptInSource as method argument:

Sample Setup Attribute with OptInSource
Copy Code
[Setup(
   OptInSourceElement = SourceElements.MethodArgument,
   OptInSourceName = "optIn",
   UseSSL = false
)]
private void MyEntryMethod(bool optIn) { ... }

Application Instance ID

Applications that wish to provide an application instance identifier (e.g. a serial number) as part of the PreEmptive Analytics Data must communicate the ID to the PreEmptive Analytics code when the application starts.

To accomplish this, the Setup attribute can be used to specify an InstanceIdSource, which Dotfuscator uses to generate code that acquires the application's instance ID at runtime. The InstanceIdSource is a string valued property, field, or method argument; it is the developer's responsibility to ensure that a correct value is stored in the InstanceIdSource at the time the entry point method is executed.

Like the OptInSource, the Setup attribute defines three properties for specifying an InstanceIdSource:

The instance ID settings are optional. If they are omitted, PreEmptive Analytics Data does not include an instance ID.

Sample Setup attribute usage with InstanceIdSource defined as a static property called "InstanceId" on the "Program" class:

Sample Setup Attribute with InstanceIdSource
Copy Code
[Setup(
   InstanceIdSourceElement = SourceElements.Property,
   InstanceIdSourceName = "InstanceId",
   InstanceIdSourceOwner = typeof(Program),
   UseSSL = false
)]
private void MyEntryMethod() { ... }

SSL

The UseSSL argument controls which web protocol the PreEmptive Analytics code uses to send messages. If UseSSL is set to true (default), it sends messages using the HTTPS protocol. If UseSSL is set to false, it sends messages using the HTTP protocol.

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.

Custom Endpoint

When you add the SetupAttribute, you may set the destination of the messages using the StaticEndpoint property.

 

 


© 2016 PreEmptive Solutions, LLC. All Rights Reserved.

www.preemptive.com