Installing Dotfuscator Professional

Use this article to install Dotfuscator Professional on a development machine or build environment.

Dotfuscator Professional supports two installation methods:

• Windows installer for Windows environments.
• NuGet package for Mac or Linux. 

The installation method you choose depends on your operating system, development environment, and workflow.

Before installing Dotfuscator Professional:

1. Verify that your application framework and development tools are supported.
2. Verify that the machine that runs Dotfuscator meets the system requirements.

For more information, see Supported Frameworks and Development Tools and System Requirements.

Choose an Installation Method

Install With the Windows Installer

The Windows Installer installs Dotfuscator Professional on Windows and includes the Dotfuscator Config Editor.

To install Dotfuscator Professional using the Windows Installer, do the following:

1. Go to the Dotfuscator Downloads page.
2. Download the Dotfuscator Professional Installer.
3. Run the installer on your development machine with administrator privileges.
4. Review and accept the terms in the End-User License Agreement section.

5. Choose an installation type:   

   • Select Complete installation to install all features
   • Select only specific features

   Note: If you opt for a partial installation, ensure the MSBuild Components feature is enabled, as most projects use Dotfuscator with these components.

6. Continue and select Install.
7. Wait for the installation to complete.
8. Select Finish to close the installation wizard.

If you have not yet activated Dotfuscator on the machine, the activation tool launches automatically. 

After installation, Dotfuscator Professional is available on the local machine and can be integrated with supported Visual Studio projects and build processes.

For more information, see Activation. 

Installed Components

The Windows Installer deploys the following components:

Where:

• $(MSBuildProgramFiles32) is a reserved MSBuild property pointing to the C:\Program Files (x86) directory on 64-bit versions of Windows and C:\Program Files on 32-bit versions.
• {app dir} is the directory where you chose to install Dotfuscator Professional.

For more information, see Reserved and Well-Known Properties.

DOTFUSCATOR_HOME Variable

The Windows installer adds the DOTFUSCATOR_HOME system environment variable. This variable contains the Dotfuscator installation directory.

The installer also appends %DOTFUSCATOR_HOME% to the PATH environment variable, unless the PATH variable is too long. If this is the case during installation, reduce the PATH variable’s length and then append %DOTFUSCATOR_HOME% manually.

For side-by-side installations, DOTFUSCATOR_HOME refers to the Dotfuscator version that was installed most recently. To use another installed version, update the system environment variable to point to that version’s installation directory.

When you uninstall Dotfuscator, the installer removes DOTFUSCATOR_HOME and removes it from PATH only if the path matches the version being uninstalled. If you have other Dotfuscator versions installed, reconfigure DOTFUSCATOR_HOME to point to the version you want to use.

Install With the NuGet Package

PreEmptive privately distributes a NuGet package for installing Dotfuscator Professional on macOS and Linux development machines.

It is possible to use this method for Windows development environments, but the Windows installer is typically recommended for Windows development machines.

About the NuGet Package

The Dotfuscator NuGet package works differently from typical project dependencies. Key characteristics of the Dotfuscator NuGet package include:

• The package does not expose libraries for general programming use.
• The package contains Dotfuscator's various components, which act as independent tools during a build.
• You do not need to add a reference to the Dotfuscator NuGet package in your project. Instead, you explicitly install the package to a directory and have your builds use the extracted components in that directory.
• The package is distributed privately by PreEmptive and is not available on the public nuget.org feed.
• You must host the package on a private feed within your organization.

Package Identifiers

Install the NuGet Package

To install the package, use any of the following:

• The NuGet command-line interface, nuget.exe
• Any tool capable of extracting ZIP files
• NuGet Restore

Install the package to a local directory that is accessible to your build process.

1. Go to the Dotfuscator Downloads page.
2. Download the Dotfuscator Professional's NuGet Package.
3. Copy the downloaded .nupkg to a new directory.
4. Note the path to this directory as the {feed url}.

5. Provision the package in your development machine:

   nuget.exe Install

   Use the install command to download and extract the package to a specific directory {out dir}. For example, the following command installs Dotfuscator Professional version 7.1.4 to {out dir}/PreEmptive.Protection.Dotfuscator.Pro:

   nuget install PreEmptive.Protection.Dotfuscator.Pro -Version 7.1.4 -OutputDirectory 
   "{out dir}" -ExcludeVersion -Source "{feed url}"

   For evaluation licenses, use:

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

   Note: Make sure you specify the correct Dotfuscator Professional version when using the install command.

   For more information, see NuGet CLI Reference.

   Extract ZIP files

   The NuGet package (.nupkg) file is actually a renamed ZIP file.

   1. Copy the .nupkg file to a new name with the .zip extension
   2. Unzip that copy into a new directory.
   3. Note the directory of unzipped contents. This is the installation directory.  

   Note: If the NuGet package is hosted on an artifact repository in your organization, consult the repository's documentation to download the .nupkg file.

   NuGet Restore

   1. Create a simple "stub" .NET project that references the Dotfuscator NuGet package
   2. Provision the package using the >nuget restore command.
6. Mark the included shell scripts as executable with the chmod +x command, including the script location as the argument.
7. Create a file in your user directory and name it .dotfuscator.user.props

8. Include the following content in the new file:

   <!-- This is an MSBuild properties file for projects which use Dotfuscator's MSBuild components.
        For details, see <https://www.preemptive.com/dotfuscator/pro/userguide/en/interfaces_msbuild.html#user>.
   -->
   <Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
       <PropertyGroup>
           <!-- Path where Dotfuscator's MSBuild components are installed via the NuGet package. -->
           <DotfuscatorMSBuildDir>{install dir}/tools/msbuilddir</DotfuscatorMSBuildDir>
           <!-- License string for Dotfuscator. -->
           <DotfuscatorLicense>{license string}</DotfuscatorLicense>
       </PropertyGroup>
   </Project>
   

   Where:
   
   {install dir} is the absolute path to the Dotfuscator installation directory.
   {license string} is your Dotfuscator Professional license key formatted as a license string. This causes Dotfuscator's build integration to automatically activate itself each time it runs.

After installation, Dotfuscator Professional is available on the local machine.

Note: When attempting to build Dotfuscator on Ubuntu 22, you may encounter a specific System.attributeTargets.System.Runtime error. For more details on this error and how to fix it, see Troubleshooting.

Installed Components

Dotfuscator's NuGet package contains the following components:

Where {install dir} is your Dotfuscator installation directory.

Next Steps

After installing Dotfuscator Professional:

1. Activate your license.
2. Understand how Dotfuscator protects your app.
3. Protect your first application:
   • With the Config Editor
   • With MSBuild
   • With the Command Line Interface
4. Review available enhanced protection features.

Related Articles

• System Requirements
• Supported Frameworks and Development Tools
• Activation
• MSBuild
• Command Line Interface
• The Config Editor
• Obfuscation Attributes Reference
• The PreMark Editor
• Tamper Check