Walkthrough: Protect .NET Framework Sample App with MSBuild

This article describes how to use the GettingStarted sample app, add Dotfuscator to the project file, build the app in Release mode, and review the files Dotfuscator creates.

Dotfuscator integrates with MSBuild. After you add the Dotfuscator settings to the project file, Dotfuscator runs automatically when you build the app in a Dotfuscator-enabled configuration, such as Release. The current article explains that Dotfuscator protects the app’s .exe and .dll files in the project output directory and creates a DotfuscatorReports folder during the build.

Note: This walkthrough uses the GettingStarted sample app. After you understand the workflow, you can follow the same general process for your own project. 

Before You Start

Before you begin, make sure you have:

• Dotfuscator Professional installed and activated.
• The GettingStarted sample app.
• Visual Studio, Visual Studio Code, or another MSBuild-based build tool.
• Access to edit the project file, such as GettingStarted.csproj.

Get the GettingStarted Sample

The GettingStarted sample gives you a small app that you can use to test Dotfuscator protection before you apply it to your own project. This is a .NET framework sample. The integration applied in this example works for any other .NET framework application.

1. Open the Dotfuscator Pro samples repository.
2. Go to the GettingStarted sample.
3. Download or clone the repository.
4. Open the solution file in Visual Studio.

Open the Project File

To integrate Dotfuscator, edit the app's project file.

1. Open the GettingStarted solution.
2. Locate the project file, such as GettingStarted.csproj.
3. Open the project file for editing.

If you use Visual Studio and cannot edit the project file directly, unload the project, edit the project file, and reload the project after you save your changes.

Note: Add the Dotfuscator integration only to the main project. This is usually the startup project. 

Add Dotfuscator to the Project File

For the GettingStarted sample, add the Dotfuscator MSBuild integration to the project file.

Copy the following XML elements and paste them immediately before the closing </Project> tag.

<!-- Import environment-specific build properties for Dotfuscator, if they exist. -->
<Import Project="$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props"
       Condition="Exists('$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props')"/>

<!-- Set build properties for Dotfuscator. -->
<PropertyGroup>
 <!-- Specify the location of the MSBuild targets, if not already provided. -->
 <DotfuscatorMSBuildDir Condition="'$(DotfuscatorMSBuildDir)' == ''">$(MSBuildProgramFiles32)/MSBuild/PreEmptive/Dotfuscator/7</DotfuscatorMSBuildDir>

 <!-- Generate a default Dotfuscator config file (DotfuscatorConfig.xml) if it doesn't exist. -->
 <!-- TODO: Set this to false after the file is generated by the first local build. -->
 <DotfuscatorGenerateConfigFileIfMissing>true</DotfuscatorGenerateConfigFileIfMissing>

 <!-- Enable Dotfuscator for Release builds. -->
 <DotfuscatorEnabled Condition="'$(Configuration)' == 'Release'">true</DotfuscatorEnabled>
</PropertyGroup>

<!-- Import the Dotfuscator MSBuild targets. Must be done last. -->
<Import Project="$(DotfuscatorMSBuildDir)/PreEmptive.Dotfuscator.Common.targets" />

Notes: 

• The order of these elements is important. The Dotfuscator MSBuild targets import must be last.
• If you use Dotfuscator v6, specify the installed product version in the targets path. For more information, see MSBuild Reference. 

Build the Project in Release Mode

After you update the project file, build the project in Release mode.

Build in Visual Studio

1. Open the solution.
2. In the build configuration dropdown, select Release.
3. Build the solution.

Build from the Command Line

From the project or solution folder, run a Release build with your MSBuild-based build tool.

For example:

dotnet build -c Release

Note: The exact command depends on your project type and target framework. For .NET Framework projects, you may need Visual Studio Build Tools or MSBuild instead of `dotnet build`.

Review the Generated Files

During the first successful build, Dotfuscator generates DotfuscatorConfig.xml with default protection settings. The build may show a warning that the file was created. You can ignore this warning during the first build. The current article states that you should check the generated config file into version control.

After the build finishes, review these files:

Disable Automatic Config File Generation

After DotfuscatorConfig.xml exists and is checked into version control, disable automatic config file generation.

This helps prevent builds from silently creating a new default config file when the expected config file is missing.

In the project file, replace this XML:

<!-- Generate a default Dotfuscator config file (DotfuscatorConfig.xml) if it doesn't exist. -->
<!-- TODO: Set this to false after the file is generated by the first local build. -->
<DotfuscatorGenerateConfigFileIfMissing>true</DotfuscatorGenerateConfigFileIfMissing>

With this XML:

<!-- Error if the Dotfuscator config file (DotfuscatorConfig.xml) is missing. -->
<DotfuscatorGenerateConfigFileIfMissing>false</DotfuscatorGenerateConfigFileIfMissing>

Then save the project file and build the project again in Release mode.

Verify the Protected Output

After you build the project, verify that Dotfuscator protected the assemblies.

One way to check the result is to compare the unprotected and protected assemblies with a decompilation tool. For example, you can compare the GettingStarted sample before and after integrating Dotfuscator.

With default protection, Dotfuscator can apply protections such as Control Flow obfuscation and Renaming obfuscation. The current article explains that Control Flow obfuscation makes decompiled code harder to understand, while Renaming obfuscation replaces method and type names with shorter, less meaningful names.

Note: The default settings are a starting point. You can configure stronger protection after the first successful build.

Archive Report Files

Dotfuscator creates report files in the DotfuscatorReports directory. These files are useful when testing, releasing, and supporting a protected app. For example, Renaming.xml helps decode obfuscated stack traces produced by the app.

Archive the report files for every release build. If your team uses a CI/CD pipeline, configure the pipeline to archive the contents of DotfuscatorReports after each build.

Store the report files in a secure, versioned location so you can use them later if you need to troubleshoot a protected release.

Warning: Dotfuscator report files can expose protection details. Never distribute them outside your organization. 

Next Steps

After you protect the GettingStarted sample successfully:

• Apply Dotfuscator to your own project.
• Configure stronger protection settings.
• Review the release checklist before distributing protected software.
• Set up Dotfuscator on your build agents if your team uses automated builds.

To apply Dotfuscator to different project types or build systems, see Protect Your App With MSBuild.