Upgrading from Dotfuscator 6

If you do not manually update the MSBuild Targets path, you will likely see Visual Studio complain about the missing targets:

The imported project “${Visual Studio Install Path}/MSBuild/PreEmptive/Dotfuscator/6/…” was not found. Confirm that the expression in the Import declaration “${Visual Studio Install Path}/MSBuild/PreEmptive/Dotfuscator/6/…” is correct, and that the file exists on the disk. “{Visual Studio Project File Path}”

To fix this, simply update the MSBuild Targets paths to:

${Visual Studio Install Path}/MSBuild/PreEmptive/Dotfuscator/7/…

Refer to the Getting Started section to start protecting your .NET applications with Dotfuscator 7.

Upgrading from Dotfuscator 4

PreEmptive Protection - Dotfuscator 6 introduces many changes and new features to the functionality and user experience of Dotfuscator. This page describes the changes that might require build modifications or affect Dotfuscator's output. A full list of the changes is available in the changelog.

License Validation

When you upgrade from Dotfuscator 4 to Dotfuscator 6, Dotfuscator 6 must successfully validate your license with PreEmptive Servers at least once in order to run. In order to do this, Dotfuscator 6 will require an active license to be configured and will require an active internet connection. If you encounter difficulties with this license validation, please contact PreEmptive support for assistance.

Installation Location

The Dotfuscator 6 installer will offer to install the new version alongside any existing installation(s) of Dotfuscator 4. To facilitate this side-by-side installation, Dotfuscator 6 will be installed in a different location than previous versions of Dotfuscator.

Choose the Correct Installation Configuration

When installing Dotfuscator 6, the installer will give you the option to uninstall Dotfuscator 4 or install the two alongside each other. Before you uninstall Dotfuscator 4, there are a few changes in Dotfuscator 6 that you should be aware of.

Dotfuscator 6 no longer has support for Dotfuscator Projects in Visual Studio. If you used these projects to protect your application, we recommend updating your application to use the Dotfuscator MSBuild Targets using the instructions below. If you choose to migrate existing projects to the MSBuild Targets, you should wait until the migration is complete before uninstalling Dotfuscator 4.

Other types of projects can also reference the Dotfuscator version explicitly. If you use the Dotfuscator MSBuild Targets or the Dotfuscator MSBuild Task, you will need to update these references in order to use Dotfuscator 6 to protect your app.

If you choose to keep Dotfuscator 4, you will still have Dotfuscator Projects available to use. However, these projects will only work with Dotfuscator 4. Also, Dotfuscator will not alert you that your existing projects are using Dotfuscator 4 instead of Dotfuscator 6.

In addition, Dotfuscator 6 no longer supports side-by-side installation through the Windows Installer. If you need this functionality, use the Dotfuscator NuGet package.

Integrate into Your App's Project File

The XML elements to copy and paste into your project file have changed. You will need to remove the old copy and pasted elements and insert the new XML elements.

MSBuild Targets

Your existing project may reference Dotfuscator's MSBuild Targets at:

${Visual Studio Install Path}/MSBuild/PreEmptive/Dotfuscator/4/

To protect your application with Dotfuscator 6, you will need to update these paths to:

${Visual Studio Install Path}/MSBuild/PreEmptive/Dotfuscator/6/

The MSBuild Targets in Dotfuscator 6 contain no breaking changes from those in Dotfuscator 4. You should be able to update the Dotfuscator version without any consequences. Keep in mind that if you choose to uninstall Dotfuscator 4, your existing MSBuild Targets projects will not build until you update this path.

If you enable the Dotfuscator MSBuild Targets for a project, all developers who wish to build or modify the project must have the same version of Dotfuscator Installed. Developers who do not have Dotfuscator installed will be unable to load the project in Visual Studio, as MSBuild will fail to find the nonexistent targets file. To open a configured project without installing Dotfuscator, you will need to first remove or comment out the corresponding section in the project file.

NuGet Package

The PreEmptive.Protection.Dotfuscator.Pro NuGet package no longer contains the Config Editor. Developers using the NuGet package will now also have use the Windows Installer if they need to make changes using the Config Editor.

Upgrade Your Configuration Files

All Dotfuscator configuration files that were created prior to Dotfuscator 6 will need to be upgraded.

If you try to run Dotfuscator with an old configuration file from the command line or via Dotfuscator's MSBuild Targets, you will receive the following error:

PreEmptive Analytics, Authenticode signing, and the Introduce Explicit Method Overrides setting are no longer supported. Please open your Dotfuscator config in the Config Editor which will automatically upgrade it.

When you open your config in the Config Editor, you will be informed that:

PreEmptive Analytics, Authenticode signing, and the Introduce Explicit Method Overrides setting are no longer supported. The associated settings have been removed. Please save your upgraded Dotfuscator config.

You will receive these messages even if you were not using PreEmptive Analytics.

Removed Features

PreEmptive Analytics

Dotfuscator 6 does not support PreEmptive Analytics, including Check Telemetry. Checks (including Application Notification and Check Actions) are still supported.

To use Dotfuscator 6, you will need to upgrade your configuration file to remove the PreEmptive Analytics settings.

If you were using in-code attributes to configure PreEmptive Analytics, you will need to remove those from your source code and rebuild your input assemblies, before Dotfuscator 6 can protect those assemblies.

Unsupported Visual Studio Versions

Dotfuscator 6 no longer supports Visual Studio version 2010.

Unsupported Application Types

The following application types are no longer supported in Dotfuscator 6:

• Windows Phone
• WinRT
• Silverlight
• Unity

Unsupported Inputs

The following file types are no longer supported as inputs to Dotfuscator 6:

• ClickOnce .application packages
• UWP .appx packages

We recommend transitioning to using the Dotfuscator MSBuild Targets, which are easier to use, more reliable, and are still able to protect the application types listed above.

Additionally, .xap packages can no longer be used as inputs. This is because Silverlight is no longer supported.

Authenticode Signing

The Authenticode signing feature has been removed from Dotfuscator. A post build event for Authenticode signing can be used instead.

The following is an example configuration for a post build Authenticode signing event. This example runs the event on each output module only when the Dotfuscator build is successful. You will need to substitute the following values:

• Sign Tool Dir is the absolute path to the Microsoft Sign Tool. You can find this by opening the Developer Command Prompt and typing where signtool
• Certificate File Path and the corresponding Certificate Password that will be used to sign. It can use ${configdir} to specify a path relative to the Dotfuscator config file's directory.
• Timestamp URL is the URL of an Authenticode timestamp service.

<eventlist>
  <event type="postbuild">
    <option>runoneachmodule</option>
    <option>buildsuccessful</option>
    <program>
      <file dir="[Sign Tool Dir]" name="signtool.exe" />
      <environment commandline="sign -fd sha256 -f [Certificate File Path].pfx -p [Certificate Password] -tr [Timestamp URL] -as ${dotf.current.out.module}" workingdir="" />
    </program>
  </event>
</eventlist>

PreMark Task

The PreMark MSBuild task, which extracted watermarks from protected assemblies, has been removed. You can still configure Dotfuscator to embed watermarks into protected assemblies, and you can extract the watermarks using the premark command line tool.

Introduce Explicit Method Overrides

The Renaming option to introduce explicit method overrides has been removed from Dotfuscator. To use Dotfuscator 6, you will need to upgrade your configuration file to remove this setting.

If you are using incremental obfuscation and explicit method overrides you will need to start using a new input mapping file or continue using Dotfuscator 4. See the Troubleshooting page for more details.

Deprecated Features

The capability to have Dotfuscator's .dat file in the same directory as the dotfuscator executable is deprecated and will stop working in a future major release of Dotfuscator. Please contact PreEmptive Support for a Floating License if you are using this feature.

Visual Studio Integration

Dotfuscator Projects in Visual Studio are no longer supported in Dotfuscator 6. These projects have been replaced by the Dotfuscator MSBuild Targets, which are easier to use, more reliable, and are able to protect more application types.

If you have a project which uses the Dotfuscator Visual Studio Plugin and want to use Dotfuscator 6, you will need to upgrade it manually to use the MSBuild Targets. So long as you still have Dotfuscator 4 installed, all Dotfuscator Visual Studio Projects will continue to use Dotfuscator 4, and will not work with Dotfuscator 6.

Choose How to Migrate

Unfortunately, due to the differences in configuration between Dotfuscator Projects and the MSBuild Targets, there is no "one size fits all" solution for migrating. If you choose to update your existing projects to use the MSBuild Targets, you should be aware of how each Dotfuscator configuration works.

For more information about the Dotfuscator MSBuild Targets, please refer to the MSBuild Targets Documentation. A condensed list of the most important differences between the two project configurations is included below. We also provide a brief set of migration instructions, which should work for most users.

Input Management

Dotfuscator Projects in Visual Studio allowed you to have arbitrarily-defined relationships between your projects. You were able to configure your Dotfuscator Project to take in any of your assemblies and obfuscate all of them together. The Visual Studio Projects' output also has consistent renaming, and could be used by downstream projects.

The Dotfuscator MSBuild Targets use Automatic Input Management (AIM) to determine the inputs to Dotfuscator. The MSBuild Targets should be configured on projects with no downstream dependencies. AIM automatically determines these projects' dependencies, and then allows you to include or exclude these projects from obfuscation. Dotfuscator then obfuscates all of the projects' dependencies with the project itself.

To exclude assemblies from protection, you will need to add the DotfuscatorIncludeAsInput Property to each assembly's project file. You can also use DotfuscatorIncludeAsInput to include external assemblies as inputs to Dotfuscator by applying it as metadata to any Reference item. However, the metadata is not supported on any ProjectReference or PackageReference items, and will cause a build error if added to either one. For more information on DotfuscatorIncludeAsInput, please refer to the Controlling Which Assemblies Are Protected section of the MSBuild interface page.

Output Location

In Dotfuscator Projects, all obfuscated assemblies were placed into the Dotfuscated shared folder by default. Since renaming is consistent in Dotfuscator Projects, any obfuscated assembly in the folder could be referenced by any other assembly in the Dotfuscated folder. However, there is no longer a need for a common output directory now that Dotfuscator is a part of the build process, and so the Dotfuscated directory has been removed. Instead, your protected assemblies will be saved in the location set by MSBuild, which is typically the bin/Release directory.

The Dotfuscator MSBuild Targets output obfuscated files to the directory specified by the project (.csproj) file. If you want your protected assemblies to be stored in the same directory, you will need to configure each project's output path to point to that common directory.

Note: If multiple projects are configured with Dotfuscator MSBuild targets and share a common dependency, the renaming of the dependency may differ based on the output project. For ideas on how to achieve consistent renaming of dependencies, see the migration instructions.

Build Timing

Migrating to the Dotfuscator MSBuild Targets will also change the point in the build when Dotfuscator operates on your assemblies. Dotfuscator Projects would obfuscate assemblies after the entire build process had completed, while the MSBuild Targets act on assemblies during the build process.

Using the MSBuild Targets means that Dotfuscator will run before any post-build processes. You will need to ensure that the obfuscated assembly will not interfere with any post-build tasks you have configured.

Dotfuscator Configuration

Dotfuscator Projects in Visual Studio relied on the Visual Studio Plugin interface to configure the protection settings for each project. To configure the Dotfuscator MSBuild Targets, each enabled project requires its own configuration file. Then, use the standalone Dotfuscator Pro Config Editor to set the protection settings for each of your projects individually.

Note: If you do not see all of your project's dependencies in the Config Editor, they should appear after running your first build.

The legacy Dotfuscator Visual Studio integration required you to build your Dotfuscator Project to generate protected assemblies. The Dotfuscator MSBuild Targets instead integrate into the build process, so your assemblies from a standard build will be protected automatically. You can enable or disable the MSBuild targets based on the project configuration, which will then allow you to have protected and unprotected builds.

If you use the default integration template from the Protect Your App page, then Dotfuscator will run only in the Release configuration. To set which project configurations are protected, modify the DotfuscatorEnabled target property.

Migration Instructions

There is no single solution for upgrading a Dotfuscator Visual Studio Project to the MSBuild Targets. Due to the way each configuration handles assemblies, each project should be migrated to the MSBuild Targets on an individual basis.

For larger or more complex projects which cannot be modified, we strongly encourage you to contact PreEmptive Support for help updating to the MSBuild Targets. For more information about which option is the best for your application, see the sections on choosing an installation configuration and choosing the best migration path for your application.

Migrate a Simple Application

If you have an application without shared libraries or one in which the individual components are distributed separately, then migrating to the MSBuild Targets should be fairly simple. This diagram shows the conceptual differences between using Dotfuscator Projects and using the Dotfuscator MSBuild Targets to protect your application.

The following steps will guide you through migrating a simple application to the MSBuild Targets.

1. Identify your output project(s). These projects should be those which have no downstream dependencies, and will most likely produce the final assembly (usually an .exe or .dll file) that you release.

   Note: If multiple output projects depend on a common assembly and you want to package the outputs together, please see the instructions for migrating a complex application.

2. Add the Dotfuscator MSBuild Targets to your Output Project(s). To do this, you will need to edit your project file (usually .csproj) according to the Protect Your App Instructions. Be sure to review the MSBuild Targets documentation so that you can best configure the protection settings for your application. As part of these instructions, you will build your project and generate a Dotfuscator configuration file.

3. Update the generated Dotfuscator Configuration file. The configuration file(s) from Dotfuscator Projects are not compatible with the MSBuild Targets. You will need to review your obfuscation settings by hand and update them manually in the configuration file generated during the Protect Your App instructions.

4. Try building the protected project (but not the entire solution). The project should be ready to build with your updated settings, assuming you have correctly completed the instructions on the Protect Your App page. If you are using the default project configuration, be sure to build using the Release Configuration so that your application is properly protected.

   Note: Building the entire solution may cause your application to be protected by Dotfuscator twice, which may cause unexpected results. Once you have removed all Dotfuscator Projects, you may once again build the entire solution.

   If you encounter any issues at this step in the process, please see the troubleshooting page to try to resolve the issue. If you still have issues, please contact PreEmptive Support so that we can help you finish the migration process.

5. Remove your old Dotfuscator Project file. Your application will now be protected automatically when it builds, and you can safely remove the old Dotfuscator Visual Studio project.

Migrate an Application with Complex Dependencies

If your application has a complex dependency tree and multiple outputs, then chances are that the simple solution will not work for your project. This is especially true if your solution contains shared dependencies and multiple output files that you want to package together.

For most of these projects, the simplest solution is to set the output directories for each project to your common output directory, and ensure that Library Mode is enabled for all common libraries. With this configuration each project will create multiple independently obfuscated copies of the assembly, which will overwrite previously generated copies. Enabling Library Mode for your shared assemblies ensures that dependent assemblies can use any version of the shared assembly without issue.

Unfortunately, there is no exact analog to Dotfuscator Visual Studio Projects supported in Dotfuscator 6. You may need to change some of the dependencies between your projects to use the MSBuild Targets effectively. That being said, we encourage you to contact PreEmptive Support for help with migration, or to attempt using one of the fixes described in the following section.

Use Dotfuscator 6 Without Altering Dependencies

If your application requires packaging shared assemblies in a single folder, it is possible to use an Empty C# Project and the Dotfuscator MSBuild Targets to mimic the behavior of a Dotfuscator Project. The MSBuild Targets allow you to use Automatic Input Management to easily protect all of your assemblies and their dependencies by following the instructions below.

1. Create an Empty C# Project as part of your solution. You will want to create at least as many Empty Projects as the number of Dotfuscator Projects you currently have. If your target platform does not have empty projects, you may also create a class library and remove all of the automatically-generated files.

   Note: Be sure your empty projects are not expecting to build an executable file. It is easiest to simply specify the build output type as Library for each of these projects.

2. Identify your output assemblies that should be grouped together. These assemblies should have no dependents within their grouping, and should be similar to the inputs for each Dotfuscator Project.

   Note: There should be the same or fewer output assemblies as the number of inputs specified in your Dotfuscator Project. You do not need to include shared libraries, as these are automatically protected by Automatic Input Management.

3. Add your output assemblies as References to your Empty Project(s). To do this, simply right click on the References section of each Empty Project and select Add Reference...

4. Apply the Protect Your App Instructions to each Empty Project. Be sure to update your Dotfuscator Configuration file(s) using the Pro Config Editor to match the settings used in your Dotfuscator Project. If you do not want any of your projects' dependencies to be renamed, you will need to explicitly exclude them in the configuration file.

5. Build your Empty Project(s). If you are using the default Dotfuscator MSBuild Targets configuration, keep in mind that your application will only be obfuscated in the Release configuration. Your protected assemblies will then appear in the output directory specified by the Empty Project's Properties. The default is ${Project Directory}/bin/Release.

6. Remove the empty file created by your Empty Project. The Empty Project will automatically create an empty library file, which you should then remove in the AfterBuild step.

If you have any questions or concerns about these instructions, please contact PreEmptive Support so that we can assist you in protecting your application.