Build Agents

Many teams build their software with a continuous integration and delivery (CI/CD) pipeline or some other kind of automated build system. Various solutions exist both as cloud services and as on-premises products. Examples include 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).

Such systems use independent machines to carry out build steps. These machines are usually called "build agents", but some systems may refer to them as "nodes" or "executors". Build agents are often virtual machines and are sometimes organized into dedicated "build farms".

This page 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. You can 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 which package you use and what operating system you run Dotfuscator on.

• ^a Runs on .NET Framework 4.7.2 or higher.

• ^b Runs on .NET Core 2.1 or higher.

The NuGet package can be used on any supported OS (Windows, macOS, or Linux). You can provision the package one time per build agent, or you can have your build scripts provision the package on the assigned agents every time a build runs. This latter case allows Dotfuscator to be available on build agents which are dynamically provisioned (allocated and deallocated with each build job), such as when using Microsoft-hosted agents on Azure Pipelines.

If your build agents run Windows and are pre-provisioned (long-running, shared across build jobs), you also have the option of running the Windows installer one time on each build agent. Depending on your environment, this may be more convenient compared to using the NuGet package.

Installing with the Windows Installer

To install Dotfuscator on a build agent for which you have administrator access, follow the same instructions used for development machines.

If you followed the recommended Protect Your App instructions, you should be able to build your Dotfuscator-integrated MSBuild projects (.csproj, .vbproj, etc.) on your build agents immediately after completing the Windows installer. This is also true if you have 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), when provisioned by the Windows installer, is a full .NET Framework console app (.exe). It will usually be on the PATH and can be called as dotfuscator.exe, or you can find the it via 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

You can install Dotfuscator on a build agent by using 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.

You will then be able to use Dotfuscator on your build agents.

Hosting the NuGet Package

The Dotfuscator NuGet package is distributed privately to licensed Dotfuscator Professional users, for internal use within their organizations. Go to the Dotfuscator Downloads page to download Dotfuscator Professional's NuGet Package (.nupkg).

To make the NuGet package available to your developers and build agents, you will need to host the file within your organization. You can use a dedicated artifact repository which supports NuGet, or you can simply create a 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 will need 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.

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 the Dotfuscator NuGet package has been hosted, you can provision the package onto your build agent. There are several ways to do this, explained in the tabs below.

nuget.exe Install

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

1. First, 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 6.0.1 -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) won't recognize the .zip archive unless it has that file extension; if so, you will need to 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.

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="6.0.1" />
     </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]\6.0.1. This is the installation directory; yours will vary depending on the exact restore command you use. Note your installation directory for later steps.

Activating the NuGet Package

Dotfuscator must be activated on your build agent before use. We recommend setting the DOTFUSCATOR_LICENSE environment variable to your license string, which will cause 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 Dotfuscator is installed and activated on a build machine, you can use it as part of your build. Your build steps will need to 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 Core 2.1 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.