External Tools and Assembly Load Paths

Dotfuscator uses external tools and assembly load paths during the build process. These settings help Dotfuscator process assemblies and locate referenced assemblies.

Use this article when you need to understand how Dotfuscator finds ILdasm and ILasm, when .NET Framework SDK tools are required, how to specify tool locations explicitly, or how to add custom assembly load paths.

Finding External Tools

Dotfuscator uses the following tools to process assemblies:

Dotfuscator can obtain these tools in two ways:

• From the .NET Framework tools installed on Windows.
• From NuGet packages that Dotfuscator retrieves automatically during the build process.

Normally, Dotfuscator selects the best tools for each assembly based on the assembly target framework.

Tools from .NET Framework

When Dotfuscator runs on Windows, ILdasm can be provided by an installed .NET Framework SDK, and ILasm can be provided by an installed .NET Framework runtime.

Dotfuscator locates these tools automatically when they are present.

These tools:

• Support certain additional features.
• Run only on Windows.
• Do not support assemblies targeting newer frameworks, such as .NET Core 3.x and .NET 5.

Tools from NuGet

Dotfuscator can use NuGet to obtain ILdasm and ILasm. Dotfuscator handles retrieval and use of these packages automatically as part of the build process.

Use the following environment variables if the default NuGet source is unavailable:

Tools from NuGet:

• Run on Windows, macOS, and Linux.
• Support assemblies targeting newer frameworks, such as .NET Core 3.x and .NET 5.
• Do not support certain additional features that require the Windows-exclusive .NET Framework SDK.

How Dotfuscator Chooses Tools

Dotfuscator uses the following process to find ILdasm and ILasm for each input assembly:

1. Dotfuscator determines the metadata version of the assembly.
   • In most cases, this is 4.0.30319.
   • Assemblies targeting older versions of the Windows-only .NET Framework may have a lower metadata version.
2. Dotfuscator checks whether user-specified properties exist for the metadata version.
   • If matching properties are defined, Dotfuscator uses those tool paths.
3. If Dotfuscator is running on macOS or Linux, Dotfuscator uses tools from NuGet.
4. If the assembly targets a runtime that supports default interface methods, Dotfuscator uses tools from NuGet.
5. If the assembly targets a Windows-exclusive runtime, Dotfuscator uses tools from .NET Framework.
6. For other target frameworks, Dotfuscator uses tools from .NET Framework if they are present. If they are not present, Dotfuscator uses tools from NuGet.

Target Frameworks That Use NuGet Tools

Dotfuscator uses tools from NuGet for target frameworks that support default interface methods, including:

• .NET 5.0 and later
• .NET Core 3.0 and later
• .NET Standard 2.1
• Xamarin Android
• Xamarin iOS
• MAUI Android

Target Frameworks That Use .NET Framework Tools

Dotfuscator uses tools from .NET Framework for Windows-exclusive target frameworks, including:

• .NET Framework 4.x and earlier
• Universal Windows Platform (UWP)

Target Frameworks That Can Use Either Tool Set

For the following target frameworks, Dotfuscator uses .NET Framework tools if they are present. If they are not present, Dotfuscator uses tools from NuGet:

• .NET Core 2.x and earlier
• .NET Standard 2.0 and earlier
• Portable Class Libraries

Features Requiring .NET Framework SDK

Some features are available only when Dotfuscator uses the Windows-exclusive .NET Framework SDK tools.

The following table summarizes feature support by operating system and target app type.

* If you installed Dotfuscator with the NuGet package, a full Windows .NET Framework SDK must also be installed to use this feature.

Explicitly Specify Tool Locations

You can use properties to specify a specific ILdasm or ILasm executable for assemblies built on certain versions of .NET.

.NET Core and .NET Standard assemblies are always considered to be built on version 4.0, because that is the metadata version embedded in these assemblies.

Dotfuscator determines the kind of user-supplied tool by checking the path. If the path contains Microsoft.NETCore, Dotfuscator treats the tool as coming from NuGet. Otherwise, Dotfuscator treats the tool as coming from .NET Framework.

User-Defined Assembly Load Paths

When Dotfuscator builds a config, it needs to load assemblies referenced by the input assemblies. Dotfuscator typically uses rules similar to other .NET tools when discovering these assemblies.

You can specify custom locations where Dotfuscator should look for referenced assemblies. This is useful when a config references third-party assemblies without including those assemblies in the config.

If Dotfuscator cannot find a referenced assembly using the default search rules, add the directory to the user-defined assembly load paths.

Configure Assembly Load Paths

To configure user-defined assembly load paths:

1. Open your Dotfuscator config in the Config Editor.
2. Go to Settings.
3. Open the Assembly Load Paths tab.
4. Select the add icon and specify the directory that Dotfuscator should search.
   
5. Add all the assembly load paths required.
6. If needed, change the order in which directories are searched with the up and down icons.
7. If Dotfuscator should search the custom load path before its standard search, select Search First.
8. Save the config.

When you select the Search First option, Dotfuscator searches the user-defined assembly load path before applying its standard search rules. When Search First is not selected, Dotfuscator searches the load path after applying its standard search rules.

Related Articles

• Linking
• Signing Assemblies
• Build Events