Troubleshooting
- General
- Are you using the latest version of Dotfuscator?
- Are all third-party assemblies excluded from obfuscation?
- Visual Studio / MSBuild Errors
- Build 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 / MSBuild Errors
This section is for issues that occur when a Visual Studio or MSBuild project is built using Dotfuscator's MSBuild targets, such as when following the instructions on Protect Your App.
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.
Is Dotfuscator Installed in a Custom Location?
The MSBuild targets assume Dotfuscator is installed in the default location, which is of the form:
C:\Program Files (x86)\PreEmptive Solutions\Dotfuscator Professional Edition X.XX.X\dotfuscator.exe
If you installed Dotfuscator in a different location, builds will fail because the MSBuild targets cannot find Dotfuscator.
You can correct this by editing the Visual Studio project file and setting the DotfuscatorCliPath
property, e.g.:
<PropertyGroup>
<DotfuscatorCliPath>c:\my\custom location\dotfuscator.exe</DotfuscatorEnabled>
</PropertyGroup>
To discover the correct path, follow the instructions at Locating the Command Line Executable.
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.
Build 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
.
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!