Now that Visual Studio 2010 Beta 1 is officially released, I’m looking forward to hearing feedback from Dotfuscator CE users around the new capabilities we’ve added. First, Dotfuscator CE’s new official name is “Dotfuscator Software Services - Community Edition”. We’ve given it a new name (but here I will still call it “CE” for short) to emphasize its broader focus as a post build tool in this release. We’ve added a whole new class of features and services based on code injection. We’ve given it a new look, reorganizing and simplifying the user interface to improve usability and discoverability. Finally, we’ve improved on the traditional obfuscation functions you may already be using. In this article, I’d like to introduce you to the new code injection features.
Dotfuscator Considered as a Post Build Code Injection Platform
As a tool that already performs significant program analysis and applies binary code transformations, Dotfuscator is in the unique position where it can add value to an application in the post build phase, without necessarily having to write or modify source code. For a while now, Dotfuscator PRO has had these capabilities—and the recently announced Dotfuscator MDE does as well. So I’m happy that Dotfuscator CE is also joining the club. Dotfuscator CE can now inject the following behaviors:
- Session tracking to determine what applications have been executed, what versions of those applications, and for how long.
- Feature usage tracking to determine what features are being used, in what sequence, and for how long.
- Application expiry to encode an end-of-life date, transmit alerts when applications are executed after their expiry date, and terminate expired application sessions. We call this “Shelf Life”.
- Tamper defense to detect the execution of tampered applications, transmit incident alerts, and terminate tampered sessions.
On the server side, we’ve created a free version of our Runtime Intelligence Services Portal at free.runtimeintelligence.com . To send session tracking, feature usage, and other notifications to the free service, just select the free endpoint as the destination for your messages when configuring Dotfuscator for injection (I’ll show you where to do this below). When you log in to the portal using the company ID you created, you can view the data your application is sending.
A Concrete Example
Let’s use Dotfuscator CE’s new capabilities to add feature analytics to the “hello world” sample application that comes with Dotfuscator CE. The sample application is installed by default into your %Program Files%Microsoft Visual Studio 10.0ApplicationPreEmptive SolutionsDotfuscator Community Editionsamples folder. Since this folder is often not writeable by normal users, I recommend creating a work area under your “Documents” folder and copying HelloWorld.exe and hello_config.xml to it. These are the input application and the associated Dotfuscator configuration file respectively.
Once you’ve done that, launch “Dotfuscator Software Services” from the Visual Studio Tools menu, and open the hello_config.xml file via Dotfuscator File->Open Project menu.
Configuring Feature Analytics
Navigate to the Instrumentation editor by clicking on the Instrumentation node on the left side navigator.
Click on the Options tab, then check “Enable Instrumentation” and “Send application analytics messages”. This tells Dotfuscator to inject code to gather feature usage data as your application runs.
You configure the actual code injection via attributes. Attributes can be embedded in the source code using .NET custom attributes (defined in PreEmptive.Attributes.dll, located in the Dotfuscator installation folder). Alternatively, if you don’t want to modify the source code, you can use “extended attributes”, which are maintained through the Dotfuscator UI and stored in your Dotfuscator configuration file. That’s the approach we will use here.
First we will add two attributes at the assembly level that are used to identify and aggregate messages originating from your application. Click on the Attributes tab and highlight the Helloworld.exe assembly. Right click on it and select the “Add Attribute” menu item from the context menu. On the Add Attribute dialog, select both an Application and Business Attribute, then click OK.
The BusinessAttribute has a CompanyKey, which is a unique value used to identify the creator of the application. Later, you will use this key to log in to the free Runtime Intelligence Services Portal to view your data. You can generate a new unique identifier by pressing the “…” button associated with the CompanyKey entry area. You should also set the CompanyName property to the name of the organization associated with the CompanyKey. While not required, the name is used to personalize the portal.
Similarly, the ApplicationAttribute has a GUID property that identifies the instrumented application. Again, click on the “…” button associated with the GUID property to generate an application identifier. You can leave the other ApplicationAttributes properties blank.
Now it is time to add two attributes to the Main method, located in the HelloWorld.Hello class. Navigate to that class in the instrumentation editor’s class browser, right click on the Main method, and select Add Attribute from the context menu. Select Setup and Teardown attributes, then click OK.
The SetupAttribute should be placed on a method called when the application starts up. When Dotfuscator runs, it injects initialization code into the tagged method. The Main method is usually a good candidate, but that isn’t required—it just needs to be a method that is executed before any messages need to be sent. To configure the SetupAttribute, the only property you need to set is the Custom Endpoint, the remote destination of all messages sent from the application. Click on the “…” button to bring up the Custom Endpoint dialog, and select “PreEmptive’s Free Runtime Intelligence Services” as the endpoint.
The TeardownAttribute can also be placed on the Main method. In general, it should be placed on a method that is called near the end of the application’s lifecycle, after all messages have been sent. Dotfuscator injects cleanup code at the end of the tagged method. Since HelloWorld.exe is a single threaded console application, adding the Teardown attribute to the Main method works, as code at the end of Main is executed last.
Now that we have identified the application and specified the endpoint, we can now add the usage analytics. HelloWorld is a simple application that says Hello and Goodbye—we are interested in how often those two “features” are used (stay with me here, remember this is “hello world”!).
The “Hello” feature is implemented in the HelloWorld.Friendly.SayHello class. Navigate to the method in the instrumentation editor’s class browser. As before, right click to bring up the Add Attribute dialog, but this time select a Feature attribute. Feature attributes tell Dotfuscator where to inject analytics collecting code. Set the attribute’s Name property to “SayHello”. The name you set here shows up in the analytics reports, so choosing a human readable name is important. Leave the FeatureEventType property set to “Tick”. This tells Dotfuscator that the feature is an “instantaneous” event as opposed to an event with a stop and start time.
Now add the same attribute to the HelloWorld.Friendly.SayGoodbye class and name this feature “SayGoodbye”.
Configuration is now complete and you are ready to run Dotfuscator. Press the play button or hit Ctrl-B to build the project.
Now, when you run the application, it will send messages when it starts, stops, and whenever the “SayHello” and “SayGoodbye” methods execute.
Viewing your Data
You can see your data by going to the Free Runtime Intelligence Portal at free.runtimeintelligence.com and logging in with your company key.
Once logged in, you can view your application and feature dashboards to answer questions like:
Which of your applications are being used the most?
What operating systems are they running on?
What CLR versions are they running on?
How often are your features used?
There are also tabular views of the same data for application use:
And for feature use:
Take Away
You’ve seen in the example how you can use Dotfuscator CE in Visual Studio 2010 to implement what amounts to your own “Customer Experience Improvement Program” in your .NET application, with just a few clicks, and without writing any additional code. But I’ve just scratched the surface here– there are lots of other things you can do with this technology. In the coming weeks and months, we will be blogging in-depth about tamper detection, shelf-life, and application analytics. In the meantime, I encourage you to play with Dotfuscator CE yourself in the Visual Studio 2010 Beta and give us your feedback!