Use Dotfuscator on Build Agents

Build agents execute automated builds as part of continuous integration and continuous delivery (CI/CD) pipelines. You can install Dotfuscator on build agents to automatically protect your applications during the build process, regardless of the CI/CD platform you use.

This article explains how to install, license, and configure Dotfuscator on build agents. For platform-specific examples, see Integrate with Azure Pipelines and Integrate with Docker.

Before You Begin

Before configuring a build agent, make sure you have:

• Dotfuscator Professional.
• A valid Dotfuscator license.
• A CI/CD platform capable of running MSBuild or the Dotfuscator command-line interface.

Choosing an Installation Package

Dotfuscator is available as two installation packages:

• Windows Installer
• NuGet Package

Both packages support automated builds, but each is designed for different deployment scenarios.

Windows Installer

The Windows Installer is recommended for dedicated Windows build agents that are provisioned once and reused across multiple builds.

After installation, the MSBuild targets, MSBuild tasks, and command-line interface are available without additional setup.

NuGet Package

The NuGet package is recommended when:

• Building on macOS or Linux.
• Using ephemeral or cloud-hosted build agents.
• Building inside containers.
• Maintaining multiple Dotfuscator versions.

The NuGet package includes the MSBuild components and the cross-platform command-line interface.

Install Dotfuscator

Install Dotfuscator using the package appropriate for your environment.

Windows Installer

Install Dotfuscator on each build agent using the Windows Installer.

The installation places the MSBuild components in the standard MSBuild directory and makes the command-line interface available for automated builds.

For more information, see Installing Dotfuscator Professional.

NuGet Package

Download the PreEmptive.Protection.Dotfuscator.Pro NuGet package from the PreEmptive Downloads page.

Host the package in a private package repository that your build agents can access, such as:

• Azure Artifacts
• A private NuGet feed
• An internal package repository
• A local NuGet source

Important: Do not publish the Dotfuscator NuGet package to a public package feed.

Provision the package as part of the build before restoring packages or building the solution.

For more information, see Installing Dotfuscator Professional.

Activate Dotfuscator

Every build agent must have access to a valid Dotfuscator license.

The recommended approach is to provide the license during the build using one of the following methods:

• Setting the DOTFUSCATOR_LICENSE environment variable to your license string.
• Setting the DotfuscatorLicense MSBuild property in a .dotfuscator.user.props file.

If your CI/CD platform supports secret variables, store the license as a secure secret rather than checking it into source control.

For more information, see Activation.

Configure MSBuild

When using the NuGet package, MSBuild must know where the Dotfuscator targets are installed.

Set the DotfuscatorMSBuildDir property to the package's tools/msbuilddir directory.

You can configure this property by:

• Setting the DotfuscatorMSBuildDir environment variable.
• Adding the property to a .dotfuscator.user.props file.
• Adding the property to Directory.Build.props.
• Passing the property on the MSBuild command line.

For example:

dotnet build -p:DotfuscatorMSBuildDir="{install dir}/tools/msbuilddir"

If you installed Dotfuscator using the Windows Installer, this property is usually not required because the MSBuild components are installed in their standard location.

Use the Command-Line Interface

The Windows Installer includes the .NET Framework command-line interface. The NuGet package includes the cross-platform .NET command-line interface.

To run the NuGet version directly, execute:

dotnet "{install dir}/tools/programdir/netcore/dotfuscator.dll" {arguments}

Where:

• {install dir} is the path to the installation directory.
• {args} are arguments to the CLI, usually including the path to the Dotfuscator config file to build.

The package also includes scripts in the netcore directory for Windows, macOS, and Linux that allow you to call the Dotfuscator command line in a way that is compatible across both the .NET Core and Full Framework command line.

• dotfuscator is a bash shell script for use on Linux and macOS systems.
• dotfuscator.cmd is a batch script for use on Windows systems.

Choose an Integration Method

After installing Dotfuscator, integrate it into your build using one of the following interfaces:

For detailed instructions, see:

• Protect Your App with MSBuild
• Protect Your App Using the Command Line Interface

Platform-Specific Integrations

The following articles demonstrate complete CI/CD integrations:

Troubleshooting

MSBuild Cannot Locate Dotfuscator Targets

If MSBuild cannot locate PreEmptive.Dotfuscator.Common.targets, verify that:

• Dotfuscator is installed.
• The DotfuscatorMSBuildDir property points to the correct installation directory.
• The NuGet package has been provisioned before the build begins.

License Activation Fails

Verify that:

• The build agent has access to the internet if required by your license type.
• The license value is configured correctly.
• Secret variables are available to the build process.

Related Articles

• Protect Your App with MSBuild
• Protect Your App Using the Command Line Interface
• Integrate with Azure Pipelines
• Integrate with Docker
• Activation