This article describes how to upgrade a Windows Forms desktop app to .NET using .NET Upgrade Assistant. Windows Forms remains a Windows-only framework, even though .NET is a cross-platform technology.

Prerequisites

• Windows Operating System.
• Download and extract the demo app used with this article.
• Visual Studio 2022 version 17.12 or later to target .NET 9.
• .NET Upgrade Assistant extension for Visual Studio.

Assessment

You should analyze your projects before performing an upgrade. Performing code analysis on your projects with .NET Upgrade Assistant generates a report that you can refer to, to identify potential migration blockers.

To analyze your projects and generate a report, right-click on the solution file inSolution Explorer and selectUpgrade. For more information about performing an analysis, seeAnalyze projects with .NET Upgrade Assistant.

Migrate dependencies

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

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

1. Right-click on theMatchingGame.Logic project in theSolution Explorer window and selectUpgrade:

   

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

2. SelectIn-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 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, which this project does.

   Select.NET 9.0 and then selectNext.

   

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. SelectUpgrade selection to start the upgrade.

   

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

   

   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.

Notes for Visual Basic projects

Currently, the .NET Upgrade Assistant doesn't recognize the use ofSystem.Configuration in the settings file created by the Visual Basic templates on .NET Framework. It also doesn't respect the use of theMy extensions used in .NET Framework projects, such asMy.Computer andMy.User. These extensions were removed in .NET. Because of these two problems, a Visual Basic library won't compile after being migrated with .NET Upgrade Assistant.

To fix this problem, the project must target Windows and reference Windows Forms.

1. After the migration is complete, double-click theMatchingGame.Logic project in theSolution Explorer window.
2. Locate the<Project>/<PropertyGroup> element.
3. In the XML editor, change the value of<TargetFramework> fromnet9.0 tonet9.0-windows.
4. Add<UseWindowsForms>true</UseWindowsForms> to the line after<TargetFramework>.

The project settings should look like the following snippet:

<Project Sdk="Microsoft.NET.Sdk">  <PropertyGroup>    <TargetFramework>net9.0-windows</TargetFramework>    <UseWindowsForms>true</UseWindowsForms>    <OutputType>Library</OutputType>    <MyType>Windows</MyType>    ... other settings removed for brevity ...

Migrate 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 theMatchingGame project in theSolution Explorer window and selectUpgrade:
2. SelectIn-place project upgrade.
3. Select.NET 9.0 for the target framework and selectNext.
4. Leave all of the artifacts selected and selectUpgrade 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:

Notice that the project upgrade component mentions that the default font changed. Because the font might 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 theMatchingGame project in theSolution Explorer window and selectClean.
2. Right-click on theMatchingGame project in theSolution Explorer window and selectBuild.

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

TheWindows Forms Matching Game Sample project is now upgraded to .NET 9.

Post-upgrade experience

If you're porting an app from .NET Framework to .NET, review theModernize after upgrading to .NET from .NET Framework article.

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