Advanced Topics
DOTFUSCATOR_HOME variable
When it is installed using the Windows installer, Dotfuscator adds a system environment variable, DOTFUSCATOR_HOME
, that specifies the location of Dotfuscator on a particular machine.
DOTFUSCATOR_HOME
is also appended to the system PATH environment variable (as long as there is room to add it).
If your system PATH environment variable was too long to append %DOTFUSCATOR_HOME%;
during installation, you may want to reduce the length of the system path and then append %DOTFUSCATOR_HOME%
to the system PATH yourself.
For side-by-side installs, the DOTFUSCATOR_HOME
environment variable refers to whichever version of Dotfuscator was installed last.
If you would like the variable to refer to another version, update the system environment variable to point to the install location of the other version.
When you uninstall Dotfuscator, the installer will unset DOTFUSCATOR_HOME and remove it from PATH, but only if the specified path matches the version being uninstalled. If you have other versions of Dotfuscator installed, you may want to reconfigure DOTFUSCATOR_HOME to point to one of those versions.
Concurrent Builds
When running multiple copies of Dotfuscator simultaneously, it is recommended that the following files be copied into the same directory as the Dotfuscator executable:
dotfuscator.dat (normally in %PROGRAMDATA%\PreEmptive Solutions\Dotfuscator [Edition]\4.0)
dfusrprf.xml (normally in %LOCALAPPDATA%\PreEmptive Solutions\Dotfuscator [Edition]\4.0)
dotfuscator.cfg (normally in %LOCALAPPDATA%\PreEmptive Solutions\Dotfuscator [Edition]\4.0)
Finding External Tools
Dotfuscator uses ILdasm and ILasm to process assemblies. ILdasm is the .NET intermediate language (IL) disassembler, and ILasm is the IL assembler. These can come from a .NET Framework SDK or through NuGet packages that contain native versions of these external tools, though there are certain limitations with the latter case.
Dotfuscator searches for the external tools using the following algorithm:
Determine the version of the framework that the assembly was originally compiled on. Note that .NET Core and .NET Standard assemblies report
4.0
for this value.Look at user-specified properties that override the default locations of the tools. Error if a property is set but the executable referred by the property's value does not exist. For details, see Explicitly Specifying the Tool Locations.
If the assembly targets .NET Core 3.0 or later, search the NuGet cache for the appropriate .NET Core runtime ILdasm and ILasm packages. If the packages are not present, attempt to automatically retrieve them from a public NuGet feed. Error if they are still not present.
Search the .NET Framework and .NET Framework SDK directories corresponding to the .NET Framework version determined in step 1.
Search the .NET Framework and .NET Framework SDK directories corresponding to later versions of the .NET Framework determined in step 1.
Search the NuGet cache for the appropriate .NET Core runtime ILdasm and ILasm packages. If the packages are not present, attempt to automatically retrieve them from the public NuGet feed. Error if they are still not present.
For help with the errors that occur when Dotfuscator cannot find one of these tools, see Troubleshooting.
Features Requiring .NET Framework SDK
Because Dotfuscator relies on the ILdasm and ILasm tools to process assemblies, certain features may be limited depending on the versions of these tools available.
The following features are only available when Dotfuscator is using the Windows-exclusive .NET Framework SDK:
- Debugging Symbols (e.g.,
.pdb
files), regardless of the debugging option. - Native Win32 resource files embedded in assemblies (e.g., application icons).
Managed resources (e.g., .resx
files) are supported in all scenarios.
The table below summarizes the support for these features based on operating system, target app type, and whether the .NET Framework SDK is installed.
OS | Target App Type | Debugging Symbols | Native resources | Managed resources |
---|---|---|---|---|
Windows | .NET Core 3.0+ | ❌ | ❌ | ✅ |
Windows | Other | ✅* | ✅* | ✅ |
macOS | Any | ❌ | ❌ | ✅ |
Linux | Any | ❌ | ❌ | ✅ |
* If you installed with the NuGet package, a full (Windows) .NET Framework SDK must also be installed to use this feature.
Explicitly Specifying the Tool Locations
You can use properties to specify a specific ILdasm or ILasm for assemblies built on certain versions of .NET.
Note that .NET Core and .NET Standard assemblies are always considered to be built on version 4.0
, due to that being the metadata version embedded in these assemblies.
The following table summarizes by example:
Property Name | Property Value | Meaning |
---|---|---|
ILDASM_v2.0.50215 |
C:\1\ildasm.exe |
Dotfuscator will disassemble input assemblies that target .NET Framework v2.0.50215 with this version of the IL disassembler. |
ILDASM_v1.1 |
C:\2\ildasm.exe |
Dotfuscator will disassemble input assemblies that target .NET Framework v1.1.x with this version of the IL disassembler. |
ILASM_v1.0.3705 |
C:\3\ilasm.exe |
Dotfuscator will assemble output assemblies that target .NET Framework v1.0.3705 with this version of the IL assembler. |
ILASM_v4.0 |
C:\4\ilasm.exe |
Dotfuscator will assemble output assemblies that target .NET Framework v4.x, .NET Core, or .NET Standard with this version of the IL assembler. |
Other Tools
Dotfuscator uses the strong naming tool (sn.exe
) to automatically resign your strong named assemblies on Windows.
This tool also ships with the .NET Framework SDK and by default Dotfuscator searches for it in the same directory as ILdasm.
If you wish to specify a specific location for sn.exe
you can set the property of SN_TOOL_*
using the same conventions as ILDASM_*'/'ILASM_*
.