Migrate Dotfuscator Visual Studio Projects to MSBuild Targets

Dotfuscator Projects in Visual Studio are not supported in Dotfuscator 6. They were replaced by the Dotfuscator MSBuild Targets.

If an application uses the Dotfuscator Visual Studio integration, you must migrate it manually before using Dotfuscator 6.

As long as Dotfuscator 4 remains installed, existing Dotfuscator Visual Studio Projects continue to use Dotfuscator 4. They do not work with Dotfuscator 6.

Understand the Migration

There is no single migration process that works for every application. Dotfuscator Visual Studio Projects and the Dotfuscator MSBuild Targets manage inputs, outputs, build timing, and configuration differently.

Review these differences before selecting a migration approach.

Input Management

Dotfuscator Visual Studio Projects allowed you to define relationships between projects and configure a Dotfuscator Project to protect multiple assemblies together. Their output used consistent renaming and could be consumed by downstream projects.

The Dotfuscator MSBuild Targets use Automatic Input Management (AIM) to determine Dotfuscator’s inputs.

Configure the MSBuild Targets on projects that have no downstream dependencies. AIM determines each project’s dependencies and allows you to include or exclude those dependencies from obfuscation.

By default, AIM obfuscates all dependencies specified in the configuration file. Explicitly exclude assemblies that you do not want Dotfuscator to protect.

Control Included Assemblies

To exclude an assembly from protection, add the DotfuscatorIncludeAsInput property to its project file.

You can also include an external assembly as an input by applying DotfuscatorIncludeAsInput as metadata to a Reference item.

Do not add this metadata to ProjectReference or PackageReference items. These items do not support the metadata, and adding it causes a build error.

For more information, refer to Controlling Which Assemblies Are Protected in the MSBuild interface documentation.

Output Location

Dotfuscator Visual Studio Projects placed protected assemblies in the shared Dotfuscated folder by default. Because renaming was consistent, assemblies in this folder could reference other protected assemblies stored there.

The MSBuild Targets integrate Dotfuscator into the application’s build process and do not use the shared Dotfuscated folder.

Protected assemblies are saved to the location configured in the project file. This is typically the bin/Release directory.

To store protected assemblies from multiple projects in one location, configure the output path of each project to use the same directory.

Note: If multiple projects use the Dotfuscator MSBuild Targets and share a dependency, the dependency’s renamed output may differ for each output project.

Build Timing

Dotfuscator Visual Studio Projects protect assemblies after the complete build process has finished.

The MSBuild Targets protect assemblies during the build process. As a result, Dotfuscator runs before configured post-build processes.

Verify that protecting the assemblies does not interfere with the project’s post-build tasks.

Dotfuscator Configuration

The legacy Visual Studio integration used the Visual Studio Plugin to configure the protection settings for each Dotfuscator Project.

With the MSBuild Targets:

• Each enabled project requires its own Dotfuscator configuration file.
• The standalone Dotfuscator Pro Config Editor is used to configure each project’s protection settings.
• Dependencies may not appear in the Config Editor until after the project’s first build.
• A standard project build automatically protects the configured assemblies.

You can enable or disable the MSBuild Targets according to the project configuration, allowing you to maintain protected and unprotected builds.

When using the default integration template from Protect Your App, Dotfuscator runs only for the Release configuration. Use the DotfuscatorEnabled target property to control which project configurations are protected.

Select a Migration Approach

Select an approach based on the structure and dependencies of your application:

• For an application without shared libraries, or one whose components are distributed separately, follow Migrate a Simple Application.
• For an application with multiple outputs and shared dependencies, review Migrate an Application with Complex Dependencies.
• If you must package shared assemblies in one folder without changing existing dependencies, review Use Dotfuscator 6 Without Altering Dependencies.

For a large or complex application that cannot be modified, contact PreEmptive Support for assistance.

Migrate a Simple Application

Use this procedure for an application without shared libraries or one whose components are distributed separately. This diagram shows the conceptual differences between using Dotfuscator Projects and using the Dotfuscator MSBuild Targets to protect your application. 

The following steps guide you through the migration of a simple application to the MSBuild Targets:

1. Identify the output projects.
   Select projects that have no downstream dependencies. These projects typically produce the final .exe or .dll files that you distribute.

   Note: If multiple output projects share a dependency and their output must be packaged together, follow the guidance for migrating an application with complex dependencies.

    

2. Add the Dotfuscator MSBuild Targets to each output project.
   Edit the project file, usually a .csproj file, according to the Protect Your App instructions.
   Review the MSBuild Targets documentation to configure the protection settings. As part of the integration process, build the project to generate a Dotfuscator configuration file.
    
3. Update the generated Dotfuscator configuration.
   Configuration files from Dotfuscator Visual Studio Projects are not compatible with the MSBuild Targets configuration. Review the previous protection settings and manually add the required settings to the newly generated configuration file.
    

4. Build the protected project.
   Build the individual project instead of the entire solution. If you use the default project configuration, select the Release configuration so that Dotfuscator protects the application.

   Note: Building the complete solution before removing the Dotfuscator Projects may cause Dotfuscator to protect the application twice, resulting in unexpected results.

    

5. Verify the protected project.
   If the build encounters problems, refer to the Troubleshooting section. If the issue continues, contact PreEmptive Support.
    
6. Remove the old Dotfuscator Project.
   After verifying that the MSBuild Targets successfully protect the application, remove the old Dotfuscator Visual Studio Project.
   You can build the entire solution again after removing all its Dotfuscator Projects.

Migrate an Application with Complex Dependencies

The simple migration approach may not work for an application with:

• A complex dependency tree.
• Multiple output projects.
• Shared dependencies.
• Multiple output files that must be packaged together.

For these projects, configure each project to use a common output directory and enable Library Mode for shared libraries.

With this configuration, projects may generate independently obfuscated copies of an assembly. Each new copy can overwrite a previously generated copy in the shared output directory.

Enabling Library Mode for shared assemblies allows dependent assemblies to use any of the generated versions of the shared assembly.

There is no exact Dotfuscator 6 equivalent to Dotfuscator Visual Studio Projects. You may need to change some dependencies between projects to use the MSBuild Targets effectively.

Contact PreEmptive Support for assistance with the migration or consider the approach described in Use Dotfuscator 6 Without Altering Dependencies.

Use Dotfuscator 6 Without Altering Dependencies

If an application must package shared assemblies in one folder, you can use an empty C# project and the Dotfuscator MSBuild Targets to reproduce the general behavior of a Dotfuscator Visual Studio Project.

1. Create an empty C# project in the solution.
   Create at least as many empty projects as the number of Dotfuscator Projects currently in the solution.
   If the target platform does not provide an empty project template, create a class library and remove its automatically generated files.
   Configure the project’s build output type as Library so that it does not expect to build an executable.
    
2. Identify the output assemblies.
   Determine which output assemblies must be grouped. The selected assemblies should have no dependents within the group and should be similar to the inputs used by the corresponding Dotfuscator Project.
   You do not need to include shared libraries because AIM automatically protects them.
    
3. Add the output assemblies as references.
   In each empty project, right-click References and select Add Reference. Add the output assemblies that belong to the group.
    
4. Integrate the Dotfuscator MSBuild Targets.
   Follow the Protect Your App instructions for each empty project.
   Use the Dotfuscator Pro Config Editor to update each generated configuration file with the settings previously used by its Dotfuscator Project.
   If you do not want the project dependencies renamed, explicitly exclude them in the configuration file.
    

5. Build the empty projects.

   If you use the default MSBuild Targets configuration, build the Release configuration.

   The protected assemblies are written to the output directory configured in the empty project’s properties. The default location is:

   ${Project Directory}/bin/Release

6. Remove the empty library file.
   The empty project creates an empty library file. Remove this file during the AfterBuild step.

If you have questions or encounter problems during the migration, contact PreEmptive Support.