Upgrade Assistant

Share your feedback on the .NET Upgrade Assistant!

We're interested to hearing how your experience with the .NET Upgrade Assistant has been going as you upgrade your project(s) from .NET Framework to .NET 5 and beyond.

Share your feedback here!

Status

	Build (Debug)	Build (Release)
ci
official

Overview

This project enables automation of common tasks related to upgrading .NET Framework projects to .NET 5 and beyond. Note that this is not a complete upgrade tool and work will be required after using the tooling to upgrade a project.

Upgrade Solution

When run on a solution in order to upgrade, the tool will:

• Determine which projects need upgraded and recommend the order the projects should be upgraded in
• Update the project file to be an SDK-style project
• Remove transitive NuGet package dependencies that may have been present in packages.config
• Re-target project to .NET 5.0
• Update NuGet package dependencies to versions that are compatible with .NET 5.0
• Make simple updates in C# source code to replace patterns that worked in .NET Framework with .NET 5.0 equivalents
• For some app models (like ASP.NET apps), add common template files (like startup.cs) and make simple updates based on recognized web.config or app.config values
• For projects targeting Windows, add a reference to the Microsoft.Windows.Compatibility package
• Add references to analyzers that help with upgrade, such as the Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers package

After running this tool on a solution to upgrade, the solution will likely not build until the upgrade is completed manually. Analyzers added to the solution will highlight some of the remaining changes needed after the tool runs.

Analyze Solution prior to Upgrade

When run on a solution in order to analyze dependencies prior to upgrade, the tool will provide an analysis report for each of the projects in the solution containing details on:

• Package dependencies that need to be removed / added / upgraded in order to upgrade the project to chosen TFM (.NET 5.0 and beyond)
• References that need to be removed / added / upgraded in order to upgrade the project to chosen TFM (.NET 5.0 and beyond)
• Framework References that need to be removed / added / upgraded in order to upgrade the project to chosen TFM (.NET 5.0 and beyond)
• Call out if there is a package upgrade across major versions that could lead towards having breaking changes.
• Unsupported API for the chosen TFM (.NET 5.0 and beyond) used in the projects with pointers to recommended path forward if one is available.

Solution wide extension management

Extensions may be managed centrally for a project as described here

Optional Features

Some features within Upgrade Assistant may be enabled by adding extensions.

Loose Assembly Identification

Some projects incorporate what we call "loose assemblies" where assemblies are added directly to a repo. An experimental feature described here can be used to help identify these and convert them to available NuGet packages.

Upgrade documentation

As you upgrade projects from .NET Framework to .NET 5, it will be very useful to be familiar with relevant porting documentation.

Web scenarios can be especially challenging, so it you are upgrading an ASP.NET app, be sure to read ASP.NET Core migration documentation. If you are unfamiliar with ASP.NET Core, you should also read ASP.NET Core fundamentals documentation to learn about important ASP.NET Core concepts (hosting, middleware, routing, etc.).

The following tutorials will give you a sense of how to upgrade ASP.NET, Windows Forms, and WPF applications to .NET 5 using the Upgrade Assistant:

• Upgrade an ASP.NET MVC App to .NET 5 with the .NET Upgrade Assistant
• Upgrade a Windows Forms App to .NET 5 with the .NET Upgrade Assistant
• Upgrade a WPF App to .NET 5 with the .NET Upgrade Assistant

Download this free e-book on Porting existing ASP.NET apps to .NET Core

Installation

Prerequisites

1. This tool uses MSBuild to work with project files. Make sure that a recent version of MSBuild is installed. An easy way to do this is to install Visual Studio 2019.
2. This tool requires that your project builds. This may include installing install Visual Studio 2019 to ensure build SDKs (such as for web applications, etc) are available.

Installation steps

The tool can be installed from NuGet as a .NET CLI tool by running:

dotnet tool install -g upgrade-assistant

Similarly, because the Upgrade Assistant is installed as a .NET CLI tool, it can be easily updated from the command line:

dotnet tool update -g upgrade-assistant

If installation fails, trying running the install command with the --ignore-failed-sources parameter:

dotnet tool install -g upgrade-assistant --ignore-failed-sources

Upgrade-assistant is installed as a NuGet package, so invalid or authenticated sources in NuGet configuration can cause installation problems.

To try the latest (and likely less stable) versions of the tool, CI builds are available on the dotnet-tools NuGet feed and can be installed with

dotnet tool install -g upgrade-assistant --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json

or to update:

dotnet tool update -g upgrade-assistant --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json

Usage

Running the tool

Upgrade Path

The usage for upgrade path of the tool is: upgrade-assistant upgrade <Path to csproj or sln to upgrade>

Full usage information:

Usage:
  upgrade-assistant upgrade [options] <project>

Arguments:
  <project>

Options:
  --skip-backup                                  Disables backing up the project. This is not recommended unless the
                                                 project is in source control since this tool will make large changes
                                                 to both the project and source files.
  --extension <extension>                        Specifies a .NET Upgrade Assistant extension package to include. This
                                                 could be an ExtensionManifest.json file, a directory containing an
                                                 ExtensionManifest.json file, or a zip archive containing an extension.
                                                 This option can be specified multiple times.
  -e, --entry-point <entry-point>                Provides the entry-point project to start the upgrade process. This
                                                 may include globbing patterns such as '*' for match.
  -v, --verbose                                  Enable verbose diagnostics
  --non-interactive                              Automatically select each first option in non-interactive mode.
  --non-interactive-wait <non-interactive-wait>  Wait the supplied seconds before moving on to the next option in
                                                 non-interactive mode.
  --target-tfm-support <Current|LTS|Preview>     Select if you would like the Long Term Support (LTS), Current, or
                                                 Preview TFM. See
                                                 https://dotnet.microsoft.com/platform/support/policy/dotnet-core for
                                                 details for what these mean.
  --version                                      Show version information
  -?, -h, --help                                 Show help and usage information

⚠️ The primary usage of upgrade-assistant is to be used in interactive mode, giving users control over changes/upgrades done to their projects. Usage of upgrade-assistant with --non-interactive mode can leave projects in a broken state and users are advised to use at their own discretion. ⚠️

Analyze Path

In order analyze package dependencies for a project or a solution use the analyze command with the tool like so : upgrade-assistant analyze <Path to csproj or sln to analyze>

Full usage information:

Usage:
  upgrade-assistant analyze [options] <project>

Arguments:
  <project>

Options:
  --extension <extension>                        Specifies a .NET Upgrade Assistant extension package to include. This
                                                 could be an ExtensionManifest.json file, a directory containing an
                                                 ExtensionManifest.json file, or a zip archive containing an extension.
                                                 This option can be specified multiple times.
  -v, --verbose                                  Enable verbose diagnostics
  --target-tfm-support <Current|LTS|Preview>     Select if you would like the Long Term Support (LTS), Current, or
                                                 Preview TFM. See
                                                 https://dotnet.microsoft.com/platform/support/policy/dotnet-core for
                                                 details for what these mean.
  --version                                      Show version information
  -?, -h, --help                                 Show help and usage information

The output of the analyze command is a report in SARIF format. SARIF is based on JSON and can be viewed using the following viewers:

• Any text editor.
• VS extension for SARIF Viewer for a richer experience.

Sample of the report in VS SARIF Viewer :

Determining upgrade feasibility

Note that this tool does not (yet) advise on the feasibility or estimated cost of upgrading projects. It assumes that projects it runs on have already been reviewed and a decision taken to upgrade them to .NET 5.0.

If you're just starting to look at .NET 5.0 and would like to understand more about potential challenges in upgrading any particular project, you should begin by looking at .NET Framework dependencies the project has and third-party libraries or NuGet packages it depends on and understand whether those dependencies are likely to work on .NET 5.0. Resources that can help with that analysis include:

1. The .NET Portability Analyzer tool
2. .NET Core porting documentation
3. Documentation of features not available on .NET Core

Authenticated NuGet sources

As part of upgrading a project, Upgrade Assistant will need to both restore the project's NuGet packages and query configured NuGet sources for information on updated packages. If a project depends on authenticated NuGet sources, some extra steps may be necessary for Upgrade Assistant to work correctly:

1. Upgrade Assistant requires that a v2 .NET Core-compatible NuGet credential provider be installed on the computer if authenticated NuGet sources are used. For example, if you are using authenticated Azure DevOps NuGet feeds, follow these instructions to setup a compatible credential provider. .NET Core NuGet credential providers are those installed under the netcore folder in .nuget/plugins, as explained here.
2. You may need to run Upgrade Assistant in interactive mode (which is the default execution mode) in order to authenticate the NuGet sources. After authenticating once, non-interactive mode can be used as the credentials are cached.

Extensibility

The Upgrade Assistant has an extension system that make it easy for you to customize many of the upgrade steps without having to rebuild the tool. See how you can extend the tool here.

Solution Structure

The structure of projects in the solution is organized into the following categories:

• cli This folder is for projects that are required for the CLI implementation of the upgrade assistant.
• common This folder is for common assemblies that extensions are expected to use.
• components This folder is for common assemblies that are not to be used in extensions, but may be used by different implementations of the tool.
• extensions This folder is for extensions that provide additional upgrade knowledge to the tool.
  • analyzers These are where custom analyzers are added. Analyzers must be separated by language if they are using language-specific syntax and cannot use any Workspace-related types. Code fixers may use workspace, and are thus kept in their own assemblies. This is because they may be hosted in different environments that may not have all language or workspace support.
• steps This folder contains projects for the different upgrade steps that are used. These should only use the abstraction class and should not depend on each other.

A similar structure is mirrored for the tests to identify where each of the tests will be located.

Terminology

Concepts referred to in this repository which may have unclear meaning are explained in the following table.

Name	Description
Step	A step can define commands that can perform actions on the project. Each step implements UpgradeStep. The upgrade process comprises a series of steps that are visited in turn. Examples include the 'Update package versions step' or the 'Project backup step'
Command	A command is an action that can be invoked by a user. Examples include a command to apply the current step or a command to change the backup location.
Project Components	AppModel-specific components that a project may depend on. The most common are WindowsDesktop components (for WPF and WinForms scenarios) and Web (for ASP.NET scenarios)
Loose assemblies	Binaries (.dll files) that are in the repo and not governed by a packaging system (such as NuGet)

Viewing log files

The project outputs a log file by default in the working directory called upgrade-assistant.clef that can be viewed with tools such as Compact Log Format Viewer available via the Windows Store.

Roadmap

Take a look at the high level overview of the roadmap for this tool and the journey to upgrade your apps from .NET Framework to .NET 5 and beyond in the roadmap.

Engage, Contribute and Give Feedback

Some of the best ways to contribute are to use the tool to upgrade your apps to .NET 5, file issues for feature-requests or bugs, join in design conversations, and make pull-requests.

Check out the contributing page for more details on the best places to log issues, start discussions, PR process etc.

Happy upgrading to .NET 5!

Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located here. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

See the documentation for information about the usage data collection.