If you are processing a package that contains third-party assemblies, we generally recommend that you do not obfuscate the third-party assemblies themselves. See Excluding or Including Package Assemblies from Processing to learn how to exclude these third-party assemblies.

Note that this is done automatically when integrating Dotfuscator into a Visual Studio project via the MSBuild targets.

Visual Studio Build / MSBuild Errors

This section is for issues that occur when a Visual Studio or MSBuild project is using Dotfuscator's MSBuild targets, such as when following the instructions on Protect Your App.

Is Dotfuscator imported but not installed?

If the project file (e.g., .csproj, .vbproj) imports the MSBuild targets, such as with the <Import> tag:

  <Import Project=".../PreEmptive.Dotfuscator.Common.targets"/>

then the MSBuild targets file must be installed before the project will load in Visual Studio and build in MSBuild. You can install via the Windows installer or the NuGet package.

If you have installed Dotfuscator but are still unable to load or build the project, check the directory from which you are trying to import the targets file, which should appear in error messages when you try to load or build the project.

error MSB4019: The imported project "C:\Program Files\MSBuild\PreEmptive\Dotfuscator\7\PreEmptive.Dotfuscator.Common.targets" was not found.
Confirm that the path in the <Import> declaration is correct, and that the file exists on disk.

The correct directory varies by installation method; see Locating the MSBuild Components for an explanation.

Additionally, note that this User Guide recommends using an MSBuild property, DotfuscatorMSBuildDir, to store the path of the directory, so that it can vary for the same project across multiple developer and build environments. For instance, we recommend the following <Import> statement:

  <Import Project="$(DotfuscatorMSBuildDir)/PreEmptive.Dotfuscator.Common.targets"/>

If your project is using DotfuscatorMSBuildDir or a similar a property and the directory in the error message appears to be wrong, check how the property is being set. Places it can be set include:

In the project file itself. The following example sets the property, if it has not already been set, to the directory where the Windows Installer places the targets file.

<PropertyGroup>
  <DotfuscatorMSBuildDir Condition="'$(DotfuscatorMSBuildDir)' == ''">$(MSBuildProgramFiles32)/MSBuild/PreEmptive/Dotfuscator/7</DotfuscatorMSBuildDir>
</PropertyGroup>

In another MSBuild property or targets file imported by your project file. The following example imports a .dotfuscator.user.props file found in the current user's directory (given by the USERPROFILE or HOME environment variables):

<Import Project="$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props"
        Condition="Exists('$([System.Environment]::GetFolderPath(SpecialFolder.UserProfile))/.dotfuscator.user.props')"/>

In a Directory.Build.props or Directory.Build.targets file.
In an environment variable, which are exposed in MSBuild as properties. (Keep in mind that property names are not case-sensitive.)
As a command line variable when calling msbuild or dotnet.

Is Dotfuscator causing the issue?

Build a configuration of your project that does not have Dotfuscator enabled. If the error persists, the issue may be caused by something other than Dotfuscator.

Get More Information

If you get a generic error saying that Dotfuscator failed or exited with an error code, get more information by:

Setting your build verbosity in Visual Studio (or via the -v switch to MSBuild) to Normal (or more detailed level) in order to see Dotfuscator's build output in the project's build output.
Setting the build progress setting in your Dotfuscator config file to Verbose in order to see additional output from Dotfuscator.

Dotfuscator MAUI Projects

When you build a MAUI project targeting multiple platforms, the number of parallel projects builds must be limited to one.

DotfuscatorIncludeAsInput Errors and Warnings

This section covers the more common errors and warnings caused by the DotfuscatorIncludeAsInput project property and metadata. For more information on using the feature, please see Controlling Which Assemblies Are Protected.

References to the assembly "X.dll" have conflicting 'DotfuscatorIncludeAsInput' metadata.

This error occurs if two Reference Items referring to the same assembly have different DotfuscatorIncludeAsInput values. For example, if Project File A contains:
```
<Reference Include="ExternalAssembly">
  <HintPath>../path/to/the/assembly/ExternalAssembly.dll</HintPath>
  
  <DotfuscatorIncludeAsInput>true</DotfuscatorIncludeAsInput>
</Reference>
```
And Project File B contains:
```
<Reference Include="ExternalAssembly">
  <HintPath>../path/to/the/assembly/ExternalAssembly.dll</HintPath>
  
  <DotfuscatorIncludeAsInput>false</DotfuscatorIncludeAsInput>
</Reference>
```
Then the "Conflicting 'DotfuscatorIncludeAsInput' metadata" error will be emitted.

To resolve this issue, you must decide whether the assembly should be protected, and change the value of the offending DotfuscatorIncludeAsInput metadata to the correct value wherever it is referenced.
Some Projects that reference 'X.csproj' (directly or indirectly) have the 'DotfuscatorIncludeAsInput' property set to 'false', while other such projects do not.

This warning is issued when a project is referenced both by a protected assembly and one that has been excluded from obfuscation.

For example, suppose Projects A and B both reference Project C, where A is protected and B is unprotected. By default, Dotfuscator would protect Project C because it is referenced by a protected project. However, this could cause issues with B's references to C if renaming is enabled because B would try to reference a method or property that has been renamed.

To avoid any issues, you should either ensure that Library Mode is enabled for the shared project or exclude the shared project from Dotfuscator:
```

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <DotfuscatorIncludeAsInput>false</DotfuscatorIncludeAsInput>
  </PropertyGroup>
</Project>
```

DotfuscatorIncludeAsInput was set on ProjectReference '../ProjB/ProjB.csproj' in project 'ProjA.csproj', but Dotfuscator does not honor this metadata on ProjectReference items.

This error is issued when you add the DotfuscatorIncludeAsInput metadata to a ProjectReference item. Currently, this feature is not supported. To exclude the project from protection, remove the DotfuscatorIncludeAsInput metadata from the ProjectReference item:

<!-- In ProjA.csproj -->
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ItemGroup>
    <ProjectReference Include=".../path/to/ProjectFile.csproj">
      <!-- Remove the following line: -->
      <DotfuscatorIncludeAsInput>false</DotfuscatorIncludeAsInput>
    </ProjectReference>
  </ItemGroup>
</Project>

Then, in the project that was referenced, add the DotfuscatorIncludeAsInput Property to any PropertyGroup element:

<!-- In ProjB.csproj -->
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <!-- Add the following line: -->
    <DotfuscatorIncludeAsInput>false</DotfuscatorIncludeAsInput>
  </PropertyGroup>
</Project>

DotfuscatorIncludeAsInput was set on PackageReference 'PackageName' in project 'Proj.csproj', but this version of Dotfuscator does not support including NuGet packages as inputs.

This error is issued when you add the DotfuscatorIncludeAsInput metadata to a PackageReference item. Currently, protecting assemblies originating from referenced NuGet packages is not supported. Please remove the DotfuscatorIncludeAsInput metadata from the PackageReference item:
```

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ItemGroup>
    <PackageReference Include="PackageName" Version="1.2.3">
      
      <DotfuscatorIncludeAsInput>true</DotfuscatorIncludeAsInput>
    </PackageReference>
  </ItemGroup>
</Project>
```
Note: If you are making a NuGet package through a Visual Studio project, you can still integrate Dotfuscator's MSBuild targets into that project, and your assemblies will be protected before being packaged into the NuGet package.

Dotfuscator Processing Errors

This section is for issues that occur when Dotfuscator processes an app.

Dotfuscator fails to protect Nullable Reference Types

To fix this issue add force_nuget_tools to the Dotfuscator's config file as a global option:

  <dotfuscator version="2.3">
    <global>
      <!--other option tags-->
        <option>force_nuget_tools</option>
    </global>
      <!-- some other tags-->
  </dotfuscator>

This option forces Dotfuscator to use newer versions of ILasm and ILdasm NuGet packages instead of relying on libraries shipped with .NET Framework 4.x.

Note: This option only applies when Dotfuscator runs on Windows, targeting .NET Framework.

Dotfuscator can't find a reference assembly

Run from the command line with -v -e -p=bindlog=true for additional info about where Dotfuscator is looking.
Add missing paths to the User Defined Assembly Load Path in the Dotfuscator config XML or through the Dotfuscator Config Editor's Settings Tab.

Dotfuscator can't find ILasm/ILdasm

This section addresses the following errors and warnings:

Could not find suitable tools [ILdasm] for "C:\Sample\SampleApp.dll". See the Troubleshooting section of the Dotfuscator User Guide.
Build Error.

Loading C:\Sample\SampleApp.exe
Could not find a compatible version of ildasm to run on assembly C:\Sample\SampleApp.exe.  This assembly was originally built with .NET Framework v4.0.30319.
Build Error.

WARNING: Encountered an invalid path/paths while probing for tools. The paths were "C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools\x64\" and ildasm.exe: The error was "Illegal characters in path.". Ignoring and continuing search. For more detail, define a config property named "toollog" and run Dotfuscator again.

These messages indicate an issue with Dotfuscator finding the IL disassembler and assembler tools (ILdasm and ILasm) it needs to process a certain assembly. For details on how Dotfuscator finds these tools, see Finding External Tools.

Here are ways to investigate and solve these kinds of issues:

To enable additional logging to get more information on the issue, re-run the Dotfuscator build after modifying your Dotfuscator config file to set build progress to Verbose and add a property named toollog with any non-blank value.
- Alternatively, if you are running from the command line, add the arguments -v -p:toollog=true.
- If you are building via MSBuild or Visual Studio, you may need to increase the MSBuild verbosity as well.
- The additional logging will begin with LOG: and include information about the assembly Dotfuscator is processing, as well as the methods by which it is trying to find the tools.
If you are running Dotfuscator on Windows and are protecting an assembly targeting the Windows-only .NET Framework, ensure that you have installed a suitable .NET Framework SDK.
If you are running Dotfuscator on macOS or Linux, or if you are protecting a .NET 5+, .NET Core 3+, .NET Standard 2.1, or Xamarin assembly, ensure that you have Internet access.
If you already know of the correct ILdasm and/or ILasm for Dotfuscator to use, see Explicitly Specifying the Tool Locations.

If you have reviewed the logging output from the build and are still unsure of what to do to fix the issue, please contact support for additional help.

ILdasm/ILasm exits with error code 127

If Dotfuscator errors with the following message when running on Linux:

ildasm returned 127

Then you might be missing a required dependency library. To determine which library is missing, check your build output for a message such as:

error while loading shared libraries: libunwind.so.8: cannot open shared object file: No such file or directory

In this example, the libunwind library needs to be installed.

See NuGet Package for Dotfuscator's full system requirements, including dependency libraries required for use on Linux.

Get a Dotfuscator Stack Trace

In the case of Dotfuscator errors, get a Dotfuscator stack trace by running from the command line with options -v -e.

DotfuscatorAndroidSigningCertFingerprint Error

Error : To inject Tamper Check into a Xamarin Android application, the signing certificate's SHA-1 fingerprint must be specified.
Please set the MSBuild property DotfuscatorAndroidSigningCertFingerprint to this value.

This error can be fixed by specifying the SHA-1 fingerprint of the certificate used to sign the application. There are two ways to specify the value:

If you have Dotfuscator integrated using our MSBuild targets file, set the value of DotfuscatorAndroidSigningCertFingerprint property in the project file of your Xamarin Android app. Refer to the Xamarin section on the Protect Your App page for an example of where to set the property in your project file.
If you are integrated with Dotfuscator another way, set the value with a new config property called AndroidSigningCertFingerprint using the Dotfuscator Config Editor.

Input mapping file cannot be honored

Error: The input mapping file cannot be honored for the listed methods. The current configuration requires that they all have the same name, but they have different names in your input map file. Please see 'Troubleshooting' in the user guide for more information.

Error: The input mapping file cannot be honored for the listed method. The current configuration doesn't allow it to be renamed, but it has a new name in your input map file. Please see 'Troubleshooting' in the user guide for more information.

If you are seeing this error you are using incremental obfuscation with a map file that was created with the Explicit Method Overrides setting enabled. Before the setting was removed, it was on by default if your config file version was less than v2.2 or if <option>explicitoverrides</option> was present in your config file when the map file was created.

To fix this error, you must stop using incremental renaming with your current input mapping file. Note however, the names between the current map file and the new map file will differ.

If you must keep using the same names from your input map file, continue using Dotfuscator 4, and ensure that any new projects you protect with Dotfuscator 4 don't use incremental renaming with the Explicit Method Overrides feature enabled.

False Positive Xamarin Tamper Check

If you are testing a Xamarin Tamper Check and the app is always reacting like it is tampered even when it wasn't, check that the DotfuscatorAndroidSigningCertFingerprint matches the SHA-1 fingerprint of the certificate used to sign the app.

Also, if you are using the default keystore certificate, the SHA-1 fingerprint varies by host so configuring the value of DotfuscatorAndroidSigningCertFingerprint with the fingerprint from one host, and then building on a different host will cause the app to always appear tampered. If you want to continue using the default keystore certificate, you should make sure DotfuscatorAndroidSigningCertFingerprint is configured with the SHA-1 fingerprint of the default keystore certificate on the host the app is built on.

Activation Errors

This section is for issues that occur when activating Dotfuscator.

Dotfuscator Not Activated

You must activate Dotfuscator Professional in order to execute command line builds. Run the Dotfuscator Config Editor to enter your License Key.

This error occurs if you have not yet activated Dotfuscator on this machine. See Activation for details.

Serial Number Previously Used

This serial number (...) has previously been used to register.  Please contact support@preemptive.com for registration assistance or to purchase additional licenses.

This error occurs when you attempt to activate Dotfuscator but your license does not permit activating on additional machines.

If this error appears in an automated build log, you are probably activating Dotfuscator via the DOTFUSCATOR_LICENSE environment variable or an argument. If the build runs on dynamically provisioned build agents, then each build job will register a new machine for the license. You must use a Floating License in this situation; other license types will produce the error above.

For more information on licensing, contact PreEmptive Solutions.

Internet Connection Issues

There is a problem reaching the activation server: "...". This license type requires access to the PreEmptive activation server before a build. Contact PreEmptive support for help.

Error: Could not verify the subscription for this license. "..." This license type requires access to the PreEmptive subscription server before a build. Contact PreEmptive support for help.

These errors occur due to network issues contacting PreEmptive Solutions' servers when activating or when running a build using a Floating License. An Internet connection is required in these cases, though Dotfuscator will re-attempt a failed connection once before erroring.

Activation Tool Issues

Activating via the Windows Installer or the Config Editor uses the Dotfuscator Activation Tool. The Activation Tool works by launching a web browser to preemptive.com, where you can log in and activate your installation of Dotfuscator. Once you complete the activation process in the browser, the browser sends the necessary information back to the Activation Tool so that it can verify and save the activation.

The following subsections detail how to resolve issues that may arise from the Activation Tool.

Activation Tool shows Windows Firewall dialog

In order for the Activation Tool to receive information from the browser, it listens on a TCP port for the localhost hostname. This can trigger a Windows Security Alert dialog with the following message:

Windows Defender Firewall has blocked some features of Node.js: Server-side JavaScript on all public and private networks.

The dialog, shown below, refers to part of the Activation Tool, client-activation-bridge-win.exe, which runs using Node.js.

As the Activation Tool only listens on localhost, it does not require a firewall exception.

This dialog can be safely dismissed by doing the following:

Uncheck all checkboxes.
Click the Cancel button.

Activation Tool does not proceed after the browser process is complete

While the Activation Tool is waiting for information from the web browser, it displays this screen:

However, if the browser's HTTP request to the Activation Tool is blocked or otherwise fails, the tool will continue showing the screen above even when the browser has reported its phase of the activation process is complete.

To address this:

In the web browser's success message, look for the Activation Token and copy it to your clipboard.
In the Activation Tool, click the hyperlink at the bottom of the window labeled click here to activate manually.
On the screen that appears, enter the activation token into the form and click Activate.

Runtime Errors

General Advice

Most apps, when protected, behave identically to their unprotected versions (barring any added Checks). However, there are some cases where Dotfuscator's obfuscation can cause runtime issues. Dotfuscator's Smart Obfuscation feature can detect some of these cases with static analysis, but others require manual configuration.

Runtime errors are often related to Renaming obfuscation. For instance, if code passes a string containing the name of a method to a reflection API, that call may fail after protection because Dotfuscator renamed the method but the string still has the old name. In this case, you can configure Dotfuscator to exclude the method from renaming. For a case study of discovering runtime issues and applying the appropriate renaming exclusions, see Identify Renaming Exclusions.

Similar problems can arise if Dotfuscator's Removal feature is enabled but static analysis cannot identify all of the code that will be used at runtime. To address this kind of problem, you can configure Dotfuscator to always include specific methods in the protected assembly.

Dotfuscator's Removal and Root Check features are not supported for MAUI in Linux environments.

Which transform is causing the problem?

Try to determine which transform is causing the problem:

Does it work when all obfuscation transforms are turned off?
Does it work with Library Mode enabled on all input assemblies?
Does it work with Transform XAML turned off on all input assemblies?
Runtime errors are almost always related to Renaming:
- Dependency Properties: are the property and all backing methods excluded from renaming?
- Does it work with the Property Exclusion Catch-All custom rule?
```
<type name=".\*" regex="true">
<propertymember name=".\*" regex="true"/>
</type>
```

Check the Warnings Tab

Are all of the warnings on the Warnings tab accounted for?

If your Dotfuscator build resulted in warnings, you will see them on their own tab in the Build Output section at the bottom of the Config Editor.

Catch Runtime Exceptions

Catch runtime exceptions and display them in a message box to see what is actually going wrong.

Improving Protection

For a detailed look at improving Dotfuscator's protection, see Enhance Protection.

Why were so few things renamed?

If your assembly is in Library Mode then Dotfuscator will not rename anything that is part of its publicly-available interfaces.

You can turn off Library Mode:

if your assembly is not meant to be available to other assemblies as a library
or, if you process the library along with all of its dependent assemblies in the same Dotfuscator config

Note: Remember that Library Mode is a per-assembly setting. You could have a scenario where some of your assemblies need Library Mode, but others can get the more powerful obfuscation that comes from turning it off.

Why isn't my transform running?

Maybe you went to one of the transform tabs (such as "Rename", "Control Flow", or "String Encryption") and configured the options for the transform, but when you build the Dotfuscator config, the transform does not seem to take effect.

It is possible that the transform itself is turned off.

Go to the "Settings" tab.
Select "Global Options" in the left-hand navigation panel.
Look at the "Feature" section in the right-hand panel.

Note: The properties to turn on and off the transforms are expressed as double negatives! So setting "Disable Control Flow" to Yes turns that transform off whereas setting it to No turns the transform on!

Build Agents

Restoring NuGet Packages from a Solution

After integrating Dotfuscator into your Azure Pipelines build, one of your build steps may start to fail. This could be an issue where NuGet fails to correctly restore the solution's packages despite the NuGet pipeline step succeeding. To see if this is the case, expand the console output of the NuGet Restore pipeline step and look for the following error message:

error MSB4019: The imported project "PreEmptive.Dotfuscator.Common.targets" was not found. Confirm that the path in the <Import> declaration is correct, and that the file exists on disk.

In this case, MSBuild is unable to find the Dotfuscator Targets file and exits before it can generate the project's dependency list. To resolve this issue, you will need to provide MSBuild with the location of the Dotfuscator Targets file on the build server.

You can use the NUGET_RESTORE_MSBUILD_ARGS environment variable to pass the correct location to MSBuild. To do so, add the following environment variable to your Azure Pipelines job:

Name: NUGET_RESTORE_MSBUILD_ARGS
Value: -p:DotfuscatorMSBuildDir="<install dir>/PreEmptive.Protection.Dotfuscator.Pro/tools/msbuilddir"
- Where <install dir> is the path to the Dotfuscator Targets file on the build server.

For more information about Azure Pipelines Variables, see the Microsoft Documentation. For more information on using Dotfuscator with build agents, see this section on Build Agents.