NuGet Package
Dotfuscator Professional can be installed using a NuGet package which is privately distributed by PreEmptive. This installation method supports running Dotfuscator on macOS and Linux development machines. You can also use this method for Windows development environments, but we usually recommend using the Windows installer instead.
Build agents can also use the NuGet package for installation - see Build Agents for details.
About the NuGet Package
While you may be familiar with using NuGet to add third-party libraries from nuget.org to your projects, the Dotfuscator NuGet package works quite differently:
The package does not expose libraries for general programming use. Instead, the package contains Dotfuscator's various components which can be used as independent tools during a build.
You do not 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 not available on the public nuget.org feed. Instead, the package is distributed privately from PreEmptive, and must be hosted on a private feed within your organization.
The package's ID is PreEmptive.Protection.Dotfuscator.Pro
.
(For customers evaluating Dotfuscator Professional, add .Eval
to the end of this ID.)
This page discusses the private NuGet package which contains Dotfuscator itself. There is also a more traditional NuGet package available on nuget.org which contains Check Attributes. Your project can reference this NuGet package and use the provided attributes to annotate your code. When Dotfuscator runs, it recognizes these attributes in your compiled code and injects Checks accordingly.
System Requirements
To install Dotfuscator with the NuGet package, you will need a way to install NuGet packages to a local directory.
The easiest way is to use the NuGet command line interface (nuget.exe
), but you can also use a different NuGet interface or any tool capable of extracting ZIP files.
For details, see the Installation Instructions
The package itself has two sets of components, divided into two subdirectories. Each set of components has separate system requirements.
tools/msbuilddir
contains Dotfuscator's MSBuild components. Most developers should use these components, as they integrate into the normal build process of most .NET projects. You can read the requirements here.tools/programdir/netcore
contains the .NET Core 2.1 version of the command line interface. You can read the requirements here.
MSBuild Requirements
The requirements for running the MSBuild components installed by the NuGet package are:
- MSBuild - any of the following:
- MSBuild for .NET Framework: 4.0 or later, running on .NET Framework 4.7.2 or later
- MSBuild for .NET Core: 16.0 or later, with the .NET Core 2 (version 2.1.x or higher) runtime installed
- MSBuild for Mono: 16.0 or later, running on Mono 6.0 or later
The MSBuild components, when installed via the NuGet package, can be used in builds running on Windows, macOS, and Linux.
However, certain features, such as .pdb
file generation, require the full .NET Framework SDK (version 1.1 or later) which is exclusive to Windows.
Below are examples of development tools (IDEs, SDKs, etc.) which Dotfuscator supports when using the NuGet package.
Visual Studio (for Windows): 2012 and later.
Visual Studio Community, Professional, and Enterprise are supported.
You can integrate Dotfuscator into projects for .NET Framework, .NET Core, .NET Standard, and Xamarin.
Dotfuscator can run during builds started from the Visual Studio IDE as well as from the following command line tools that can be installed with Visual Studio: msbuild
(for .NET Framework) and dotnet
(for .NET Core).
Installing Visual Studio (with a .NET workload in VS 2017 and later) will also satisfy the .NET runtime and .NET SDK requirements.
Visual Studio for Mac: 2019 and later.
You can integrate Dotfuscator into projects for .NET Core, .NET Standard, Xamarin, and Mono.
Dotfuscator can run during builds started from the Visual Studio for Mac IDE as well as from the following command line tools that are installed with Visual Studio for Mac: msbuild
(for Mono) and dotnet
(for .NET Core).
Visual Studio Code: any version.
You can integrate Dotfuscator into any .NET-based project.
Dotfuscator can run during builds which are triggered through build tasks, if those build tasks call supported msbuild
and dotnet
tools.
Visual Studio Code does not include these tools; you will need to install them via an SDK or another IDE.
.NET Framework runtime: 4.0 and later.
You can integrate Dotfuscator into projects for .NET Framework and .NET Standard.
Dotfuscator can run during builds started from the .NET Framework msbuild
command line tool, on Windows only.
.NET Core SDK: 2.1 and later (latest patch versions)
You can integrate Dotfuscator into projects for .NET Core and .NET Standard.
Dotfuscator can run during builds started from the .NET Core dotnet
command line tool, on Windows, macOS, and Linux.
Mono SDK: 6.0 and later
You can integrate Dotfuscator into projects for Mono and .NET Standard.
Dotfuscator can run during builds started from the Mono msbuild
command line tool, on Windows, macOS, and Linux.
Command Line Interface Requirements
The requirements for running the command line interface installed by the NuGet package are:
- .NET runtime: .NET Core 2.1 or later
- Note You must have a .NET Core 2 runtime of 2.1 or later installed. For more information on how .NET Core selects what runtime to use see here. This limitation does not apply to the version used by processed applications or installed SDKs.
The command line interface, when installed via the NuGet package, can run on Windows, macOS, and Linux.
However, certain features, such as .pdb
file generation, require the full .NET Framework SDK (version 1.1 or later) which is exclusive to Windows.
Installation Instructions
Your organization may have already hosted the Dotfuscator NuGet package internally. If so, note the NuGet feed URL where the package is hosted.
Otherwise, you will need to download the NuGet package to your development machine.
Go to the Dotfuscator Downloads page and download Dotfuscator Professional's NuGet Package.
Copy the downloaded .nupkg
to a new directory and note the path to this directory as your NuGet feed URL.
Once the NuGet package is hosted or downloaded, you can provision it on your development machine. There are multiple ways to do this, shown in the tabs below.
nuget.exe
Install
The NuGet command line interface (CLI) can use the install
verb to provision Dotfuscator.
This CLI can be downloaded as nuget.exe
, suitable for running on Windows or under Mono.
If your machine is running macOS and has Visual Studio for Mac installed, you already have the NuGet CLI available at /Library/Frameworks/Mono.framework/Commands/nuget
.
Here is an example command for provisioning Dotfuscator:
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 the directory where the Dotfuscator NuGet package will be extracted.{feed url}
is the NuGet feed URL you noted earlier.
This installs Dotfuscator to {out dir}\PreEmptive.Protection.Dotfuscator.Pro[.Eval]
.
Note this installation directory for the next set of instructions.
Unzipping
The NuGet package (.nupkg
) file is actually a renamed ZIP file.
You can copy the .nupkg
file to a new name with the .zip
extension, and then unzip that copy into a new directory.
(If the NuGet package is hosted on an artifact repository in your organization, consult the repository's documentation to download the .nupkg
file.)
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.
When installed via NuGet this will likely be unnecessary as NuGet marks all files as executable.
After unzipping the package, the directory of unzipped contents is your installation directory.
Note this installation directory for the next set of instructions.
NuGet Restore
You can create a simple "stub" .NET project that references the Dotfuscator NuGet package. Then you can provision the package by using a NuGet restore command on the "stub" project.
For details, see NuGet Restore on the Build Agents page.
After provisioning, you will need to set some environment-specific settings.
Create a file named .dotfuscator.user.props
in your user directory (i.e., the directory found in the USERPROFILE
or HOME
environment variables) with the following content:
<!-- 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 you noted.{license string}
is your Dotfuscator Professional license key formatted as a license string. This will cause Dotfuscator's build integration to automatically activate itself each time it runs.
Now you can follow the Protect Your App instructions to integrate Dotfuscator into your build.
Installed Components
Dotfuscator's NuGet package contains the following components:
Component | Installation Location |
---|---|
MSBuild targets | {install dir}\tools\msbuilddir\PreEmptive.Dotfuscator.Common.targets |
MSBuild tasks (modern) | {install dir}\tools\msbuilddir\PreEmptive.Dotfuscator.Tasks.dll |
MSBuild tasks (legacy) | {install dir}\tools\msbuilddir\legacy\PreEmptive.Dotfuscator.Tasks.dll |
Command line interface | {install dir}\tools\programdir\netcore\dotfuscator.dll (.NET Core app) |
where {install dir}
is the Dotfuscator installation directory you noted in the Installation Instructions.