Upgrade a Windows Forms App to .NET 5 with the .NET Upgrade Assistant

The .NET Upgrade Assistant is a command-line tool that can assist with upgrading .NET Framework Windows Forms (WinForms) apps to .NET 5. This article provides:

  • A demonstration of how to run the tool against a .NET Framework Windows Forms app
  • Troubleshooting tips

Upgrade .NET Framework Windows Forms apps

This section demonstrates running the .NET Upgrade Assistant against a newly created Windows Forms app targeting .NET Framework 4.6.1. For more information on how to install the tool, see Overview of the .NET Upgrade Assistant.

Initial demo setup

If you're running the .NET Upgrade Assistant against your own .NET Framework app, you can skip this step. If you just want to try it out to see how it works, this step shows you how to set up a sample .NET Windows Forms project to use.

Using Visual Studio, create a new Windows Forms project using .NET Framework.

New Windows Forms project in Visual Studio

Name the project WinformsTest. Configure the project to use .NET Framework 4.6.1.

Configure Windows Forms project in Visual Studio

Review the created project and its files, especially its project file(s).

Run upgrade-assistant

Open a terminal and navigate to the folder where the target project or solution is located. Run the upgrade-assistant command, passing in the name of the project you're targeting (you can run the command from anywhere, as long as the path to the project file is valid).

upgrade-assistant upgrade .\WinformsTest.csproj

The tool runs and shows you a list of the steps it will do.

.NET Upgrade Assistant initial screen

As each step is completed, the tool provides a set of commands allowing the user to apply or skip the next step, see more details, configure logging, or exit the process. If the tool detects that a step will perform no actions, it automatically skips that step and continues to the next step until it reaches one that has actions to do. Pressing Enter will start the next step if no other selection is made.

In this example, the apply step is chosen each time. The first step is to back up the project.

.NET Upgrade Assistant back up project

The tool prompts for a custom path for the backup, or to use the default, which will place the project backup in the same folder with a .backup extension. The next step the tool does is to convert the project file to SDK style.

.NET Upgrade Assistant convert project to SDK style

Once the project format has been updated, the next step is to update the TFM of the project.

.NET Upgrade Assistant update TFM

Next, the tool updates the project's NuGet packages.

.NET Upgrade Assistant update NuGet packages

Once the packages are updated, the next step is to add template files, if any. In this case, there are no template files that need to be added. This step continues and migrates app config files and updates C# source to apply fixes, as shown below. This project didn't need any config file or source code changes, so these steps proceeded automatically.

.NET Upgrade Assistant add template files and migrate config

Since this is the last project, the next step, "Move to next project", prompts to complete the process of migrating the entire solution.

.NET Upgrade Assistant completing the solution

Once this process has completed, the migrated Windows Forms project will look something like this:

<Project Sdk="Microsoft.NET.Sdk">
    <PackageReference Include="Microsoft.CSharp" Version="4.7.0" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.2.211730">
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="5.0.2" />

Notice that the .NET Upgrade Assistant also adds analyzers to the project that assist with continuing the upgrade process.

Troubleshooting tips

There are several known problems that can occur when using the .NET Upgrade Assistant. In some cases, these are problems with the try-convert tool that the .NET Upgrade Assistant uses internally.

The tool's GitHub repository has more troubleshooting tips and known issues.

See also