Skip to main content

Build Agents

Build Agents are machines that execute build steps for continuous integration and delivery (CI/CD) pipelines and automated build systems. These systems include cloud services and on-premises products like Jenkins, TeamCity, and Azure Pipelines (available both in the cloud-hosted Azure DevOps Services and the on-premises Azure DevOps Server, formerly known as Microsoft Team Foundation Server or TFS).

Systems may refer to them as "nodes" or "executors". Build agents are often virtual machines and are sometimes organized into dedicated "build farms".

This article explains how to set up, activate, and use Dotfuscator on build agents, as part of an automated build process.

Choosing an Installation Package

Dotfuscator has two installation packages: the Windows installer (.msi) and the NuGet package. 

  • Use either package to install Dotfuscator onto Windows machines. 
  • For macOS and Linux machines, only the NuGet package can be used. 
  • Dotfuscator's capabilities vary depending on the package you use and the operating system Dotfuscator runs on.

Review the table below to compare the two installation packages:

Installation package Windows Installer NuGet package
Installation OS Windows Windows macOS / Linux
Components Installed
MSBuild targets and tasks ✅ ✅ ✅
Command line interface ✅ a ✅ b ✅ b
Config Editor ✅ ❌ ❌
Installation
Requires admin rights? ✅ ❌ ❌
Deploys to well-known locations? ✅ ❌ ❌
Can be provisioned at build time? ❌ ✅ ✅
Can have multiple versions side-by-side? ❌ ✅ ✅
Can protect code that targets...
.NET Framework ✅ ✅ ❌
.NET 5 / .NET Core / .NET Standard ✅ ✅ ✅
Xamarin Android / Xamarin iOS / Mono ✅ ✅ ✅
MAUI Android ✅ ✅ ✅
  • a Runs on .NET Framework 4.7.2 or higher.
  • b Runs on .NET 6 or higher.

When to Use Each Package

  • The NuGet package works on any supported OS (Windows, macOS, or Linux). 
  • You can provision the package one time per build agent. For dynamically provisioned agents (allocated and deallocated with each build job, e.g., Microsoft-hosted agents on Azure Pipelines), configure your build scripts to provision the package at the start of every job.
  • If your Windows build agents are pre-provisioned (long-running, shared across jobs), you can run the Windows installer once per agent. Use the Windows installer if it is more convenient for your environment.

Installing with the Windows Installer

Install Dotfuscator on a build agent for which you have administrator access using the same instructions for development machines.

If you followed the recommended Protect Your App instructions, you can immediately build your Dotfuscator-integrated MSBuild projects (.csproj, .vbproj, etc.) on your build agents after completing the Windows installer. This applies even if you use a custom MSBuild project that calls Dotfuscator via its Dotfuscate task. If your build encounters errors finding Dotfuscator's targets or tasks, see Troubleshooting.

The Dotfuscator command line interface (CLI) provisioned by the Windows installer is a full .NET Framework console app (.exe). You can call it as dotfuscator.exe (it is usually on the PATH) or locate it using the DOTFUSCATOR_HOME environment variable. If you are using Azure Pipelines, you can instead call the command line interface by Using the Azure Pipelines Extension.

Installing with the NuGet Package

Use the Dotfuscator NuGet package to install the NuGet package on your build agents:

  1. Host the package in a directory or NuGet feed within your organization.
  2. Provision the NuGet package on the build agent.
  3. Activate Dotfuscator on the build agent.

After activation, you can use Dotfuscator on your build agents.

 Note: If you use dynamically-provisioned build agents, you can follow step 1 once, and then configure your automated build scripts to perform steps 2 and 3 at the start of every build job. This ensures the build job can use Dotfuscator, even when running on an agent allocated specifically for the build job.

Hosting the NuGet Package

The Dotfuscator NuGet package is distributed privately to licensed Dotfuscator Professional users, for internal use within their organizations. 

  1. Go to the Dotfuscator Downloads page to download Dotfuscator Professional's NuGet Package (.nupkg).
  2. Host the file within your organization to make it available to your developers and build agents. You can use a dedicated artifact repository that supports NuGet, or a simple directory in a shared filesystem location.

The package can be hosted in a NuGet feed provided by a dedicated artifact repository (also known as a package repository or software repository). Compatible systems include on-premises software like Artifactory and cloud-based services like Azure Artifacts. You must ensure the Dotfuscator NuGet package is only available to licensed users in your organization, even if you use a cloud-based service.

You can also host the NuGet package by using a directory as a local NuGet feed. The directory needs to be accessible to your build agents, such as on a network share - e.g., \\server\share\nuget - or in your project's source tree in a version control system. You can use the nuget add command to create the directory, or you can just create a directory and copy the .nupkg into it.

 Do NOT host this NuGet package in a publicly-accessible location such as a public NuGet feed. Doing so is a violation of your license to use the software.

Once you've hosted the NuGet package, note the NuGet feed URL. If you are using an artifact repository, consult its documentation and user interface to obtain the appropriate URL. If you are using a filesystem directory, the URL is the path to that directory.

Provisioning the NuGet Package

Once you host the Dotfuscator NuGet package, provision it onto your build agent. There are several ways to do this, explained in the tabs below.

nuget.exeInstall

You can use the install command of the nuget command line interface to provision the package.

  1. Ensure that the nuget CLI is available on your build agent. It's often available on the PATH, so you can run the nuget help command to verify it is installed.

    • On macOS, if Visual Studio for Mac is installed, you can run the nuget CLI at this path:

      /Library/Frameworks/Mono.framework/Commands/nuget
    • Some automated build systems may provide a way to install the NuGet CLI onto the build agent. For example, Azure Pipelines has the NuGet Tool Installer task.
    • If the NuGet CLI isn't installed, you can follow these instructions to install it.

  2. Use the NuGet CLI's install command:

    nuget install PreEmptive.Protection.Dotfuscator.Pro[.Eval] -Version 7.2.0 -OutputDirectory "{out dir}" -ExcludeVersion -Source "{feed url}"

    Where:

    • [.Eval] is .Eval if you are evaluating Dotfuscator Professional and is the empty string otherwise.
    • {out dir} is where the NuGet package will be extracted.
    • {feed url} is the NuGet feed URL noted when hosting the package.

This installs Dotfuscator to {out dir}/PreEmptive.Protection.Dotfuscator.Pro[.Eval]. Note this installation directory for later.

Unzipping

A NuGet package file, .nupkg, is actually a .zip archive which has been renamed. You can extract it like any .zip file.

If you are hosting the NuGet package in a dedicated artifact repository, consult the repository's documentation for how to download the .nupkg file. (You may be able to automate this process using curl or similar tools.)

If the NuGet package is hosted on a filesystem location, you can get the file directly from that location (the feed URL noted earlier).

Some extraction tools (like Windows Explorer) don't recognize the .zip archive unless it has that file extension; if so, copy the file to a new name before extracting it. Other tools (like 7-Zip) can extract directly from a .nupkg file.

The directory where you extract the NuGet package's contents is the installation directory. Note this installation directory for later.

NuGet Restore

You can create an MSBuild project that references the NuGet package, then restore the packages for that project.

 Warning: Adding Dotfuscator's NuGet package as a reference to a project does not automatically protect that project. You must integrate Dotfuscator into a project in order to protect it.

 

For this reason we recommend making a separate "stub" project that you use only to restore the NuGet package to a specific directory. After provisioning Dotfuscator this way, you can build your normal projects using the provisioned Dotfuscator.

To provision Dotfuscator with a NuGet restore:

  1. Create a project file like this one in a text editor (e.g., RestoreDotfuscator.csproj) and check it in to your version control.

    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="PreEmptive.Protection.Dotfuscator.Pro[.Eval]" Version="7.2.0" />
  </ItemGroup>

</Project>

    where [.Eval] is .Eval if you are evaluating Dotfuscator Professional and is the empty string otherwise.

  2. On the build agent, restore the project file's NuGet package using the dotnet CLI, nuget CLI, or another NuGet interface. The example below uses dotnet.

    dotnet restore --packages {out dir} --source {feed url} {project path}

    where:

    • {out dir} is where the NuGet package will be extracted.
    • {feed url} is the NuGet feed URL noted when hosting the package. (Other NuGet interfaces may require you to instead specify this as a source in a NuGet.config file.)
    • {project path} is the path to the project file you created in step 1.

This example installs Dotfuscator into {out dir}/PreEmptive.Protection.Dotfuscator.Pro[.Eval]/7.2.0. This is the installation directory; yours will vary depending on the exact restore command you use. Note your installation directory for later steps.

Before calling the included shell scripts, it may be necessary to mark them executable. This is usually done by calling chmod +x with the script location as an argument.

Activating the NuGet Package

You must activate Dotfuscator on your build agent before use. The recommendation is to set the DOTFUSCATOR_LICENSE environment variable to your license string. This causes Dotfuscator to activate itself when it runs. You can also pass the license string as an argument to Dotfuscator, such as by setting DotfuscatorLicense in a .dotfuscator.user.props file.

Some build systems have built-in ways to store license keys and other sensitive strings and then expose them in environment variables during a build. For instance, Azure Pipelines has secret variables. Using features like this can help keep your license key protected during a build.

While you're setting environment variables, you may wish to also set your Customer Feedback Options via the PREEMPTIVE_TELEMETRY_OPT_OUT variable.

Using the NuGet Package

Once you install and active Dotfuscator on a build machine, you can use it as part of your build. Your build steps must use Dotfuscator from the installation directory you noted during provisioning.

Examples are shown in the sections below for the MSBuild components and command line interface. If you followed the recommended Protect Your App instructions, then read the MSBuild Components section.

MSBuild Components

If you are using the MSBuild targets or tasks, you should override the DotfuscatorMSBuildDir property when building on a build agent. The value of the property should be {install dir}/tools/msbuilddir, where {install dir} is the installation directory.

You can do this in a number of ways:

  • By setting the DotfuscatorMSBuildDir environment variable.
  • By setting the DotfuscatorMSBuildDir property in a .dotfuscator.user.props file located in the user directory of the user which runs the build job.
  • By setting the DotfuscatorMSBuildDir property in a Directory.Build.props or Directory.Build.targets file located in an ancestor directory of your project's directory.
  • By setting the DotfuscatorMSBuildDir property in an argument when you call msbuild, dotnet, or a similar MSBuild-based step. Examples include:

    • Using the msbuild command line:

      msbuild YourSolution.sln -p:DotfuscatorMSBuildDir="{install dir}/tools/msbuilddir"

    • Using the dotnet command line:

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

    • In an Azure Pipelines step, using the YAML syntax's msbuildArgs input argument:

      - task: VSBuild@1
  displayName: 'Build solution **/*.sln'
  inputs:
    solution: '$(Parameters.solution)'
    msbuildArgs: '-p:DotfuscatorMSBuildDir="{install dir}/tools/msbuilddir"'
    platform: '$(BuildPlatform)'
    configuration: '$(BuildConfiguration)'
       Note: If you encounter build errors when using the NuGet package on Azure Pipelines, see Troubleshooting.

Command Line Interface

The Dotfuscator command line interface (CLI), when provisioned by the NuGet package, is a framework-dependent deployment of a .NET 6 console app (.dll). You can call it using the .NET Core CLI (dotnet):

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

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.

Additionally, there are scripts in the netcore directory allowing you to more naturally call the Dotfuscator command line in a way that is compatible across both the .NET Core and Full Framework command lines:

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

If you are using Azure Pipelines, you can instead call the command line interface using an extension for that build system; see Using the Azure Pipelines Extension.

Using the Azure Pipelines Extension

You can call the Dotfuscator command line from Azure Pipelines using the Dotfuscator Professional Command Line task instead of invoking the command line manually. Note that most Dotfuscator Professional users should follow the recommended Protect Your App instructions; if you followed these instructions, you do not need to call Dotfuscator's command line nor use this extension. This extension is only for those who used an alternative approach involving the command line interface.

For instructions on how to install and use the extension, see Dotfuscator Professional Build Task in the Visual Studio Marketplace.

 Note: When using the task, the Location of Dotfuscator application (dotfuscatorHome) input field should be empty if you provisioned with the Windows Installer. If you provisioned with the NuGet package, set this field to:
$(System.DefaultWorkingDirectory)/{install dir}/tools/programdir/netcore
where {install dir} is your installation directory, relative to your version control's root directory.
Was this article helpful?
日本語