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.

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

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 .\WinformsTest.csproj

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

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 will automatically skip that step and continue to the next step until it reaches one that will have actions to perform. Pressing enter will perform 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.

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.

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

Next, the tool updates the project's 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.

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

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net5.0-windows</TargetFramework>
    <OutputType>WinExe</OutputType>
    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
    <UseWindowsForms>true</UseWindowsForms>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.CSharp" Version="4.7.0" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.2.211730">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="5.0.2" />
  </ItemGroup>
</Project>

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. This tool is being frequently updated to address more scenarios, so make sure you're using a recent version.

• The try-convert tool must be installed and updated to at least version 0.7.212201.
• Earlier versions of the try-convert tool didn't support custom target or props files. If you can't upgrade to the latest version, you may need to manually address these issues. If the target project file includes references to custom targets or props files, these references may need to be manually deleted from the file before the .NET Upgrade Assistant is run against it.

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

See also

• Upgrade a WPF App to .NET 5 with the .NET Upgrade Assistant
• Upgrade an ASP.NET MVC App to .NET 5 with the .NET Upgrade Assistant
• Overview of the .NET Upgrade Assistant
• .NET Upgrade Assistant GitHub Repository