How to upgrade a Windows Forms desktop app to .NET 7

This article describes how to upgrade a Windows Forms desktop app to .NET 7. Even though Windows Forms runs on .NET, a cross-platform technology, Windows Forms is still a Windows-only framework. The following Windows Forms-related project types can be upgraded with the .NET Upgrade Assistant:

  • Windows Forms project
  • Control library
  • .NET library

You should also review the information in the Porting from .NET Framework to .NET guide.


Don't upgrade Visual Basic Windows Forms projects. There seems to be a bug with the extension. This article will be updated when the bug is fixed.


Demo app

This article was written in the context of upgrading the Windows Forms Matching Game Sample project, which you can download from the .NET Samples GitHub repository.


Due to a bug in Windows Forms for .NET 7, the sample project crashes on startup after upgrading. This is fixed in upcoming .NET Desktop Runtime 7.0.6 release. The latest .NET 8 preview contains the same fix.

Initiate the upgrade

If you're upgrading multiple projects, start with projects that have no dependencies. In the Matching Game sample, the MatchingGame project depends on the MatchingGame.Logic library, so MatchingGame.Logic should be upgraded first.


Be sure to have a backup of your code, such as in source control or a copy.

Use the following steps to upgrade a project in Visual Studio:

  1. Right-click on the MatchingGame.Logic project in the Solution Explorer window and select Upgrade:

    The .NET Upgrade Assistant's Upgrade menu item in Visual Studio.

    A new tab is opened that prompts you to choose how you want the upgrade to be performed.

  2. Select In-place project upgrade.

  3. Next, select the target framework. Based on the type of project you're upgrading, you're presented with different options. .NET Standard 2.0 is a good choice if the library doesn't rely on a desktop technology like Windows Froms and can be used by both .NET Framework projects and .NET projects. However, the latest .NET releases provide many language and compiler improvements over .NET Standard.

    Select .NET 7.0 and then select Next.

    The .NET Upgrade Assistant's target framework decision tab.

  4. A tree is shown with all of the artifacts related to the project, such as code files and libraries. You can upgrade individual artifacts or the entire project, which is the default. Select Upgrade selection to start the upgrade.

    When the upgrade is finished, the results are displayed:

    The .NET Upgrade Assistant's upgrade results tab, showing two out of the 13 items were skipped.

    Artifacts with a solid green circle were upgraded while empty green circles were skipped. Skipped artifacts mean that the upgrade assistant didn't find anything to upgrade.

Now that the app's supporting library is upgraded, upgrade the main app.

Upgrade the app

Once all of the supporting libraries are upgraded, the main app project can be upgraded. With the example app, there's only one library project to upgrade, which was upgraded in the previous section.

  1. Right-click on the MatchingGame project in the Solution Explorer window and select Upgrade:
  2. Select In-place project upgrade as the upgrade mode.
  3. Select .NET 7.0 for the target framework and select Next.
  4. Leave all of the artifacts selected and select Upgrade selection.

After the upgrade is complete, the results are shown. Notice how the Windows Forms project has a warning symbol. Expand that and more information is shown about that step:

The .NET Upgrade Assistant's upgrade results tab, showing some of the result items have warning symbols.

Notice that the project upgrade component mentions that the default font has changed. Because the font may affect control layout, you need to check every form and custom control in your project to ensure the UI is arranged correctly.

Generate a clean build

After your project is upgraded, clean and compile it.

  1. Right-click on the MatchingGame project in the Solution Explorer window and select Clean.
  2. Right-click on the MatchingGame project in the Solution Explorer window and select Build.

If your application encountered any errors, you can find them in the Error List window with a recommendation how to fix them.


The Windows Forms Matching Game Sample project is now upgraded to .NET 7. Your results will be different when you migrate your own project. Make sure you take the time to review the Porting from .NET Framework to .NET guide and the Modernize after upgrading to .NET from .NET Framework article.