Edit

Upgrade a .NET Framework Windows Forms desktop app to .NET 8

  • Article

This article describes how to upgrade a Windows Forms desktop app to .NET 8 using the Upgrade Assistant. 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

Prerequisites

Upgrade the dependencies first

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.

Tip

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:

    A screenshot of the .NET Upgrade Assistant's Upgrade menu item in Visual Studio.

    A new tab is opened that prompts you to choose which type of upgrade you want to perform.

  2. Select Upgrade project to a newer .NET version.

    A screenshot of the .NET Upgrade Assistant tab. The 'Upgrade project to a newer .NET version' option is highlighted.

  3. Select In-place project upgrade.

    A screenshot of the .NET Upgrade Assistant tab. The 'In-place project upgrade' option is highlighted.

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

    Select .NET 8.0 and then select Next.

    A screenshot of the .NET Upgrade Assistant. The target framework ptompt is open and .NET 8 is highlighted along with the 'Next' button.

  5. 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.

  6. When the upgrade is finished, the results are displayed:

    A screenshot of the .NET Upgrade Assistant's upgrade results tab, showing the migrated items from the project.

    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 main project

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 Upgrade project to a newer .NET version.
  3. Select In-place project upgrade as the upgrade mode.
  4. Select .NET 8.0 for the target framework and select Next.
  5. 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 item and more information is shown about that step:

A screenshot of 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 main 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 8.

Related content

  • Porting from .NET Framework to .NET.

    The porting guide provides an overview of what you should consider when porting your code from .NET Framework to .NET. The complexity of your projects dictates how much work you'll do after the initial migration of the project files.

  • Modernize after upgrading to .NET from .NET Framework.

    The world of .NET has changed a lot since .NET Framework. This link provides some information about how to modernize your app after you've upgraded it.