Building in the Cloud with Dotfuscator Community Edition

Most of our previous blogging about Dotfuscator Community Edition (CE) assumes you are doing local builds, or have a dedicated build server—but what if you want to use Dotfuscator CE within a distributed build system such as Visual Studio Team Services (VSTS) or Team Foundation Server (TFS) on-premises? Until now, you've had to do extra work to install and provision Dotfuscator CE on each build agent host in your pool. Now, we're pleased to announce a VSTS build extension for Dotfuscator CE, available in the VSTS Marketplace. It does the extra work for you, making it easy to get Dotfuscator CE into your distributed build.

Let's walk through an example, using a sample project. The overall process is:

1. Stage a local build of the project and verify that Dotfuscator CE is configured correctly.
2. Push it to a VSTS hosted project.
3. Automate the build using the new Dotfuscator CE build extension.

Setup the Local Sample Project

• Download the "hello world" sample application and unzip it to a directory on your file system. The zip file contains two versions of the sample: one tailored for Visual Studio 2015 and up, and one tailored for Visual Studio 2017. For this exercise, choose the "Visual Studio 2015" version of the sample (even if you are using Visual Studio 2017 locally), since that is what we will be using on the build agent hosts. You can review the included Readme.txt file to learn more about the sample application.
• Open the DotfuscatorCommunityEditionSample.sln file in Visual Studio and build the release configuration. The solution should build with no errors or warnings.

Setup your Local Environment

• Get and verify that you have Dotfuscator CE. You should see it on Visual Studio's Tools menu. If it is not there, you can always find the latest version on the Dotfuscator Downloads Page.
• The "hello world" sample ships with a ready-made Dotfuscator configuration file that exercises many of Dotfuscator CE's capabilities, such as renaming and tamper detection. To test that you have the environment setup correctly, run the Dotfuscator CE GUI from the Tools menu and open the sample's configuration file (dotfuscator_config.xml).
• Build the project in the Dotfuscator UI and verify that it builds without errors, and that the output assembly is located in the "Dotfuscated" directory.  
• If your copy of Dotfuscator CE is unregistered, now is a good time to register it, because you will need your serial number in a later step.

Push to VSTS

Once you have a successful local build, the next step is to push the project to the remote repository. We will use VSTS, but the same procedure will also work if you are using on-premises TFS 2015 (Update 3 and above).

• Create a local git repository for the project, along with an associated team project in VSTS. This tutorial will help you if you are not already familiar with the process.
• Before syncing your local repository with the remote:
  • Delete the local Dotfuscated directory (if it exists from previous builds), and any files in it. We do not want to store the obfuscated outputs in the git repository.
  • Exclude that directory from future commits by adding the following to the .gitignore file:

    Dotfuscated/
    

• Commit the above changes, and sync the local repository to the remote. At this point you should be able to see the sample code in the VSTS portal, like this:  

Create a Build and Add the Dotfuscator CE Extension

• Create a build definition, using the Visual Studio template. This tutorial will help you if you are not already familiar with the process. When complete you should see something like this in the VSTS portal:  

• If you queue the build as-is, it will succeed, but the output assembly won't be protected. Let's fix that by Getting the Dotfuscator CE extension from the Marketplace. Click the install button to add it to your VSTS account.

• Once installed, add the Dotfuscator CE Provisioner Task to your build by editing the build definition, and adding the task from the Utility category.  
• The Provisioner task must run before Dotfuscator CE runs, so after adding the task to your build definition, move it above the "Visual Studio Build" task.  
• Configure the Provisioner task:
  • In the Dotfuscator Community Serial Number field, enter the serial number you received when you registered your local version of Dotfuscator CE. For reference, it is located on Dotfuscator CE's "About" box.  
  • Select the Dotfuscator Version you wish to use, by selecting the associated Visual Studio version from the dropdown. As of this writing, the build agents in the hosted pool do not yet have Visual Studio 2017, but that is expected to change very soon. The Dotfuscator CE extension will support Visual Studio 2017 when that happens; but for now, choose Visual Studio 2015.
  • The last field, User Specified Environment Variable is not required in this case. If you have a custom build agent host with Dotfuscator CE installed in a non-default location, you can use this field to provide the name of an environment variable on the build host that contains the path to the Dotfuscator CE command line executable. Since we will be using build agents in the hosted pool, which already have Dotfuscator CE in the default locations, setting this is unnecessary.
  • Save your changes to the task configuration.  
• Next, add a Dotfuscator Community Edition Task to your build definition. It is available in the Build category.  
• Move it below the "Visual Studio Build" task, so it runs after code compilation.
• Configure the Dotfuscator CE task:
  • In the Relative Path to Configuration File field, enter the name of the Dotfuscator configuration file (you can also browse for it in the project tree).
  • In the Additional Command Line Arguments field, you can also pass command line arguments to Dotfuscator CE. For this example, none are necessary, so we will leave it blank.
  • Save your changes to the task configuration.  
• Now, if you queue a build, it should pass. You should see output from Dotfuscator CE in the logs from the "Run Dotfuscator" step.  
• We aren't finished yet, because we still need to capture the obfuscated output assembly and the renaming map file as build artifacts. Do this by modifying the Copy Files task to include everything in the Dotfuscated directory.  
• Now if you do a build, not only should it pass, but the obfuscated outputs will be included with the other build artifacts.  

Other Scenarios

We've covered a basic end-to-end scenario, using a simple Visual Studio solution, building with VSTS. There are additional ways to use the Dotfuscator CE build extension, and it supports many other scenarios:

• As mentioned, it is supported with on-premises TFS versions 2015 Update 3 and higher. The configuration steps are the same.
• You can use it with custom build agent hosts, so long as Dotfuscator CE itself is installed on them.
• If you want to run Dotfuscator CE directly inside of a solution build (e.g. as an Exec task in a project's AfterBuild target), you can. To do so, you only need the Provision step before the solution build task in your build definition. The Provision task sets a build variable called DotfuscatorCEDir that you can reference in your MSBuild scripts. For example:

  <Target Name="AfterBuild" Condition="'$(Configuration)' == 'Release'">
    <Exec Command="&quot;$(DotfuscatorCEDir)\dotfuscatorCLI.exe&quot; ..\dotfuscator_config.xml" />
  </Target>
  

Conclusion

You now have an idea of what's possible with Dotfuscator CE in the cloud. You can use the VSTS build extension to easily protect your application from reverse engineering, tampering, and unauthorized debugging.

Dotfuscator Community Edition is free for experimental and non-commercial use. For commercial use, Dotfuscator Professional Edition offers advanced obfuscation and code protection capabilities, and also can be run in distributed build environments. You can try Dotfuscator Professional Edition for free, with support, by signing up for an evaluation.