Automate Your Builds with New CE Command Line Support
At Microsoft Build 2016, we introduced a new feature for Dotfuscator Community Edition (CE): command line support. This will allow you to integrate Dotfuscator into your automated build process, so that your builds and releases can automatically use Dotfuscator for obfuscation, tamper protection, usage tracking, and expiration. To help you get started, this post will walk through how to use the command line interface (CLI), as well as how to integrate it into MSBuild and Visual Studio for automated builds.
Note: This blog post was originally written for Dotfuscator CE version 5.19.2, which shipped with Visual Studio 2015 Update 3. Dotfuscator CE version 5.27.0, which ships with Visual Studio 2017, continues to offer command line support to registered users. However, the newer version of Dotfuscator CE no longer includes the sample project mentioned in this blog post; instead, a slightly different sample project is hosted on our Support page.
Note that command line support is only available in Dotfuscator CE version 5.19.2 and later. See this page to learn how to download, install, and enable the command line interface. After doing so, assuming a default installation of Visual Studio, Dotfuscator CE is located at this path:
[Program Files]\Microsoft Visual Studio 14.0\PreEmptive Solutions\Dotfuscator and Analytics Community Edition
And the sample project we'll be using is located at:
Because this directory requires elevated permissions to edit, we recommend copying the sample to a different location, such as your Desktop. The rest of these instructions assume this copied directory is your working directory.
About the Sample
The sample's input consists of a single executable .NET assembly,
HelloWorld.exe, derived from one C# code file,
Hello.cs. Also included is a Dotfuscator configuration file,
hello_config.xml. You can open it
in the Dotfuscator CE GUI by running the command:
[CE directory]\dotfuscator.exe hello_config.xml
You can build the sample project from the GUI (Build -> Build Project).
This will output an obfuscated (and instrumented) assembly in the
dotfuscated subdirectory, alongside a map file showing how symbols were renamed.
Building from the Command Line
To build our sample from the command line, we simply specify the configuration file as an argument to the CLI executable:
[CE directory]\dotfuscatorCLI.exe hello_config.xml
The output will contain the typical build output you would see in the GUI, including exclusions due to Smart Obfuscation. The build results will be the same as if we had opened the project in the GUI and built it there: an obfuscated output, alongside
a renaming map file, in the
Integrating with MSBuild
Command line builds are useful, because they can be automated. Take this simple MSBuild project, for instance, which uses the
Exec task to call Dotfuscator CE.
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" DefaultTargets="Build;Obfuscate"> <ItemGroup> <Compile Include="hello.cs" /> </ItemGroup> <Target Name="Build" > <Csc Sources="@(Compile)" OutputAssembly="HelloWorld.exe"/> </Target> <Target Name="Obfuscate" DependsOnTargets="Build" > <Exec Command=""C:\Program Files (x86)\Microsoft Visual Studio 14.0\PreEmptive Solutions\Dotfuscator and Analytics Community Edition\DotfuscatorCLI.exe" hello_config.xml" /> </Target> </Project>
Note the use of escaped quotation-marks --
" -- in the
Command attribute's value. Quotation marks are required because the path to the CLI contains spaces, and they must be escaped to fit into the XML syntax.
You can copy and save this project file as
HelloWorld.csproj, then run it from the MSBuild Command Prompt:
HelloWorld.exe, then calls Dotfuscator to obfuscate that assembly, per the configuration file. Just as before, this ultimately creates an obfuscated output in the
alongside a renaming map file.
Integrating with Visual Studio
Project files created by Visual Studio also use the MSBuild format. Thus, you can also automatically call Dotfuscator CE in a Visual Studio build as well. Consider this excerpt from a
<Target Name="AfterBuild" Condition="'$(Configuration)' == 'Release'"> <Exec Command=""C:\Program Files (x86)\Microsoft Visual Studio 14.0\PreEmptive Solutions\Dotfuscator and Analytics Community Edition\DotfuscatorCLI.exe" config_file.xml" /> </Target>
Whenever Visual Studio builds this project in the Release configuration, it will also call Dotfuscator CE, executing whatever configuration is saved in
Making Your Configuration Portable
There's an interesting aspect of the sample
hello_config.xml configuration that's useful for command-line use and build integration.
By default, when you add an input to a Dotfuscator project, the configuration refers to the input by its absolute path. But recall that you were able to copy
hello_config.xml and its inputs to another directory and still have Dotfuscator
correctly find the inputs when run. This is because the configuration specifies its inputs by paths relative to the configuration file, instead of the default absolute paths.
Specifically, the input is specified in the configuration as:
This notation uses the project property
configdir. Project properties are variables that can stand-in for file directory and name values within the configuration. In this case,
configdir is a property that is always set to the
absolute path of the directory holding the current project's configuration file.
Thus, as long as
HelloWorld.exe is a sibling of the configuration file, the project can find and use this assembly as an input. The configuration also uses the
configdir property when specifying the output location of the obfuscated
assembly and the renaming map file.
When creating your own Dotfuscator configuration, you may wish to use this pre-populated project property, thus making your configuration portable between, for instance, a development machine and a build server. You can also specify your own project properties, and set their values from the command line. For more details, see the Properties section of the Dotfuscator CE Help.
Personal Use Only
While we have provided command line support for CE as a way to automate the obfuscation process, please take note of CE's specific licensing restrictions. The Dotfuscator CE license expressly prohibits the use of Dotfuscator CE by commercial organizations for anything other than personal research and education. If you would like to use Dotfuscator on commercial projects, please consider evaluating Dotfuscator Professional Edition.