Upgrade Assistant

Status

	Build (Debug)	Build (Release)
ci
official

Overview

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

When run on a solution, 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, 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.

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

The usual usage 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. ⚠️

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)

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!