Troubleshooting
- General
- Are you using the latest version of Dotfuscator?
- Are all third-party assemblies excluded from obfuscation?
- Visual Studio Build / MSBuild Errors
- Is Dotfuscator imported but not installed?
- Is Dotfuscator causing the issue?
- Get More Information
- .NET Core and .NET Standard Build Errors
- Dotfuscator Processing Errors
- Dotfuscator can't find a reference assembly?
- Get a Dotfuscator Stack Trace
- DotfuscatorAndroidSigningCertFingerprint Error
- Activation Errors
- Runtime Errors
- General Advice
- Which transform is causing the problem?
- Is the application signed/resigned properly?
- Catch Runtime Exceptions
- Improving Protection
General
Are you using the latest version of Dotfuscator?
You may be encountering an issue that has already been fixed!
Are all third-party assemblies excluded from obfuscation?
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 (.csproj
) imports the MSBuild targets, such as with the statement:
<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.
If you are using a developer environment, follow the Installation Instructions, remembering to enable the Visual Studio Integration features for your installation(s) of Visual Studio.
If you are building on a build agent, see Build Agent Considerations for how to best install Dotfuscator.
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.
.NET Core and .NET Standard Build Errors
error MSB4019: The imported project "C:\Program Files\dotnet\sdk\2.1.504\PreEmptive\Dotfuscator\4\PreEmptive.Dotfuscator.Common.targets" was not found. Confirm that the path in the <Import> declaration is correct, and that the file exists on disk.
error MSB4062: The "FindProjectAssemblies" task could not be loaded from the assembly C:\SomePath\PreEmptive\Dotfuscator\4\PreEmptive.Dotfuscator.Internal.Tasks.dll. Could not load file or assembly 'Microsoft.Build.Utilities.v4.0, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'. The system cannot find the file specified. Confirm that the declaration is correct, that the assembly and all its dependencies are available, and that the task contains a public class that implements Microsoft.Build.Framework.ITask.
These errors can occur when you are using the .NET Core commands (dotnet build
/ dotnet msbuild
/ dotnet publish
) in conjunction with having Dotfuscator integrated into your Visual Studio project file. While Visual Studio and MSBuild on Windows will work with Dotfuscator to protect such projects, the .NET Core commands are not currently supported. See Protect Your App for more information.
Dotfuscator Processing Errors
This section is for issues that occur when Dotfuscator processes an app.
Dotfuscator can't find a reference assembly?
- Run from the command line with
/v /e /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.
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.
Activation Errors
This section is for issues that occur when activating Dotfuscator.
Dotfuscator Not Activated
You must register 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.
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.
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>
Is the application signed/resigned properly?
Read the Signing section in the Dotfuscator Config Editor Overview page for more information.
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
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 that 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!