diff --git a/dotnet-desktop-guide/net/winforms/index.yml b/dotnet-desktop-guide/net/winforms/index.yml index ecfc2b3674..29827098a4 100644 --- a/dotnet-desktop-guide/net/winforms/index.yml +++ b/dotnet-desktop-guide/net/winforms/index.yml @@ -1,13 +1,13 @@ ### YamlMime:Landing title: Windows Forms documentation -summary: Learn about using Windows Forms, an open-source, graphical user interface for Windows, on .NET 7. +summary: Learn about using Windows Forms, an open-source, graphical user interface for Windows, on .NET. metadata: - title: Windows Forms for .NET 7 documentation - description: Learn about using Windows Forms, an open-source, graphical user interface for Windows, on .NET 7. + title: Windows Forms for .NET documentation + description: Learn about using Windows Forms, an open-source, graphical user interface for Windows, on .NET. ms.topic: landing-page - ms.date: 02/08/2023 + ms.date: 04/09/2024 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | sample | tutorial | video | whats-new @@ -32,7 +32,7 @@ landingContent: url: migration/index.md - linkListType: download links: - - text: Visual Studio 2022 version 17.4 + - text: Visual Studio 2022 url: https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2022+desktopguide+winforms - title: Controls diff --git a/dotnet-desktop-guide/net/winforms/migration/index.md b/dotnet-desktop-guide/net/winforms/migration/index.md index 33f194dcd1..6cf45202fa 100644 --- a/dotnet-desktop-guide/net/winforms/migration/index.md +++ b/dotnet-desktop-guide/net/winforms/migration/index.md @@ -1,32 +1,27 @@ --- -title: Upgrade a Windows Forms app to .NET 7 -description: Learn how to upgrade a .NET Framework (or previous .NET) Windows Forms application to .NET 7. -ms.date: 06/01/2023 +title: Upgrade a .NET Framework WinForms app to .NET 8 +description: Learn how to upgrade a .NET Framework (or previous .NET) Windows Forms application to .NET 8 with the Upgrade Assistant in Visual Studio. +ms.date: 04/08/2024 ms.topic: how-to +#customer intent: As a developer, I want to use the .NET Upgrade Assistant to automatically upgrade my projects to the latest version of .NET. --- -# How to upgrade a Windows Forms desktop app to .NET 7 +# Upgrade a .NET Framework Windows Forms desktop app to .NET 8 -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: +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 -You should also review the information in the [Porting from .NET Framework to .NET](/dotnet/core/porting/) guide. - ## Prerequisites -- Windows Operating System -- [Visual Studio 2022 version 17.1 or later to target .NET 7](https://visualstudio.microsoft.com/downloads/) -- [Visual Studio 2022 version 17.7 Preview 1 or later to target .NET 8](https://visualstudio.microsoft.com/downloads/) -- [.NET Upgrade Assistant extension for Visual Studio](/dotnet/core/porting/upgrade-assistant-install#install-the-visual-studio-extension) - -## 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][winforms-sample]. +- Windows Operating System. +- [Download and extract the demo app used with this article.][winforms-sample] +- [Visual Studio 2022 version 17.8 or later to target .NET 8.](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2022+desktopguide+winforms+migration) +- [.NET Upgrade Assistant extension for Visual Studio.](/dotnet/core/porting/upgrade-assistant-install#install-the-visual-studio-extension) -## Initiate the upgrade +## 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. @@ -37,51 +32,61 @@ Use the following steps to upgrade a project in Visual Studio: 01. Right-click on the **MatchingGame.Logic** project in the **Solution Explorer** window and select **Upgrade**: - :::image type="content" source="media/index/vs-upgrade.png" alt-text="The .NET Upgrade Assistant's Upgrade menu item in Visual Studio."::: + :::image type="content" source="media/index/vs-upgrade.png" alt-text="A screenshot of 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. + A new tab is opened that prompts you to choose which type of upgrade you want to perform. + +01. Select **Upgrade project to a newer .NET version**. + + :::image type="content" source="media/index/step-2-initial-tab.png" alt-text="A screenshot of the .NET Upgrade Assistant tab. The 'Upgrade project to a newer .NET version' option is highlighted."::: 01. Select **In-place project upgrade**. -01. 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 Forms 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**. + :::image type="content" source="media/index/step-3-project-upgrade-item.png" alt-text="A screenshot of the .NET Upgrade Assistant tab. The 'In-place project upgrade' option is highlighted."::: + +01. 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. - :::image type="content" source="media/index/vs-target-framework.png" alt-text="The .NET Upgrade Assistant's target framework decision tab."::: + Select **.NET 8.0** and then select **Next**. + + :::image type="content" source="media/index/step-4-net8.png" alt-text="A screenshot of the .NET Upgrade Assistant. The target framework ptompt is open and .NET 8 is highlighted along with the 'Next' button."::: 01. 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: +01. When the upgrade is finished, the results are displayed: - :::image type="content" source="media/index/vs-upgrade-results.png" alt-text="The .NET Upgrade Assistant's upgrade results tab, showing two out of the 13 items were skipped."::: + :::image type="content" source="media/index/step-5-results1.png" alt-text="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 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. 01. Right-click on the **MatchingGame** project in the **Solution Explorer** window and select **Upgrade**: +01. Select **Upgrade project to a newer .NET version**. 01. Select **In-place project upgrade** as the upgrade mode. -01. Select **.NET 7.0** for the target framework and select **Next**. +01. Select **.NET 8.0** for the target framework and select **Next**. 01. 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: +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: -:::image type="content" source="media/index/vs-upgrade-warning.png" alt-text="The .NET Upgrade Assistant's upgrade results tab, showing some of the result items have warning symbols."::: +:::image type="content" source="media/index/step-final-results2.png" alt-text="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 project is upgraded, clean and compile it. +After your main project is upgraded, clean and compile it. 01. Right-click on the **MatchingGame** project in the **Solution Explorer** window and select **Clean**. 01. 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. + -## Conclusion +## Related content + +- [Porting from .NET Framework to .NET.](/dotnet/core/porting/) + + 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.](/dotnet/core/porting/modernize) -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](/dotnet/core/porting/) guide and the [Modernize after upgrading to .NET from .NET Framework](/dotnet/core/porting/modernize) article. + 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. [winforms-sample]: https://github.com/dotnet/samples/tree/main/windowsforms/matching-game diff --git a/dotnet-desktop-guide/net/winforms/migration/media/index/step-2-initial-tab.png b/dotnet-desktop-guide/net/winforms/migration/media/index/step-2-initial-tab.png new file mode 100644 index 0000000000..7eb5773aa5 Binary files /dev/null and b/dotnet-desktop-guide/net/winforms/migration/media/index/step-2-initial-tab.png differ diff --git a/dotnet-desktop-guide/net/winforms/migration/media/index/step-3-project-upgrade-item.png b/dotnet-desktop-guide/net/winforms/migration/media/index/step-3-project-upgrade-item.png new file mode 100644 index 0000000000..4930188210 Binary files /dev/null and b/dotnet-desktop-guide/net/winforms/migration/media/index/step-3-project-upgrade-item.png differ diff --git a/dotnet-desktop-guide/net/winforms/migration/media/index/step-4-net8.png b/dotnet-desktop-guide/net/winforms/migration/media/index/step-4-net8.png new file mode 100644 index 0000000000..4aefc28cd6 Binary files /dev/null and b/dotnet-desktop-guide/net/winforms/migration/media/index/step-4-net8.png differ diff --git a/dotnet-desktop-guide/net/winforms/migration/media/index/step-5-results1.png b/dotnet-desktop-guide/net/winforms/migration/media/index/step-5-results1.png new file mode 100644 index 0000000000..c5d93f856b Binary files /dev/null and b/dotnet-desktop-guide/net/winforms/migration/media/index/step-5-results1.png differ diff --git a/dotnet-desktop-guide/net/winforms/migration/media/index/step-final-results2.png b/dotnet-desktop-guide/net/winforms/migration/media/index/step-final-results2.png new file mode 100644 index 0000000000..6f216f89c8 Binary files /dev/null and b/dotnet-desktop-guide/net/winforms/migration/media/index/step-final-results2.png differ diff --git a/dotnet-desktop-guide/net/winforms/migration/media/index/vs-target-framework.png b/dotnet-desktop-guide/net/winforms/migration/media/index/vs-target-framework.png deleted file mode 100644 index f5f773319d..0000000000 Binary files a/dotnet-desktop-guide/net/winforms/migration/media/index/vs-target-framework.png and /dev/null differ diff --git a/dotnet-desktop-guide/net/winforms/migration/media/index/vs-upgrade-results.png b/dotnet-desktop-guide/net/winforms/migration/media/index/vs-upgrade-results.png deleted file mode 100644 index 0a4fb892e5..0000000000 Binary files a/dotnet-desktop-guide/net/winforms/migration/media/index/vs-upgrade-results.png and /dev/null differ diff --git a/dotnet-desktop-guide/net/winforms/migration/media/index/vs-upgrade-warning.png b/dotnet-desktop-guide/net/winforms/migration/media/index/vs-upgrade-warning.png deleted file mode 100644 index c086f80b60..0000000000 Binary files a/dotnet-desktop-guide/net/winforms/migration/media/index/vs-upgrade-warning.png and /dev/null differ diff --git a/dotnet-desktop-guide/net/winforms/toc.yml b/dotnet-desktop-guide/net/winforms/toc.yml index a0661adb68..1b420a7c30 100644 --- a/dotnet-desktop-guide/net/winforms/toc.yml +++ b/dotnet-desktop-guide/net/winforms/toc.yml @@ -19,7 +19,7 @@ items: href: get-started/create-app-visual-studio.md - name: Migration items: - - name: Upgrade to .NET 7 + - name: How to upgrade to the latest .NET href: migration/index.md - name: Forms items: diff --git a/dotnet-desktop-guide/net/wpf/index.yml b/dotnet-desktop-guide/net/wpf/index.yml index 003476c0e8..d4dd5d43ab 100644 --- a/dotnet-desktop-guide/net/wpf/index.yml +++ b/dotnet-desktop-guide/net/wpf/index.yml @@ -1,13 +1,13 @@ ### YamlMime:Landing title: Windows Presentation Foundation documentation -summary: Learn about using Windows Presentation Foundation (WPF), an open-source, graphical user interface for Windows, on .NET 8. +summary: Learn about using Windows Presentation Foundation (WPF), an open-source, graphical user interface for Windows, on .NET. metadata: title: Windows Presentation Foundation for .NET 8 documentation - description: Learn about using Windows Presentation Foundation (WPF), an open-source, graphical user interface for Windows, on .NET 8. + description: Learn about using Windows Presentation Foundation (WPF), an open-source, graphical user interface for Windows, on .NET. ms.topic: landing-page - ms.date: 02/08/2023 + ms.date: 04/09/2024 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview # quickstart | reference | sample | tutorial | video | whats-new