diff --git a/docs/azure/migration/appmod/overview.md b/docs/azure/migration/appmod/overview.md index 6fe067e8a25ad..f3fb6f0595c7a 100644 --- a/docs/azure/migration/appmod/overview.md +++ b/docs/azure/migration/appmod/overview.md @@ -47,7 +47,7 @@ For more information, see [Predefined tasks](predefined-tasks.md). ### Upgrading .NET projects -Upgrading .NET apps is a common task that requires substantial time and resources. GitHub Copilot App Modernization - upgrade for .NET provides an AI-based solution designed to assist with updating your .NET apps. For more information, see [GitHub Copilot App Modernization - upgrade for .NET](../../../core/porting/github-copilot-app-modernization-overview.md). +Upgrading .NET apps is a common task that requires substantial time and resources. GitHub Copilot app modernization is an AI-based solution designed to assist with updating your .NET apps. For more information, see [GitHub Copilot app modernization](../../../core/porting/github-copilot-app-modernization-overview.md). ## Common use cases diff --git a/docs/core/porting/framework-overview.md b/docs/core/porting/framework-overview.md new file mode 100644 index 0000000000000..feca7a9b36dbb --- /dev/null +++ b/docs/core/porting/framework-overview.md @@ -0,0 +1,217 @@ +--- +title: Port from .NET Framework to .NET +description: Understand the porting process and discover tools you might find helpful when porting a .NET Framework project to .NET. +author: adegeo +ms.date: 09/15/2025 +ms.custom: devdivchpfy22, updateeachrelease +no-loc: ["package.config", PackageReference] +--- +# Overview of porting from .NET Framework to .NET + +This article provides an overview of what you should consider when porting your code from .NET Framework to .NET (formerly named .NET Core). Porting to .NET from .NET Framework is relatively straightforward for many projects. The complexity of your projects dictates how much work you'll need to do after the initial upgrade of the project files. + +Projects where the app model is available in .NET, such as libraries, console apps, and desktop apps, usually require little change. Projects that require a new app model, such as moving to [ASP.NET Core from ASP.NET](/aspnet/core/migration/proper-to-2x/), require more work. Many patterns from the old app model have equivalents that can be used during the conversion. + +## Windows desktop technologies + +Many applications created for .NET Framework use a desktop technology such as Windows Forms or Windows Presentation Foundation (WPF). Both Windows Forms and WPF are available in .NET, but they remain Windows-only technologies. + +Consider the following dependencies before you upgrade a Windows Forms or WPF application: + +- Project files for .NET use a different format than .NET Framework. +- Your project might use an API that isn't available in .NET. +- Third-party controls and libraries might not have been ported to .NET and remain only available to .NET Framework. +- Your project uses a [technology that is no longer available](net-framework-tech-unavailable.md) in .NET. + +.NET uses the open-source versions of Windows Forms and WPF and includes enhancements over .NET Framework. + +For tutorials on upgrading your desktop application to .NET, see one of the following articles: + +- [How to upgrade a WPF desktop app to .NET](/dotnet/desktop/wpf/migration/) +- [Upgrade .NET Framework Windows Forms apps to .NET](/dotnet/desktop/winforms/migration/) + +## Windows-specific APIs + +Applications can still P/Invoke native libraries on platforms supported by .NET. This technology isn't limited to Windows. However, if the library you're referencing is Windows-specific, such as a _user32.dll_ or _kernel32.dll_, then the code only works on Windows. For each platform you want your app to run on, you have to either find platform-specific versions, or make your code generic enough to run on all platforms. + +When you're porting an application from .NET Framework to .NET, your application probably used a library provided by .NET Framework. Many APIs that were available in .NET Framework weren't ported to .NET because they relied on Windows-specific technology, such as the Windows Registry or the GDI+ drawing model. + +The **Windows Compatibility Pack** provides a large portion of the .NET Framework API surface to .NET and is provided via the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility). + +For more information, see [Use the Windows Compatibility Pack to port code to .NET](windows-compat-pack.md). + +## .NET Framework compatibility mode + +The .NET Framework compatibility mode was introduced in .NET Standard 2.0. The compatibility mode allows .NET Standard and .NET projects to reference .NET Framework libraries as if they were compiled for the project's target framework. However, some .NET implementations might support a larger chunk of .NET Framework than others. For example, .NET Core 3.0 extends the .NET Framework compatibility mode to Windows Forms and WPF. Referencing .NET Framework libraries doesn't work for all projects, such as if the library uses WPF APIs, but it does unblock many porting scenarios. For more information, see the [Analyze your dependencies to port code from .NET Framework to .NET](third-party-deps.md#net-framework-compatibility-mode). + +Referencing .NET Framework libraries doesn't work in all cases, as it depends on which .NET Framework APIs were used and whether or not these APIs are supported by the project's target framework. Also, some of the .NET Framework APIs will only work on Windows. The .NET Framework compatibility mode unblocks many porting scenarios but you should test your projects to ensure that they also work at runtime. For more information, see the [Analyze your dependencies to port code from .NET Framework to](third-party-deps.md#net-framework-compatibility-mode). + +## Target framework changes in SDK-style projects + +As previously mentioned, the project files for .NET use a different format than .NET Framework, known as the SDK-style project format. Even if you're not moving from .NET Framework to .NET, you should still upgrade the project file to the latest format. The way to specify a target framework is different in SDK-style projects. In .NET Framework, the `` property is used with a moniker that specifies the version of .NET Framework. For example, .NET Framework 4.7.2 looks like the following snippet: + +```xml + + v4.7.2 + +``` + +An SDK-style project uses a different property to identify the target framework, the `` property. When targeting .NET Framework, the moniker starts with `net` and ends with the version of .NET Framework without any periods. For example, the moniker to target .NET Framework 4.7.2 is `net472`: + +```xml + + net472 + +``` + +For a list of all target monikers, see [Target frameworks in SDK-style projects](../../standard/frameworks.md#supported-target-frameworks). + +## Unavailable technologies + +There are a few technologies in .NET Framework that don't exist in .NET: + +- [Application domains](net-framework-tech-unavailable.md#application-domains) + + Creating other application domains isn't supported. For code isolation, use separate processes or containers as an alternative. + +- [Remoting](net-framework-tech-unavailable.md#remoting) + + Remoting is used for communicating across application domains, which are no longer supported. For simple communication across processes, consider inter-process communication (IPC) mechanisms as an alternative to remoting, such as the class or the class. For more complex scenarios, consider frameworks such as [StreamJsonRpc](https://github.com/microsoft/vs-streamjsonrpc) or [ASP.NET Core](/aspnet/core) (either using [gRPC](/aspnet/core/grpc) or [RESTful Web API services](/aspnet/core/web-api)). + + Because remoting isn't supported, calls to `BeginInvoke()` and `EndInvoke()` on delegate objects throw `PlatformNotSupportedException`. + +- [Code access security (CAS)](net-framework-tech-unavailable.md#code-access-security-cas) + + CAS was a sandboxing technique supported by .NET Framework but deprecated in .NET Framework 4.0. It was replaced by Security Transparency and it isn't supported in .NET. Instead, use security boundaries provided by the operating system, such as virtualization, containers, or user accounts. + +- [Security transparency](net-framework-tech-unavailable.md#security-transparency) + + Similar to CAS, the security transparency sandboxing technique is no longer recommended for .NET Framework applications and it isn't supported in .NET. Instead, use security boundaries provided by the operating system, such as virtualization, containers, or user accounts. + +- + + (COM+) isn't supported in .NET. + +- Windows Workflow Foundation (WF) + + WF isn't supported in .NET. For an alternative, see [CoreWF](https://github.com/UiPath/corewf). + +For more information about these unsupported technologies, see [.NET Framework technologies unavailable on .NET 6+](net-framework-tech-unavailable.md). + +## Cross-platform + +.NET (formerly known as .NET Core) is designed to be cross-platform. If your code doesn't depend on Windows-specific technologies, it can run on other platforms such as macOS, Linux, and Android. Such code includes project types like: + +- Libraries +- Console-based tools +- Automation +- ASP.NET sites + +.NET Framework is a Windows-only component. When your code uses Windows-specific technologies or APIs, such as Windows Forms and WPF, the code can still run on .NET but it doesn't run on other operating systems. + +It's possible that your library or console-based application can be used cross-platform without changing much. When you're porting to .NET, you might want to take this into consideration and test your application on other platforms. + +## The future of .NET Standard + +.NET Standard is a formal specification of .NET APIs that are available on multiple .NET implementations. The motivation behind .NET Standard was to establish greater uniformity in the .NET ecosystem. Starting with .NET 5, a different approach to establishing uniformity has been adopted, and this new approach eliminates the need for .NET Standard in many scenarios. For more information, see [.NET 5+ and .NET Standard](../../standard/net-standard.md#net-5-and-net-standard). + +.NET Standard 2.0 was the last version to support .NET Framework. + +## Tools to assist porting + +Instead of manually porting an application from .NET Framework to .NET, you can use different tools to help automate some aspects of the upgrade. Porting a complex project is, in itself, a complex process. The tools might help in that journey. + +Even if you use a tool to help port your application, you should review the [Considerations when porting section](#considerations-when-porting) in this article. + +### GitHub Copilot app modernization assistant + +[GitHub Copilot app modernization](github-copilot-app-modernization-overview.md) is a GitHub Copilot chat assistant that helps you plan and upgrade projects to newer versions of .NET, migrate to Azure, update dependencies, and apply code fixes. Azure migration is powered by [Application and code assessment for .NET](../../azure/migration/appcat/app-code-assessment-toolkit.md) + +This chat assistant supports the following upgrade paths: + +- Upgrade projects from older .NET versions to the latest. +- Upgrade projects from .NET Framework to the latest version of .NET. +- Modernize your code base with new features. +- Migrate components and services to Azure. + +It also works on various project types, such as: + +- ASP.NET and related technologies such as MVC, Razor Pages, Web API +- Blazor +- Azure Functions +- Windows Presentation Foundation +- Windows Forms +- Class libraries +- Console apps + +**When to use:** + +Use GitHub Copilot app modernization when you want an AI-powered, end-to-end experience to upgrade .NET Framework projects and dependencies to modern .NET—covering assessment, planning, remediation, and guidance for migrating applications to Azure. + +### Application and code assessment for .NET + +[Azure Migrate application and code assessment for .NET](../../azure/migration/appcat/app-code-assessment-toolkit.md) provides code and application analysis, along with recommendations for planning cloud deployments. It helps you confidently run business-critical solutions in the cloud by offering a developer-focused assessment of your source code. The tool also provides recommendations and examples to optimize code and configurations for Azure, following industry best practices. + +This tool is also used by the GitHub Copilot app modernization for .NET experience. + +**When to use:** + +Use the Azure Migrate application and code assessment for .NET toolset for an assessment of and recommendations for migrating an existing code base to Azure. The Azure Migrate application and code assessment is essentially a subset of the GitHub Copilot app modernization for .NET experience. + +### .NET Upgrade Assistant + +The [.NET Upgrade Assistant](upgrade-assistant-overview.md) is a command-line tool that can be run on different kinds of .NET Framework apps. It's designed to assist with upgrading .NET Framework apps to .NET. After running the tool, **in most cases the app will require more effort to complete the upgrade**. The tool includes the installation of analyzers that can assist with completing the upgrade. This tool works on the following types of .NET Framework applications: + +- Windows Forms +- WPF +- ASP.NET MVC +- Console +- Class libraries + +This tool uses the other tools listed in this article, such as **try-convert**, and guides the upgrade process. For more information about the tool, see [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md). + +**When to use:** + +Use when an AI powered solution like GitHub Copilot app modernization isn't available. + +### `try-convert` + +The `try-convert` tool is a .NET global tool that can convert a project or entire solution to the .NET SDK, including moving desktop apps to .NET. However, this tool isn't recommended if your project has a complicated build process such as custom tasks, targets, or imports. + +For more information, see the [`try-convert` GitHub repository](https://github.com/dotnet/try-convert). + +### Platform compatibility analyzer + +The [Platform compatibility analyzer](../../standard/analyzers/platform-compat-analyzer.md) analyzes whether or not you're using an API that throws a at run time. Although finding one of these APIs is unlikely if you're moving from .NET Framework 4.7.2 or higher, it's good to check. For more information about APIs that throw exceptions on .NET, see [APIs that always throw exceptions on .NET Core](../compatibility/unsupported-apis.md). + +For more information, see [Platform compatibility analyzer](../../standard/analyzers/platform-compat-analyzer.md). + +## Considerations when porting + +When porting your application to .NET, consider the following suggestions in order: + +✔️ CONSIDER using the [GitHub Copilot app modernization](github-copilot-app-modernization-overview.md) to upgrade your projects. GitHub Copilot is powerful at identifying and fixing incompatibilities when porting. It automates most of the manual steps detailed in this article and gives you a great starting point for continuing your upgrade path. + +✔️ CONSIDER examining your dependencies first. Your dependencies must target .NET, .NET Standard, or .NET Core. + +✔️ DO upgrade from a NuGet _packages.config_ file to [PackageReference](/nuget/consume-packages/package-references-in-project-files) settings in the project file. Use Visual Studio to [convert the _package.config_ file](/nuget/consume-packages/migrate-packages-config-to-package-reference#migration-steps). + +✔️ CONSIDER upgrading to the latest project file format even if you can't yet port your app. .NET Framework projects use an outdated project format. Even though the latest project format, known as SDK-style projects, was created for .NET Core and beyond, the format also works with .NET Framework. Having your project file in the latest format gives you a good basis for porting your app in the future. + +✔️ DO retarget your .NET Framework project to at least .NET Framework 4.7.2. This ensures the availability of the latest API alternatives for cases where .NET Standard doesn't support existing APIs. + +✔️ CONSIDER targeting .NET 8, which is a long-term support (LTS) release. + +✔️ DO target .NET 8+ for **Windows Forms and WPF** projects. .NET 8 and later versions contain many improvements for Desktop apps. + +✔️ CONSIDER targeting .NET Standard 2.0 if you're upgrading a library that might also be used with .NET Framework projects. You can also multitarget your library, targeting both .NET Framework and .NET Standard. + +✔️ DO add reference to the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility) if, after migrating, you get errors of missing APIs. A large portion of the .NET Framework API surface is available to .NET via the NuGet package. + +## See also + +- [What is GitHub Copilot app modernization](github-copilot-app-modernization-overview.md) +- [ASP.NET to ASP.NET Core migration](/aspnet/core/migration/proper-to-2x) +- [Upgrade a WPF desktop app to .NET](/dotnet/desktop/wpf/migration/) +- [Upgrade a Windows Forms app to .NET](/dotnet/desktop/winforms/migration/) +- [.NET vs. .NET Framework for server apps](../../standard/choosing-core-framework-server.md) diff --git a/docs/core/porting/github-copilot-app-modernization-faq.yml b/docs/core/porting/github-copilot-app-modernization-faq.yml index 501980180fde6..db8c6cdc6df57 100644 --- a/docs/core/porting/github-copilot-app-modernization-faq.yml +++ b/docs/core/porting/github-copilot-app-modernization-faq.yml @@ -6,11 +6,11 @@ metadata: author: adegeo ms.author: adegeo ms.topic: faq - ms.date: 09/04/2025 + ms.date: 09/15/2025 -title: GitHub Copilot app modernization - upgrade for .NET FAQ +title: GitHub Copilot app modernization FAQ summary: | - GitHub Copilot app modernization - upgrade for .NET is an interactive GitHub Copilot extension that adds powerful upgrade capabilities to Visual Studio. This article answers frequently asked questions. For more information about the tool, see [What is GitHub Copilot app modernization - upgrade for .NET?](github-copilot-app-modernization-overview.md). + GitHub Copilot app modernization is an interactive GitHub Copilot agent that adds powerful upgrade capabilities to Visual Studio. This article answers frequently asked questions. For more information about the modernization agent, see [What is GitHub Copilot app modernization](github-copilot-app-modernization-overview.md). The tool requires one of the following GitHub Copilot subscriptions: @@ -19,12 +19,14 @@ summary: | - Copilot Business - Copilot Enterprise + GitHub Copilot app modernization is included in [Visual Studio 2022 version 17.14.16 or newer](https://visualstudio.microsoft.com/downloads/). + sections: - - name: Scenarios + - name: Modernization agent questions: - - question: What can the tool do? + - question: What can the agent do? answer: | - Currently, GitHub Copilot app modernization - upgrade for .NET helps you upgrade your .NET projects to newer versions of .NET. The tool is an extension for Visual Studio that performs the following steps in a GitHub Copilot chat session: + Currently, GitHub Copilot app modernization helps you upgrade your .NET (.NET, .NET Core, and .NET Framework) projects to newer versions of .NET. It also helps migrate services to Azure. It also upgrades dependencies and fixes errors in the code post-migration. The agent performs the following steps in a GitHub Copilot chat session: - Analyzes your projects and proposes an upgrade plan. - According to the plan, runs a series of tasks to upgrade your projects. @@ -33,11 +35,44 @@ sections: - Reports progress and allow access to code changes & logs. - Learns from the interactive experience with you (within the context of the session) to improve subsequent transformations. - - question: What can the tool upgrade? + - question: What limitations are there? + answer: | + - Only Git repositories are supported. + - There's no guarantee that the upgrade suggestions are considered best practices. + - The LLM doesn't persist learning from the upgrade. Meaning, code fixes and corrections you provide during the upgrade process don't persist and can't be remembered for future upgrades. + - It only runs on Windows. + + - question: Which model should I use? answer: | - GitHub Copilot app modernization - upgrade for .NET currently focuses on migrating your projects from one version of .NET to another. For example, upgrading from .NET Core 3.1 or .NET 6, to .NET 9. It also upgrades dependencies and fixes errors in the code post-migration. + You should use a good coding model, such as Claude Sonnet 4.0 or Claude Sonnet 3.7. - Besides upgrading the target framework, the tool can work with the following types of projects: + - question: Can I train the model based on my code base? + answer: | + No. Unlike traditional AI tools where you might enter freeform prompts, the agent operates in a more structured way. The AI is embedded within the build-and-fix process, meaning the prompts it uses are predefined and tied to the upgrade plan. So it's not something you can train on your codebase, and it's not something you can manually steer with custom instructions, beyond the changes you can make to the plan Markdown file. + + However, the agent does have some adaptability within a session. If you manually adjust a fix, it learns from that interaction in the short term and applies similar corrections if it encounters the same issue again. Think of it as refining its approach within the scope of that upgrade. + + - question: Does the agent store my source code? + answer: | + The agent never stores a user's codebase and never uses your code for training the model. Once an upgrade is complete, session data is deleted. + + - question: Can I provide feedback? + answer: | + Yes! Use the [Suggest a feature](/visualstudio/ide/suggest-a-feature) and [Report a Problem](/visualstudio/ide/report-a-problem) features of in Visual Studio to provide feedback. + + - question: What data is collected? + answer: | + The agent only collects telemetry information about project types, intent to upgrade, and upgrade duration. The data is aggregated through Visual Studio itself and doesn't contain any user-identifiable information. For more information about Microsoft's privacy policy, see [Visual Studio Customer Experience Improvement Program](/visualstudio/ide/visual-studio-experience-improvement-program?view=vs-2022). + + - question: Can I disable telemetry? + answer: | + Yes, you can disable telemetry. In Visual Studio, select **Help** > **Privacy** > **Privacy Settings** > **"No, I would not like to participate."** + + - name: Upgrade .NET apps + questions: + - question: What can the agent upgrade? + answer: | + GitHub Copilot app modernization helps you upgrade your .NET projects or migrate them to Azure. Besides upgrading the target framework, the agent can work with the following types of projects: - Azure Functions. - Console apps and class libraries. @@ -50,28 +85,30 @@ sections: - Test projects such as MSTest and NUnit. - .NET Framework projects. - - question: What limitations are there? + - name: Migrate to Azure + questions: + - question: What can the agent migrate? answer: | - - Only Git repositories are supported. - - There's no guarantee that the upgrade suggestions are considered best practices. - - The LLM doesn't persist learning from the upgrade. Meaning, code fixes and corrections you provide during the upgrade process don't persist and can't be remembered for future upgrades. - - It only runs on Windows. + The agent can assist in migrating your .NET applications to Azure, including: + - Web apps + - API apps + - Azure Functions + - Containerized applications - - question: What data is collected? + - question: Can I monitor assessment progress? answer: | - The tool only collects telemetry information about project types, intent to upgrade, and upgrade duration. The data is aggregated through Visual Studio itself and doesn't contain any user-identifiable information. For more information about Microsoft's privacy policy, see [Visual Studio Customer Experience Improvement Program](/visualstudio/ide/visual-studio-experience-improvement-program?view=vs-2022). + Yes, you can monitor the progress of the assessment through the Visual Studio interface. The agent provides real-time feedback and updates on the status of the migration process. - - question: Can I disable telemetry? - answer: | - Yes, you can disable telemetry. In Visual Studio, select **Help** > **Privacy** > **Privacy Settings** > **"No, I would not like to participate."** + While the assessment is running, you can monitor its progress by viewing the command-line output: - - question: Can I train the model based on my code base? - answer: | - No. Unlike traditional AI tools where you might enter freeform prompts, the tool operates in a more structured way. The AI is embedded within the build-and-fix process, meaning the prompts it uses are predefined and tied to the upgrade plan. So it's not something you can train on your codebase, and it's not something you can manually steer with custom instructions, beyond the changes you can make to the plan Markdown file. + 1. In Visual Studio, go to **View** > **Output** to open the Output window. + 2. In the Output window, find the **Show output from:** dropdown. + 3. Select **AppModernizationExtension** from the dropdown list. + 4. The command-line output from the assessment tool appears here, showing real-time progress. - However, the tool does have some adaptability within a session. If you manually adjust a fix, it learns from that interaction in the short term and applies similar corrections if it encounters the same issue again. Think of it as refining its approach within the scope of that upgrade. We never store a user's codebase and never use your code for training the model. Once an upgrade is complete, session data is deleted and not stored. + You can also access the **Output** window using the keyboard shortcut Ctrl+Alt+O. additionalContent: | ## Related content - To learn more, see [What is GitHub Copilot app modernization - upgrade for .NET?](github-copilot-app-modernization-overview.md). + To learn more, see [What is GitHub Copilot app modernization?](github-copilot-app-modernization-overview.md). diff --git a/docs/core/porting/github-copilot-app-modernization-install.md b/docs/core/porting/github-copilot-app-modernization-install.md index c07bc5aeb1504..e919c6e8633c3 100644 --- a/docs/core/porting/github-copilot-app-modernization-install.md +++ b/docs/core/porting/github-copilot-app-modernization-install.md @@ -1,24 +1,27 @@ --- -title: Install GitHub Copilot app modernization - upgrade for .NET -description: "Learn how to install the GitHub Copilot app modernization - upgrade for .NET Visual Studio extension. App modernization assists you when upgrading projects to the latest dependencies or when upgrading to a new version of .NET" +title: Install GitHub Copilot app modernization +description: "Learn how to install the GitHub Copilot app modernization Visual Studio extension. App modernization assists you when upgrading projects to the latest dependencies or when upgrading to a new version of .NET" titleSuffix: "" author: adegeo ms.author: adegeo ms.topic: install-set-up-deploy -ms.date: 09/04/2025 +ms.date: 09/15/2025 #customer intent: As a developer, I want to install GitHub Copilot App Modernization so that I can upgrade my projects. --- -# Install GitHub Copilot app modernization - upgrade for .NET +# Install GitHub Copilot app modernization -This article guides you through installing GitHub Copilot app modernization - upgrade for .NET extension in Visual Studio. +This article guides you through installing the GitHub Copilot app modernization extension in Visual Studio. + +> [!IMPORTANT] +> The GitHub Copilot Modernization agent is included in Visual Studio, starting with Visual Studio 2022 17.14.16 and Visual Studio 2026. ## Prerequisites - Windows operating system -- [Visual Studio 2022 version 17.14 or newer](https://visualstudio.microsoft.com/downloads/) +- [Visual Studio 2022 version 17.14.15 or earlier](https://visualstudio.microsoft.com/downloads/) - [.NET desktop development workload](/visualstudio/install/modify-visual-studio?view=vs-2022&preserve-view=true#change-workloads-or-individual-components) While not required to _install_ the extension, to use the extension you must [sign in to Visual Studio using a GitHub account](/visualstudio/ide/work-with-github-accounts) with [Copilot access](https://docs.github.com/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). @@ -65,4 +68,4 @@ There are two ways to determine if GitHub Copilot App Modernization is installed ## Related content -- [What is GitHub Copilot app modernization - upgrade for .NET?](github-copilot-app-modernization-overview.md) +- [What is GitHub Copilot app modernization?](github-copilot-app-modernization-overview.md) diff --git a/docs/core/porting/github-copilot-app-modernization-overview.md b/docs/core/porting/github-copilot-app-modernization-overview.md index 0fc522bd3767f..258f09a2771bf 100644 --- a/docs/core/porting/github-copilot-app-modernization-overview.md +++ b/docs/core/porting/github-copilot-app-modernization-overview.md @@ -1,28 +1,48 @@ --- -title: GitHub Copilot app modernization - upgrade for .NET overview -description: "Learn more about GitHub Copilot app modernization - upgrade for .NET. This Visual Studio extension helps you upgrade your code and projects. Upgrades can include .NET versioning or migrating code from one technology to another." +title: GitHub Copilot app modernization overview +description: "Learn more about GitHub Copilot app modernization. This Visual Studio extension helps you upgrade your code and projects. Upgrades can include .NET versioning or migrating code from one technology to another." titleSuffix: "" author: adegeo ms.author: adegeo ms.topic: overview -ms.date: 09/04/2025 +ms.date: 09/15/2025 #customer intent: As a developer, I want to upgrade my project so that I can take advantage of the latest features. --- -# What is GitHub Copilot app modernization - upgrade for .NET? +# What is GitHub Copilot app modernization -GitHub Copilot app modernization - upgrade for .NET is a powerful Visual Studio extension that works with you to upgrade projects to newer versions of .NET, upgrade your dependencies, and apply code fixes. +GitHub Copilot app modernization is a GitHub Copilot agent that helps upgrade projects to newer versions of .NET and migrate .NET applications to Azure quickly and confidently by guiding you through assessment, solution recommendations, code fixes, and validation - all within Visual Studio. -GitHub Copilot app modernization is distributed as a Visual Studio extension, and is an interactive upgrade process. +This process streamlines modernization and boosts developer productivity and confidence. GitHub Copilot app modernization is an all-in-one upgrade and migration assistant that uses AI to improve developer velocity, quality, and results. + +With this assistant, you can: + +- Upgrade to a newer version of .NET. +- Migrate technologies to Azure. +- Modernize your .NET app, especially when upgrading from .NET Framework. +- Assess your application's code, configuration, and dependencies. +- Plan and set up the right Azure resource. +- Fix issues and apply best practices for cloud migration. +- Validate that your app builds and tests successfully. + +## Provide feedback + +Feedback is important to Microsoft and the efficiency of this agent. Use the [Suggest a feature](/visualstudio/ide/suggest-a-feature) and [Report a problem](/visualstudio/ide/report-a-problem) features of Visual Studio to provide feedback. ## Prerequisites - Windows Operating System -- [Visual Studio 2022 version 17.14 or newer](https://visualstudio.microsoft.com/downloads/). -- [.NET desktop development workload](/visualstudio/install/modify-visual-studio?view=vs-2022&preserve-view=true#change-workloads-or-individual-components). -- [Sign in to Visual Studio using a GitHub account](/visualstudio/ide/work-with-github-accounts) with [Copilot access](https://docs.github.com/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). +- [Visual Studio 2022 version 17.14.16 or newer](https://visualstudio.microsoft.com/downloads/). (To be released) +- [.NET desktop development workload](/visualstudio/install/modify-visual-studio?view=vs-2022&preserve-view=true#change-workloads-or-individual-components) with the following optional components enabled: + + - GitHub Copilot + - GitHub Copilot app modernization for .NET + +- Copilot license and supported subscription plan: + + [Sign in to Visual Studio using a GitHub account](/visualstudio/ide/work-with-github-accounts) with [Copilot access](https://docs.github.com/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). Supported subscription plans: @@ -31,17 +51,13 @@ GitHub Copilot app modernization is distributed as a Visual Studio extension, an - Copilot Business - Copilot Enterprise -(If you change subscriptions, you must restart Visual Studio.) + (If you change subscriptions, you must restart Visual Studio.) -- Code must be in a local Git repository. - Code must be written in C#. -- Optional but recommended: Use **GitHub Copilot agent mode** for the upgrade process. For more information, see [Use Copilot agent mode in Visual Studio](/visualstudio/ide/copilot-agent-mode?view=vs-2022&preserve-view=true). -For installation instructions, see [Install GitHub Copilot app modernization - upgrade for .NET](github-copilot-app-modernization-install.md). +## Upgrade .NET projects -## Supported project types - -GitHub Copilot app modernization supports upgrading projects coded in C#. The following types of projects are supported: +The modernization agent supports upgrading projects coded in C#. The following types of projects are supported: - ASP.NET and related technologies such as MVC, Razor Pages, Web API - Blazor @@ -51,145 +67,96 @@ GitHub Copilot app modernization supports upgrading projects coded in C#. The fo - Class libraries - Console apps -## Upgrade paths - -The following upgrade paths are supported: +To learn how to start an upgrade, see [How to upgrade a .NET app with GitHub Copilot app modernization](how-to-upgrade-with-github-copilot.md). -- Upgrade projects from .NET Core to .NET. -- Upgrade projects from older versions of .NET to the latest. -- Modernize your code base. +### Upgrade paths -## Start the upgrade process +The following upgrade paths are supported: -The first step to upgrading is generating a plan by interacting with GitHub Copilot. There are two ways to get Copilot to use the tool: +- Upgrade projects from older .NET versions to the latest. +- Upgrade projects from .NET Framework to the latest version of .NET. +- Modernize your code base with new features. +- Migrate components and services to Azure. -- Right-click on the solution or project and select **Upgrade with GitHub Copilot**. +## Migrate .NET projects to Azure - —or— +The modernization agent combines automated analysis, AI-driven code remediation, build and vulnerability checks, and deployment automation to simplify migrations to Azure. The following capabilities describe how the agent assesses readiness, applies fixes, and streamlines the migration process: -- [Enable GitHub Copilot agent mode](/visualstudio/ide/copilot-agent-mode?view=vs-2022&preserve-view=true), and ask a new Copilot chat to upgrade the solution or project. +- Analysis & Intelligent Recommendations. - > [!IMPORTANT] - > After enabling GitHub Copilot agent mode, set the chat mode to **Agent** and enable the **upgrade_start** tool. - > - > :::image type="content" source="media/github-copilot-app-modernization-overview/copilot-agent-tools.png" alt-text="The GitHub Copilot chat window. The Agent Mode dropdown and Tool selection dropdown are both highlighted."::: + Assess your application's readiness for Azure migration and receive tailored guidance based on its dependencies and identified issues. -## Generate a plan +- AI-Powered Code Remediation. -Once the process starts, Copilot analyzes your projects and their dependencies, and then asks you a series of questions about the upgrade. After you answer these questions, an upgrade plan is written in the form of a Markdown file. If you tell Copilot to proceed with the upgrade, this plan describes the steps of the upgrade process. + Apply predefined best-practice code patterns to accelerate modernization with minimal manual effort. -You can adjust the plan by editing the Markdown file to change the upgrade steps or add more context. +- Automatic Build and CVE Resolution. -> [!CAUTION] -> The plan is generated based on the inter-dependencies of your projects. The upgrade won't succeed if you modify the plan in such a way that the migration path can't complete. For example, if **Project A** depends on **Project B** and you remove **Project B** from the upgrade plan, upgrading **Project A** might fail. + Automatically builds your app and resolves compilation errors and vulnerabilities, streamlining development. -The following snippet demonstrates the structure of a plan: +- Seamless Deployment. -```md -# .NET 9.0 Upgrade Plan + Deploy to Azure effortlessly, taking your code from development to cloud faster than ever. -## Execution Steps +### Predefined tasks for migration -1. Validate that an .NET 9.0 SDK required for this upgrade is installed on the machine and if not, help to get it installed. -2. Ensure that the SDK version specified in global.json files is compatible with the .NET 9.0 upgrade. -3. Upgrade projects to .NET 9.0. - - 3.1. Upgrade RazorMovie.csproj - - 3.2. Upgrade RazorMovie.Tests.csproj -4. Run unit tests to validate upgrade in the projects listed below: - - RazorMovie.Tests.csproj +Predefined tasks capture industry best practices for using Azure services. Currently, App Modernization for .NET (Preview) offers predefined tasks that cover common migration scenarios. -## Settings +- **Migrate to Managed Identity based Database on Azure, including Azure SQL DB, Azure SQL MI, and Azure PostgreSQL** -This section contains settings and data used by execution steps. + Modernize your data layer by migrating from on-premises or legacy databases (such as DB2, Oracle DB, or SQL Server) to Azure SQL DB, Azure SQL Managed Instance, or Azure PostgreSQL, using secure managed identity authentication. -### Aggregate NuGet packages modifications across all projects +- **Migrate to Azure File Storage** -NuGet packages used across all selected projects or their dependencies that need version update in projects that reference them. + Move file I/O operations from the local file system to Azure File Storage for scalable, cloud-based file management. -| Package Name | Current Version | New Version | Description | -|:-------------------------------------------------|:-------------------:|:-----------:|:-------------------------| -| HtmlSanitizer | 7.1.542 | 9.0.884 | Security vulnerability | -| Microsoft.Data.SqlClient | 4.0.5 | 6.0.2 | Deprecated | -| Microsoft.EntityFrameworkCore.Design | 6.0.0-rtm.21467.1 | 9.0.5 | Recommended for .NET 9.0 | -| Microsoft.EntityFrameworkCore.SqlServer | 6.0.0-rc.1.21452.10 | 9.0.5 | Recommended for .NET 9.0 | -| Microsoft.EntityFrameworkCore.Tools | 6.0.0-rc.1.21452.10 | 9.0.5 | Recommended for .NET 9.0 | -| Microsoft.VisualStudio.Web.CodeGeneration.Design | 6.0.0-rc.1.21464.1 | 9.0.0 | Recommended for .NET 9.0 | +- **Migrate to Azure Blob Storage** -... -``` + Replace on-premises or cross-cloud object storage, or local file system file I/O, with Azure Blob Storage for unstructured data. -## Perform the upgrade +- **Migrate to Microsoft Entra ID** -Once an upgrade plan is ready, tell Copilot to start the upgrade. Once the upgrade process starts, Copilot lets you know what it's doing in the chat window and it opens the **Upgrade Progress Details** document, which lists the status of every step. If it runs into a problem, Copilot pauses and asks for your direction or help in fixing these problems. + Transition authentication and authorization from Windows Active Directory to Microsoft Entra ID (formerly Azure AD) for modern identity management. -The tool differs in experience based on whether or not Copilot _agent mode_ is enabled. +- **Migrate to secured credentials with Managed Identity and Azure Key Vault** -- **Copilot agent mode** + Replace plaintext credentials in configuration or code with secure, managed identities and Azure Key Vault for secrets management. - When Copilot agent mode is enabled and used, Copilot tries to identify the cause of a problem and apply a fix. If Copilot can't seem to correct the problem, it asks for your help. When you intervene, Copilot learns from the changes you make and tries to automatically apply them for you, if the problem is encountered again. +- **Migrate to Azure Service Bus** -- **Copilot fix mode** + Move from legacy or third-party message queues (such as MSMQ or RabbitMQ) to Azure Service Bus for reliable, cloud-based messaging. - Copilot fix mode is used if agent mode is disabled or not used. Copilot reports the problems it finds and guides you through the fixes required. It relies on you to perform the actual code changes and then it verifies those fixes. +- **Migrate to Azure Communication Service email** -Each major step in the upgrade process is committed to the local Git repository. + Replace direct SMTP email sending with Azure Communication Service for scalable, secure email delivery. -## Upgrade results +- **Migrate to Confluent Cloud/Azure Event Hub for Apache Kafka** -When the upgrade completes, a report is generated that describes every step of the upgrade. The tool creates a Git commit for every portion of the upgrade process, so you can easily roll back the changes or get detailed information about what changed. The report contains the Git commit hashes. + Transition from local or on-premises Kafka to managed event streaming with Confluent Cloud or Azure Event Hubs. -The report also provides a _Next steps_ section that describes the steps you should take after the upgrade finishes. The following example shows the report of a completed upgrade that contained a test failure: +- **Migrate to OpenTelemetry on Azure** -```md -# .NET 9 Upgrade Report + Transition from local logging frameworks like log4net, serilog, and Windows event log to OpenTelemetry on Azure. -## Project modifications +## How does it work -| Project name | Old Target Framework | New Target Framework | Commits | -|:-----------------------------------------------|:-----------------------:|:----------------------------:|---------------------------| -| RazorMovie | net6.0 | net9.0 | af8cf633, aa61a18d | -| MvcMovie | net6.0 | net9.0 | cc8c9015 | -| WpfMovie | net6.0-windows | net9.0-windows | 9c4b13f9 | -| RazorMovie.Tests | net6.0 | net9.0 | b8d85e97 | -| MvcMovie.Tests | net6.0 | net9.0 | b8d85e97 | -| WpfMovie.Tests | net6.0-windows | net9.0-windows7.0 | b8d85e97 | +Once you request the modernization agent to upgrade or migrate your app, Copilot analyzes your projects and their dependencies, and then asks you a series of questions about the upgrade or migration. After you answer these questions, a plan is written in the form of a Markdown file. If you tell Copilot to proceed with the upgrade or migration, it follows the steps described in the plan. -## NuGet Packages +You can adjust the plan by editing the Markdown file to change the upgrade steps or add more context. -| Package Name | Old Version | New Version | Commit Id | -|:-------------------------------------------------|:-------------------:|:-----------:|-----------| -| HtmlSanitizer | 7.1.542 | 9.0.884 | af8cf633 | -| Microsoft.Data.SqlClient | 4.0.5 | 6.0.2 | bf8deeac | -| Microsoft.EntityFrameworkCore.Design | 6.0.0-rtm.21467.1 | 9.0.5 | bf8deeac | -| Microsoft.EntityFrameworkCore.SqlServer | 6.0.0-rc.1.21452.10 | 9.0.5 | bf8deeac | -| Microsoft.EntityFrameworkCore.Tools | 6.0.0-rc.1.21452.10 | 9.0.5 | bf8deeac | -| Microsoft.VisualStudio.Web.CodeGeneration.Design | 6.0.0-rc.1.21464.1 | 9.0.0 | bf8deeac | +### Perform the upgrade or migration -## All commits +Once a plan is ready, tell Copilot to start using it. Once the process starts, Copilot lets you know what it's doing in the chat window and it opens the **Upgrade Progress Details** document, which lists the status of every step. -| Commit ID | Description | -|:----------|:--------------------------------------------------------| -| af8cf633 | Update HtmlSanitizer package in RazorMovie.csproj | -| aa61a18d | Upgrade target framework in RazorMovie.csproj | -| cc8c9015 | Upgrade to .NET 9 and update dependencies | -| bf8deeac | Update package references in MvcMovie.csproj | -| 9c4b13f9 | Update WpfMovie.csproj to target .NET 9.0 | -| b8d85e97 | Update test projects to .NET 9 and enhance dependencies | +If it runs into a problem, Copilot tries to identify the cause of a problem and apply a fix. If Copilot can't seem to correct the problem, it asks for your help. When you intervene, Copilot learns from the changes you make and tries to automatically apply them for you, if the problem is encountered again. -## Test Results +Each major step in the plan is committed to the local Git repository. -| Project Name | Passed | Failed | Skipped | -|:-----------------------|:------:|:------:|:-------:| -| RazorMovie.Tests | 0 | 0 | 0 | -| MvcMovie.Tests | 2 | 0 | 0 | -| WpfMovie.Tests | 6 | 1 | 0 | +### Upgrade and migration results -## Next steps +When the process completes, a report is generated that describes every step taken by Copilot. The tool creates a Git commit for every portion of the process, so you can easily roll back the changes or get detailed information about what changed. The report contains the Git commit hashes. -- Review the test results and address the single failing test in `WpfMovie.Tests`. -- Ensure all updated NuGet packages are compatible with your application. -- Leverage new features and improvements in .NET 9.0 for your projects. -``` +The report also provides a _Next steps_ section that describes the steps you should take after the upgrade finishes. ## Telemetry @@ -197,5 +164,5 @@ The tool only collects data about project types, intent to upgrade, and upgrade ## Related content -- [Install GitHub Copilot app modernization - upgrade for .NET](github-copilot-app-modernization-install.md) -- [GitHub Copilot app modernization - upgrade for .NET FAQ](github-copilot-app-modernization-faq.yml) +- [How to upgrade a .NET app with GitHub Copilot app modernization](how-to-upgrade-with-github-copilot.md) +- [GitHub Copilot app modernization FAQ](github-copilot-app-modernization-faq.yml) diff --git a/docs/core/porting/how-to-upgrade-with-github-copilot.md b/docs/core/porting/how-to-upgrade-with-github-copilot.md new file mode 100644 index 0000000000000..bf9d77776124e --- /dev/null +++ b/docs/core/porting/how-to-upgrade-with-github-copilot.md @@ -0,0 +1,174 @@ +--- +title: How to upgrade a .NET app with GitHub Copilot app modernization +description: "Learn how to upgrade your .NET applications to newer versions using GitHub Copilot app modernization in Visual Studio. This step-by-step guide covers planning, execution, and validation." +author: adegeo +ms.author: adegeo +ms.topic: how-to +ms.date: 09/15/2025 +ai-usage: ai-assisted + +#customer intent: As a developer, I want to upgrade my .NET app using GitHub Copilot app modernization so that I can modernize my codebase efficiently with AI assistance. + +--- + +# How to upgrade a .NET app with GitHub Copilot app modernization + +GitHub Copilot app modernization is an AI-powered agent in Visual Studio that helps you upgrade .NET projects to newer versions and migrate applications to Azure. This article guides you through the process of using this tool to modernize your .NET applications, from initial assessment to final validation. + +The modernization agent analyzes your projects and dependencies, creates an upgrade plan, and assists with code fixes throughout the process. It supports upgrading from older .NET versions to the latest, including migrations from .NET Framework to modern .NET. + +## Prerequisites + +Before you begin, ensure you have the following requirements: + +- Windows Operating System +- [Visual Studio 2022 version 17.14.16 or newer](https://visualstudio.microsoft.com/downloads/) (To be released) +- [.NET desktop development workload](/visualstudio/install/modify-visual-studio?view=vs-2022&preserve-view=true#change-workloads-or-individual-components) with the following optional components enabled: + - GitHub Copilot + - GitHub Copilot app modernization for .NET +- GitHub account with Copilot access and supported subscription plan: + - [Sign in to Visual Studio using a GitHub account](/visualstudio/ide/work-with-github-accounts) with [Copilot access](https://docs.github.com/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot) + - Supported subscription plans: Copilot Pro, Copilot Pro+, Copilot Business, or Copilot Enterprise + - If you change subscriptions, you must restart Visual Studio +- A .NET project written in C# that you want to upgrade + +## Start the upgrade process + +The first step to upgrading is generating a plan by interacting with GitHub Copilot. Follow these steps to initiate the upgrade: + +1. Open your .NET project or solution in Visual Studio. +1. Access the GitHub Copilot app modernization agent using one of these methods: + + Right-click on the solution or project in **Solution Explorer** and select **Modernize**. + + —or— + + Open the **GitHub Copilot Chat** window and type `@modernize` followed by your upgrade request. + +1. Tell the `@modernize` agent what you want to upgrade. + +## Generate an upgrade plan + +Once the process starts, Copilot analyzes your projects and their dependencies, and then asks you a series of questions about the upgrade. After you answer these questions, an upgrade plan is written in the form of a Markdown file. + +To generate and customize your plan: + +1. Answer Copilot's questions about your upgrade requirements and preferences. +1. Review the generated upgrade plan in the Markdown file. +1. Optionally, edit the Markdown file to change the upgrade steps or add more context. +1. Tell Copilot to proceed with the upgrade when you're satisfied with the plan. + +> [!CAUTION] +> The plan is generated based on the inter-dependencies of your projects. The upgrade won't succeed if you modify the plan in such a way that the migration path can't complete. For example, if **Project A** depends on **Project B** and you remove **Project B** from the upgrade plan, upgrading **Project A** might fail. + +The following snippet demonstrates the structure of a plan: + +```md +# .NET 9.0 Upgrade Plan + +## Execution Steps + +1. Validate that an .NET 9.0 SDK required for this upgrade is installed on the machine and if not, help to get it installed. +2. Ensure that the SDK version specified in global.json files is compatible with the .NET 9.0 upgrade. +3. Upgrade projects to .NET 9.0. + - 3.1. Upgrade RazorMovie.csproj + - 3.2. Upgrade RazorMovie.Tests.csproj +4. Run unit tests to validate upgrade in the projects listed below: + - RazorMovie.Tests.csproj + +## Settings + +This section contains settings and data used by execution steps. + +### Aggregate NuGet packages modifications across all projects + +NuGet packages used across all selected projects or their dependencies that need version update in projects that reference them. + +| Package Name | Current Version | New Version | Description | +|:-------------------------------------------------|:-------------------:|:-----------:|:-------------------------| +| HtmlSanitizer | 7.1.542 | 9.0.884 | Security vulnerability | +| Microsoft.Data.SqlClient | 4.0.5 | 6.0.2 | Deprecated | +| Microsoft.EntityFrameworkCore.Design | 6.0.0-rtm.21467.1 | 9.0.5 | Recommended for .NET 9.0 | +| Microsoft.EntityFrameworkCore.SqlServer | 6.0.0-rc.1.21452.10 | 9.0.5 | Recommended for .NET 9.0 | +| Microsoft.EntityFrameworkCore.Tools | 6.0.0-rc.1.21452.10 | 9.0.5 | Recommended for .NET 9.0 | +| Microsoft.VisualStudio.Web.CodeGeneration.Design | 6.0.0-rc.1.21464.1 | 9.0.0 | Recommended for .NET 9.0 | + +... +``` + +## Perform the upgrade + +Once an upgrade plan is ready, tell Copilot to start the upgrade. Once the upgrade process starts, Copilot lets you know what it's doing in the chat window and it opens the **Upgrade Progress Details** document, which lists the status of every step. If it runs into a problem, Copilot pauses and asks for your direction or help in fixing these problems. + +Each major step in the upgrade process is committed to the local Git repository. + +## Review upgrade results + +When the upgrade completes, a report is generated that describes every step of the upgrade. The tool creates a Git commit for every portion of the upgrade process, so you can easily roll back the changes or get detailed information about what changed. The report contains the Git commit hashes and provides a _Next steps_ section that describes the steps you should take after the upgrade finishes. + +The following example shows the report of a completed upgrade that contained a test failure: + +```md +# .NET 9 Upgrade Report + +## Project modifications + +| Project name | Old Target Framework | New Target Framework | Commits | +|:-----------------------------------------------|:-----------------------:|:----------------------------:|---------------------------| +| RazorMovie | net6.0 | net9.0 | af8cf633, aa61a18d | +| MvcMovie | net6.0 | net9.0 | cc8c9015 | +| WpfMovie | net6.0-windows | net9.0-windows | 9c4b13f9 | +| RazorMovie.Tests | net6.0 | net9.0 | b8d85e97 | +| MvcMovie.Tests | net6.0 | net9.0 | b8d85e97 | +| WpfMovie.Tests | net6.0-windows | net9.0-windows7.0 | b8d85e97 | + +## NuGet Packages + +| Package Name | Old Version | New Version | Commit Id | +|:-------------------------------------------------|:-------------------:|:-----------:|-----------| +| HtmlSanitizer | 7.1.542 | 9.0.884 | af8cf633 | +| Microsoft.Data.SqlClient | 4.0.5 | 6.0.2 | bf8deeac | +| Microsoft.EntityFrameworkCore.Design | 6.0.0-rtm.21467.1 | 9.0.5 | bf8deeac | +| Microsoft.EntityFrameworkCore.SqlServer | 6.0.0-rc.1.21452.10 | 9.0.5 | bf8deeac | +| Microsoft.EntityFrameworkCore.Tools | 6.0.0-rc.1.21452.10 | 9.0.5 | bf8deeac | +| Microsoft.VisualStudio.Web.CodeGeneration.Design | 6.0.0-rc.1.21464.1 | 9.0.0 | bf8deeac | + +## All commits + +| Commit ID | Description | +|:----------|:--------------------------------------------------------| +| af8cf633 | Update HtmlSanitizer package in RazorMovie.csproj | +| aa61a18d | Upgrade target framework in RazorMovie.csproj | +| cc8c9015 | Upgrade to .NET 9 and update dependencies | +| bf8deeac | Update package references in MvcMovie.csproj | +| 9c4b13f9 | Update WpfMovie.csproj to target .NET 9.0 | +| b8d85e97 | Update test projects to .NET 9 and enhance dependencies | + +## Test Results + +| Project Name | Passed | Failed | Skipped | +|:-----------------------|:------:|:------:|:-------:| +| RazorMovie.Tests | 0 | 0 | 0 | +| MvcMovie.Tests | 2 | 0 | 0 | +| WpfMovie.Tests | 6 | 1 | 0 | + +## Next steps + +- Review the test results and address the single failing test in `WpfMovie.Tests`. +- Ensure all updated NuGet packages are compatible with your application. +- Leverage new features and improvements in .NET 9.0 for your projects. +``` + +## Next steps + +After completing the upgrade process: + +- Review the generated upgrade report and any test results. +- Address any failing tests or compilation errors that might remain. +- Ensure all updated NuGet packages are compatible with your application. +- Test your application thoroughly to verify the upgrade was successful. +- Apply new features and improvements available in the upgraded .NET version. + +## Related content + +- [GitHub Copilot app modernization FAQ](github-copilot-app-modernization-faq.yml) diff --git a/docs/core/porting/includes/github-copilot-suggestion.md b/docs/core/porting/includes/github-copilot-suggestion.md new file mode 100644 index 0000000000000..84484c3bbec7c --- /dev/null +++ b/docs/core/porting/includes/github-copilot-suggestion.md @@ -0,0 +1,2 @@ +> [!IMPORTANT] +> Try the [GitHub Copilot app modernization chat agent](../github-copilot-app-modernization-overview.md). This agent analyzes your projects and dependencies, produces a step-by-step migration plan with targeted recommendations and automated code fixes, and commits each change so you can validate or roll back. It automates common porting tasks—updating project files, replacing deprecated APIs, and resolving build issues—so you can modernize faster with less manual effort. For more information, see [What is GitHub Copilot app modernization](../github-copilot-app-modernization-overview.md). diff --git a/docs/core/porting/index.md b/docs/core/porting/index.md index a47db7fd68ce7..fb7e37918b3e8 100644 --- a/docs/core/porting/index.md +++ b/docs/core/porting/index.md @@ -1,223 +1,45 @@ --- -title: Port from .NET Framework to .NET -description: Understand the porting process and discover tools you might find helpful when porting a .NET Framework project to .NET. +title: Upgrade .NET apps overview +description: Understand the aspects of upgrading from .NET Framework to .NET, upgrading to the latest .NET, and modernizing your app to the cloud. author: adegeo -ms.date: 06/03/2025 -ms.custom: devdivchpfy22, updateeachrelease -no-loc: ["package.config", PackageReference] +ms.date: 09/12/2025 +ai-usage: ai-assisted --- -# Overview of porting from .NET Framework to .NET -This article provides an overview of what you should consider when porting your code from .NET Framework to .NET (formerly named .NET Core). Porting to .NET from .NET Framework is relatively straightforward for many projects. The complexity of your projects dictates how much work you'll need to do after the initial migration of the project files. +# Overview of upgrading .NET apps -Projects where the app model is available in .NET, such as libraries, console apps, and desktop apps, usually require little change. Projects that require a new app model, such as moving to [ASP.NET Core from ASP.NET](/aspnet/core/migration/proper-to-2x/), require more work. Many patterns from the old app model have equivalents that can be used during the conversion. +This article explains how to plan and perform upgrades of .NET applications. It helps you assess your current app, choose the right upgrade path, use the available tooling, and validate the upgraded app. Follow the guidance to upgrade from .NET Framework to modern .NET, move to the latest .NET release, or modernize your app for cloud and containers. -## Windows desktop technologies +## When to upgrade -Many applications created for .NET Framework use a desktop technology such as Windows Forms or Windows Presentation Foundation (WPF). Both Windows Forms and WPF are available in .NET, but they remain Windows-only technologies. +Consider upgrading when business or technical signals show clear value: -Consider the following dependencies before you migrate a Windows Forms or WPF application: +- .NET or other dependencies reach end of support. +- New security vulnerabilities are discovered or you must meet new compliance requirements. +- Or you face performance or scalability limits that newer .NET versions address. -- Project files for .NET use a different format than .NET Framework. -- Your project might use an API that isn't available in .NET. -- Third-party controls and libraries might not have been ported to .NET and remain only available to .NET Framework. -- Your project uses a [technology that is no longer available](net-framework-tech-unavailable.md) in .NET. +Upgrading is a good opportunity to modernize your app. For example, you could containerize your app, modernize a component to a cloud-native service, or apply cloud patterns that improve reliability and operability. -.NET uses the open-source versions of Windows Forms and WPF and includes enhancements over .NET Framework. +It also increases developer productivity by enabling newer SDKs, templates, and language features that simplify development and reduce maintenance. Prioritize upgrades by risk and return: run a targeted assessment, pilot the changes on a low-risk project, and use the results to plan broader migrations. -For tutorials on migrating your desktop application to .NET, see one of the following articles: +## Upgrade your environment -- [How to upgrade a WPF desktop app to .NET](/dotnet/desktop/wpf/migration/) -- [Migrate .NET Framework Windows Forms apps to .NET](/dotnet/desktop/winforms/migration/) +.NET releases a new major version yearly, alternating STS (standard-term support) and LTS (long-term support) versions. The .NET SDK supports targeting older versions of .NET, which you might need continue to support if you deploy to a cloud service that doesn't yet support the latest .NET runtime. -## Windows-specific APIs +It's important to keep your developer tools up-to-date as each new release addresses security vulnerabilities and provides compatibility with new technologies. -Applications can still P/Invoke native libraries on platforms supported by .NET. This technology isn't limited to Windows. However, if the library you're referencing is Windows-specific, such as a _user32.dll_ or _kernel32.dll_, then the code only works on Windows. For each platform you want your app to run on, you have to either find platform-specific versions, or make your code generic enough to run on all platforms. +## Use GitHub Copilot app modernization agent -When you're porting an application from .NET Framework to .NET, your application probably used a library provided by .NET Framework. Many APIs that were available in .NET Framework weren't ported to .NET because they relied on Windows-specific technology, such as the Windows Registry or the GDI+ drawing model. - -The **Windows Compatibility Pack** provides a large portion of the .NET Framework API surface to .NET and is provided via the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility). - -For more information, see [Use the Windows Compatibility Pack to port code to .NET](windows-compat-pack.md). - -## .NET Framework compatibility mode - -The .NET Framework compatibility mode was introduced in .NET Standard 2.0. The compatibility mode allows .NET Standard and .NET projects to reference .NET Framework libraries as if they were compiled for the project's target framework. However, some .NET implementations might support a larger chunk of .NET Framework than others. For example, .NET Core 3.0 extends the .NET Framework compatibility mode to Windows Forms and WPF. Referencing .NET Framework libraries doesn't work for all projects, such as if the library uses WPF APIs, but it does unblock many porting scenarios. For more information, see the [Analyze your dependencies to port code from .NET Framework to .NET](third-party-deps.md#net-framework-compatibility-mode). - -Referencing .NET Framework libraries doesn't work in all cases, as it depends on which .NET Framework APIs were used and whether or not these APIs are supported by the project's target framework. Also, some of the .NET Framework APIs will only work on Windows. The .NET Framework compatibility mode unblocks many porting scenarios but you should test your projects to ensure that they also work at runtime. For more information, see the [Analyze your dependencies to port code from .NET Framework to](third-party-deps.md#net-framework-compatibility-mode). - -## Target framework changes in SDK-style projects - -As previously mentioned, the project files for .NET use a different format than .NET Framework, known as the SDK-style project format. Even if you're not moving from .NET Framework to .NET, you should still upgrade the project file to the latest format. The way to specify a target framework is different in SDK-style projects. In .NET Framework, the `` property is used with a moniker that specifies the version of .NET Framework. For example, .NET Framework 4.7.2 looks like the following snippet: - -```xml - - v4.7.2 - -``` - -An SDK-style project uses a different property to identify the target framework, the `` property. When targeting .NET Framework, the moniker starts with `net` and ends with the version of .NET Framework without any periods. For example, the moniker to target .NET Framework 4.7.2 is `net472`: - -```xml - - net472 - -``` - -For a list of all target monikers, see [Target frameworks in SDK-style projects](../../standard/frameworks.md#supported-target-frameworks). - -## Unavailable technologies - -There are a few technologies in .NET Framework that don't exist in .NET: - -- [Application domains](net-framework-tech-unavailable.md#application-domains) - - Creating additional application domains isn't supported. For code isolation, use separate processes or containers as an alternative. - -- [Remoting](net-framework-tech-unavailable.md#remoting) - - Remoting is used for communicating across application domains, which are no longer supported. For simple communication across processes, consider inter-process communication (IPC) mechanisms as an alternative to remoting, such as the class or the class. For more complex scenarios, consider frameworks such as [StreamJsonRpc](https://github.com/microsoft/vs-streamjsonrpc) or [ASP.NET Core](/aspnet/core) (either using [gRPC](/aspnet/core/grpc) or [RESTful Web API services](/aspnet/core/web-api)). - - Because remoting isn't supported, calls to `BeginInvoke()` and `EndInvoke()` on delegate objects will throw `PlatformNotSupportedException`. - -- [Code access security (CAS)](net-framework-tech-unavailable.md#code-access-security-cas) - - CAS was a sandboxing technique supported by .NET Framework but deprecated in .NET Framework 4.0. It was replaced by Security Transparency and it isn't supported in .NET. Instead, use security boundaries provided by the operating system, such as virtualization, containers, or user accounts. - -- [Security transparency](net-framework-tech-unavailable.md#security-transparency) - - Similar to CAS, the security transparency sandboxing technique is no longer recommended for .NET Framework applications and it isn't supported in .NET. Instead, use security boundaries provided by the operating system, such as virtualization, containers, or user accounts. - -- - - (COM+) isn't supported in .NET. - -- Windows Workflow Foundation (WF) - - WF isn't supported in .NET. For an alternative, see [CoreWF](https://github.com/UiPath/corewf). - -For more information about these unsupported technologies, see [.NET Framework technologies unavailable on .NET 6+](net-framework-tech-unavailable.md). - -## Cross-platform - -.NET (formerly known as .NET Core) is designed to be cross-platform. If your code doesn't depend on Windows-specific technologies, it can run on other platforms such as macOS, Linux, and Android. Such code includes project types like: - -- Libraries -- Console-based tools -- Automation -- ASP.NET sites - -.NET Framework is a Windows-only component. When your code uses Windows-specific technologies or APIs, such as Windows Forms and WPF, the code can still run on .NET but it doesn't run on other operating systems. - -It's possible that your library or console-based application can be used cross-platform without changing much. When you're porting to .NET, you might want to take this into consideration and test your application on other platforms. - -## The future of .NET Standard - -.NET Standard is a formal specification of .NET APIs that are available on multiple .NET implementations. The motivation behind .NET Standard was to establish greater uniformity in the .NET ecosystem. Starting with .NET 5, a different approach to establishing uniformity has been adopted, and this new approach eliminates the need for .NET Standard in many scenarios. For more information, see [.NET 5+ and .NET Standard](../../standard/net-standard.md#net-5-and-net-standard). - -.NET Standard 2.0 was the last version to support .NET Framework. - -## Tools to assist porting - -Instead of manually porting an application from .NET Framework to .NET, you can use different tools to help automate some aspects of the migration. Porting a complex project is, in itself, a complex process. The tools might help in that journey. - -Even if you use a tool to help port your application, you should review the [Considerations when porting section](#considerations-when-porting) in this article. - -### GitHub Copilot App Modernization – Upgrade for .NET - -[GitHub Copilot App Modernization – Upgrade for .NET](github-copilot-app-modernization-overview.md) is a Visual Studio extension that helps you upgrade projects to newer versions of .NET, update dependencies, and apply code fixes. It leverages GitHub Copilot to provide an interactive upgrade experience. - -This tool supports the following upgrade paths: - -- Upgrade projects from .NET Core to .NET. -- Upgrade projects from older versions of .NET to the latest. -- Modernize your code base. - -**When to use:** - -Use GitHub Copilot App Modernization – Upgrade for .NET for scenarios where you want to upgrade your .NET project code and dependencies to newer versions of .NET using an AI-powered tool. - -### GitHub Copilot app modernization for .NET - -GitHub Copilot app modernization for .NET (Preview) helps you migrate .NET applications to Azure efficiently and confidently. Powered by GitHub Copilot and [Application and code assessment for .NET](../../azure/migration/appcat/app-code-assessment-toolkit.md), it guides you through assessment, solution recommendations, code fixes, and validation—all within a single tool. - -With this assistant, you can: +The GitHub Copilot app modernization agent provides an AI-assisted, end-to-end experience to speed porting and modernization work. The agent analyzes your project and writes a plan to complete your desired upgrade. You can adjust and iterate on the plan, then perform the upgrades. With this assistant, you can: +- Upgrade projects to a newer .NET version. - Assess your application's code, configuration, and dependencies. -- Plan and set up the right Azure resources. -- Fix issues and apply best practices for cloud migration. -- Validate that your app builds and tests successfully. - -For more details, see the [GitHub Copilot app modernization for .NET overview](upgrade-assistant-overview.md). - -**When to use:** - -Use the GitHub Copilot app modernization for .NET (Preview) experience for scenarios where you need end to end assessment, planning, and remediation for migrating your .NET apps to Azure. - -### Application and Code Assessment for .NET - -[Azure Migrate application and code assessment for .NET](../../azure/migration/appcat/app-code-assessment-toolkit.md) provides code and application analysis, along with recommendations for planning cloud deployments. It helps you confidently run business-critical solutions in the cloud by offering a developer-focused assessment of your source code. The tool also provides recommendations and examples to optimize code and configurations for Azure, following industry best practices. - -This tool is also used by the GitHub Copilot app modernization for .NET experience. - -**When to use:** - -Use the Azure Migrate application and code assessment for .NET toolset for an assessment of and recommendations for migrating an existing code base to Azure. The Azure Migrate application and code assessment is essentially a subset of the GitHub Copilot app modernization for .NET experience. - -### .NET Upgrade Assistant - -The [.NET Upgrade Assistant](upgrade-assistant-overview.md) is a command-line tool that can be run on different kinds of .NET Framework apps. It's designed to assist with upgrading .NET Framework apps to .NET. After running the tool, **in most cases the app will require more effort to complete the migration**. The tool includes the installation of analyzers that can assist with completing the migration. This tool works on the following types of .NET Framework applications: - -- Windows Forms -- WPF -- ASP.NET MVC -- Console -- Class libraries - -This tool uses the other tools listed in this article, such as **try-convert**, and guides the migration process. For more information about the tool, see [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md). - -**When to use:** - -Use .NET Upgrade Assistant to upgrade .NET Framework apps to newer versions of .NET. This tool provides an alternative to the AI powered GitHub Copilot App Modernization – Upgrade for .NET experience. - -### `try-convert` - -The `try-convert` tool is a .NET global tool that can convert a project or entire solution to the .NET SDK, including moving desktop apps to .NET. However, this tool isn't recommended if your project has a complicated build process such as custom tasks, targets, or imports. - -For more information, see the [`try-convert` GitHub repository](https://github.com/dotnet/try-convert). - -### Platform compatibility analyzer - -The [Platform compatibility analyzer](../../standard/analyzers/platform-compat-analyzer.md) analyzes whether or not you're using an API that throws a at run time. Although finding one of these APIs is unlikely if you're moving from .NET Framework 4.7.2 or higher, it's good to check. For more information about APIs that throw exceptions on .NET, see [APIs that always throw exceptions on .NET Core](../compatibility/unsupported-apis.md). - -For more information, see [Platform compatibility analyzer](../../standard/analyzers/platform-compat-analyzer.md). - -## Considerations when porting - -When porting your application to .NET, consider the following suggestions in order: - -✔️ CONSIDER using the [.NET Upgrade Assistant](upgrade-assistant-overview.md) to migrate your projects. Even though this tool is in preview, it automates most of the manual steps detailed in this article and gives you a great starting point for continuing your migration path. - -✔️ CONSIDER examining your dependencies first. Your dependencies must target .NET, .NET Standard, or .NET Core. - -✔️ DO migrate from a NuGet _packages.config_ file to [PackageReference](/nuget/consume-packages/package-references-in-project-files) settings in the project file. Use Visual Studio to [convert the _package.config_ file](/nuget/consume-packages/migrate-packages-config-to-package-reference#migration-steps). - -✔️ CONSIDER upgrading to the latest project file format even if you can't yet port your app. .NET Framework projects use an outdated project format. Even though the latest project format, known as SDK-style projects, was created for .NET Core and beyond, the format also works with .NET Framework. Having your project file in the latest format gives you a good basis for porting your app in the future. - -✔️ DO retarget your .NET Framework project to at least .NET Framework 4.7.2. This ensures the availability of the latest API alternatives for cases where .NET Standard doesn't support existing APIs. - -✔️ CONSIDER targeting .NET 8, which is a long-term support (LTS) release. - -✔️ DO target .NET 6+ for **Windows Forms and WPF** projects. .NET 6 and later versions contain many improvements for Desktop apps. - -✔️ CONSIDER targeting .NET Standard 2.0 if you're migrating a library that might also be used with .NET Framework projects. You can also multitarget your library, targeting both .NET Framework and .NET Standard. - -✔️ DO add reference to the [Microsoft.Windows.Compatibility NuGet package](https://www.nuget.org/packages/Microsoft.Windows.Compatibility) if, after migrating, you get errors of missing APIs. A large portion of the .NET Framework API surface is available to .NET via the NuGet package. +- Migrate projects from older .NET versions to the latest release. +- Migrate technologies your app depends on to Azure. +- Plan and provision the right Azure resources. +- Fix issues and apply cloud-migration best practices. +- Validate that your app builds and that tests pass. -## See also +Use the GitHub Copilot app modernization agent when you want a guided, AI-powered path to assess, remediate, and modernize codebases—particularly for projects that have many dependencies, rely on Windows-specific APIs, or when you plan to containerize or migrate services to the cloud. -- [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md) -- [ASP.NET to ASP.NET Core migration](/aspnet/core/migration/proper-to-2x) -- [How to upgrade a WPF desktop app to .NET](/dotnet/desktop/wpf/migration/) -- [Migrate .NET Framework Windows Forms apps to .NET](/dotnet/desktop/winforms/migration/) -- [.NET 5 vs. .NET Framework for server apps](../../standard/choosing-core-framework-server.md) +For more information, see [What is GitHub Copilot app modernization](github-copilot-app-modernization-overview.md). diff --git a/docs/core/porting/modernize.md b/docs/core/porting/modernize.md index 7b681e161a2a2..f40a1cde968cd 100644 --- a/docs/core/porting/modernize.md +++ b/docs/core/porting/modernize.md @@ -10,10 +10,7 @@ ms.custom: sfi-ropc-nochange # Modernize after upgrading to .NET from .NET Framework -In this article, you'll learn about different ways you can modernize your app after it's been upgraded from .NET Framework to .NET. Use the [.NET Upgrade Assistant](upgrade-assistant-overview.md) tool to upgrade your app to .NET. - -> [!TIP] -> You can use GitHub Copilot to modernize your application after migrating from .NET Framework. For more information, see [What is GitHub Copilot app modernization - upgrade for .NET?](github-copilot-app-modernization-overview.md). +In this article, you'll learn about different ways you can modernize your app after it's been upgraded from .NET Framework to .NET. Use the [GitHub Copilot app modernization](github-copilot-app-modernization-overview.md) assistant to upgrade your app to .NET. ## Missing APIs @@ -29,7 +26,7 @@ Projects that target a Windows desktop technology, such as Windows Presentation ## App.config -.NET Framework uses the _App.config_ file to load settings for your app, such as connection strings and log provider configuration. Modern .NET uses the _appsettings.json_ file for app settings. The CLI version of the Upgrade Assistant handles converting _App.config_ files to _appsettings.json_, but the Visual Studio extension doesn't. +.NET Framework uses the _App.config_ file to load settings for your app, such as connection strings and log provider configuration. Modern .NET uses the _appsettings.json_ file for app settings. > [!TIP] > If you don't want to use the _appsettings.json_ file, you can add the `System.Configuration.ConfigurationManager` NuGet package to your app and your code will compile and use the _App.config_ file. diff --git a/docs/core/porting/porting-approaches.md b/docs/core/porting/porting-approaches.md index 7678bf8de25ea..b3d444953161f 100644 --- a/docs/core/porting/porting-approaches.md +++ b/docs/core/porting/porting-approaches.md @@ -3,20 +3,20 @@ title: Porting approaches description: Create a porting plan that best reflects your project and context. author: StephenBonikowsky ms.author: stebon -ms.date: 06/10/2021 +ms.date: 09/15/2025 --- # Create a porting plan -We recommend using the Visual Studio [.NET Upgrade Assistant](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.upgradeassistant) to update .NET Framework code to the latest .NET versions. For more information see the blog [Upgrading your .NET projects with Visual Studio](https://devblogs.microsoft.com/dotnet/upgrade-assistant-now-in-visual-studio/). - -[!INCLUDE[](~/includes/deprecating-api-port.md)] - Before you jump straight into the code, take the time to go through the recommended pre-migration steps. This article gives you insight into the kinds of issues you may come across, and helps you decide on an approach that makes the most sense. +[!INCLUDE[](../../../includes/deprecating-api-port.md)] + ## Port your code Make sure that you follow the [prerequisites to porting code](premigration-needed-changes.md) before you continue any further. Be ready to decide on the best approach for you and begin porting code. +[!INCLUDE [github-copilot-suggestion](includes/github-copilot-suggestion.md)] + ### Deal primarily with the compiler This approach works well for small projects or projects that don't use many .NET Framework APIs. The approach is simple: @@ -98,5 +98,5 @@ If you start with the base of your library and move outward from the base and te ## Next steps -- [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md) +- [What is GitHub Copilot app modernization](github-copilot-app-modernization-overview.md) - [Organize your project to support both .NET Framework and .NET Core](project-structure.md) diff --git a/docs/core/porting/premigration-needed-changes.md b/docs/core/porting/premigration-needed-changes.md index bb86455440a66..46c5ca1ea337a 100644 --- a/docs/core/porting/premigration-needed-changes.md +++ b/docs/core/porting/premigration-needed-changes.md @@ -9,6 +9,8 @@ ms.date: 06/10/2021 Make the needed changes to build and run a .NET application before beginning the work to port your code. These changes can be done while still building and running a .NET Framework application. +[!INCLUDE [github-copilot-suggestion](includes/github-copilot-suggestion.md)] + ## Upgrade to required tooling Upgrade to a version of MSBuild/Visual Studio that supports the version of .NET you will be targeting. See [Versioning relationship between the .NET SDK, MSBuild and VS](versioning-sdk-msbuild-vs.md) for more info. diff --git a/docs/core/porting/third-party-deps.md b/docs/core/porting/third-party-deps.md index d3ed619fa8614..56f04fa14422c 100644 --- a/docs/core/porting/third-party-deps.md +++ b/docs/core/porting/third-party-deps.md @@ -95,7 +95,7 @@ The .NET Team would like to know which libraries are the most important to suppo ## Analyze non-NuGet dependencies -You might have a dependency that isn't a NuGet package, such as a DLL in the file system. You can determine the portability of that dependency with the [.NET Upgrade Assistant](upgrade-assistant-overview.md) tool. +You might have a dependency that isn't a NuGet package, such as a DLL in the file system. You can determine the portability of that dependency with the [GitHub Copilot app modernization agent](github-copilot-app-modernization-overview.md). ## Next steps diff --git a/docs/core/porting/unsupported-apis.md b/docs/core/porting/unsupported-apis.md index 86e55f6704209..68fa8a9387939 100644 --- a/docs/core/porting/unsupported-apis.md +++ b/docs/core/porting/unsupported-apis.md @@ -9,22 +9,14 @@ ms.date: 06/10/2021 APIs in your .NET Framework code may not be supported in .NET for many reasons. These reasons range from the simple to fix, such as a namespace change, to the more challenging to fix, such as an entire technology not being supported. The first step is to determine which of your APIs are no longer supported and then identify the proper fix. +[!INCLUDE [github-copilot-suggestion](includes/github-copilot-suggestion.md)] + ## .NET Portability Analyzer +[!INCLUDE [deprecating-api-port](../../../includes/deprecating-api-port.md)] + The .NET Portability Analyzer is a tool that analyzes assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms. To use the .NET Portability Analyzer in Visual Studio, install the [extension from the marketplace](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer). For more information, see [The .NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md). - -## Upgrade assistant - -The [.NET Upgrade Assistant](upgrade-assistant-overview.md) is a command-line tool that can be run on different kinds of .NET Framework apps. It's designed to assist with upgrading .NET Framework apps to .NET 5. After running the tool, in most cases, the app will **require more effort to complete the migration**. The tool includes the installation of analyzers that can assist with completing the migration. This tool works on the following types of .NET Framework applications: - -- Windows Forms -- WPF -- ASP.NET MVC -- Console -- Class libraries - -This tool uses the **.NET Portability Analyzer** among other tools, and guides the migration process. For more information about the tool, see [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md). diff --git a/docs/core/porting/upgrade-assistant-analyze-overview.md b/docs/core/porting/upgrade-assistant-analyze-overview.md index 5f2f863489dc2..975c1a0905389 100644 --- a/docs/core/porting/upgrade-assistant-analyze-overview.md +++ b/docs/core/porting/upgrade-assistant-analyze-overview.md @@ -14,6 +14,8 @@ ms.date: 10/08/2024 This article provides an overview of the code analysis function of .NET Upgrade Assistant. Code analysis generates a report based on your project configuration, dependencies, and code. The report contains information about potential issues and problems you might encounter during the upgrade, and what steps you could take to remediate those problems. +[!INCLUDE [github-copilot-suggestion](includes/github-copilot-suggestion.md)] + ## Types of analysis There are two types of analysis you can perform on your code: diff --git a/docs/core/porting/upgrade-assistant-install.md b/docs/core/porting/upgrade-assistant-install.md index 1d1085c5b8e36..08106083a28b1 100644 --- a/docs/core/porting/upgrade-assistant-install.md +++ b/docs/core/porting/upgrade-assistant-install.md @@ -14,6 +14,8 @@ ms.date: 10/08/2024 This article teaches you how to install .NET Upgrade Assistant using either the Visual Studio extension or the command-line interface (CLI) tool. +[!INCLUDE [github-copilot-suggestion](includes/github-copilot-suggestion.md)] + ## Prerequisites - Windows Operating System diff --git a/docs/core/porting/upgrade-assistant-overview.md b/docs/core/porting/upgrade-assistant-overview.md index eb3206ec6fc21..5260ab914191b 100644 --- a/docs/core/porting/upgrade-assistant-overview.md +++ b/docs/core/porting/upgrade-assistant-overview.md @@ -12,10 +12,12 @@ ms.date: 10/08/2024 # What is .NET Upgrade Assistant? -.NET Upgrade Assistant helps upgrade projects to newer versions of .NET and analyzes your code to spot and fix potential incompatibilities. One focus of the tool is to help migrate a project from .NET Framework, .NET Core, or .NET, to the latest version of .NET. You use the extension or tool to upgrade entire .NET projects, or some aspect of the project, such migrating a configuration file from an older type to a newer type. +.NET Upgrade Assistant helps upgrade projects to newer versions of .NET and analyzes your code to spot and fix potential incompatibilities. One focus of the tool is to help upgrading a project from .NET Framework, .NET Core, or .NET, to the latest version of .NET. You use the extension or tool to upgrade entire .NET projects, or some aspect of the project, such upgrading a configuration file from an older type to a newer type. .NET Upgrade Assistant is distributed as a Visual Studio extension or a command-line interface (CLI) tool. +[!INCLUDE [github-copilot-suggestion](includes/github-copilot-suggestion.md)] + ## Analyze and upgrade .NET Upgrade Assistant includes an analysis engine that scans your projects and their dependencies. After the scan is complete, a report is generated with detailed information about performing an upgrade. You can use this information to upgrade either the entire project or specific parts of the project. diff --git a/docs/core/whats-new/dotnet-7.md b/docs/core/whats-new/dotnet-7.md index 91bd02b3b38ab..1a4f9d7e9c644 100644 --- a/docs/core/whats-new/dotnet-7.md +++ b/docs/core/whats-new/dotnet-7.md @@ -167,10 +167,6 @@ WPF in .NET 7 includes numerous bug fixes as well as performance and accessibili Orleans is a cross-platform framework for building robust, scalable distributed applications. For information about the latest updates for Orleans, see [Migrate from Orleans 3.x to 7.0](../../orleans/migration-guide.md). -### .NET Upgrade Assistant and CoreWCF - -The .NET Upgrade Assistant now supports upgrading server-side WCF apps to [CoreWCF](https://github.com/CoreWCF/CoreWCF), which is a community-created port of WCF to .NET (Core). For more information, see [Upgrade a WCF server-side project to use CoreWCF](../porting/upgrade-assistant-wcf.md). - ### ML.NET ML.NET now includes a text classification API that makes it easy to train custom text classification models using the latest state-of-the-art deep learning techniques. For more information, see the [What's new with AutoML and tooling](https://devblogs.microsoft.com/dotnet/whats-new-with-mldotnet-automl/) and [Introducing the ML.NET Text Classification API](https://devblogs.microsoft.com/dotnet/introducing-the-ml-dotnet-text-classification-api-preview/) blog posts. diff --git a/docs/navigate/github-copilot-modernize/index.yml b/docs/navigate/github-copilot-modernize/index.yml new file mode 100644 index 0000000000000..16425d73be024 --- /dev/null +++ b/docs/navigate/github-copilot-modernize/index.yml @@ -0,0 +1,51 @@ +### YamlMime:Landing + +title: Use GitHub Copilot to upgrade and migrate .NET apps +summary: Learn about updating and migrating .NET apps with GitHub Copilot. + +metadata: + title: Use GitHub Copilot to upgrade and migrate .NET apps + description: Learn about updating and migrating .NET apps with GitHub Copilot. + ms.topic: landing-page + ms.date: 09/15/2025 + +landingContent: + + - title: Upgrade .NET apps + linkLists: + - linkListType: overview + links: + - text: Upgrade .NET apps + url: ../../core/porting/github-copilot-app-modernization-overview.md + - text: FAQ + url: ../../core/porting/github-copilot-app-modernization-faq.yml + - linkListType: how-to-guide + links: + - text: How to upgrade a .NET app + url: ../../core/porting/how-to-upgrade-with-github-copilot.md + + - title: Migrate .NET apps to Azure + linkLists: + - linkListType: overview + links: + - text: Migrate .NET apps to Azure (app modernization) + url: ../../azure/migration/appmod/overview.md?toc=/dotnet/navigate/github-copilot-modernize/toc.json&bc=/dotnet/breadcrumb/toc.json + - text: Azure migration quickstart + url: ../../azure/migration/appmod/quickstart.md?toc=/dotnet/navigate/github-copilot-modernize/toc.json&bc=/dotnet/breadcrumb/toc.json + - linkListType: sample + links: + - text: Migration sample + url: ../../azure/migration/appmod/sample.md?toc=/dotnet/navigate/github-copilot-modernize/toc.json&bc=/dotnet/breadcrumb/toc.json + - linkListType: concept + links: + - text: Azure migration FAQ + url: ../../azure/migration/appmod/faq.md?toc=/dotnet/navigate/github-copilot-modernize/toc.json&bc=/dotnet/breadcrumb/toc.json + + - title: Get help and community + linkLists: + - linkListType: overview + links: + - text: .NET on Q&A + url: /answers/products/dotnet + - text: .NET tech community forums + url: https://techcommunity.microsoft.com/category/dotnet diff --git a/docs/navigate/github-copilot-modernize/toc.yml b/docs/navigate/github-copilot-modernize/toc.yml new file mode 100644 index 0000000000000..f319a66dfcc53 --- /dev/null +++ b/docs/navigate/github-copilot-modernize/toc.yml @@ -0,0 +1,24 @@ +items: + - name: GitHub Copilot app modernization for .NET + href: index.yml + - name: Overview + href: ../../core/porting/github-copilot-app-modernization-overview.md + - name: FAQ + href: ../../core/porting/github-copilot-app-modernization-faq.yml + displayName: copilot, upgrade + + - name: Upgrade .NET apps + expanded: true + items: + - name: How to upgrade with GitHub Copilot + href: ../../core/porting/how-to-upgrade-with-github-copilot.md + + - name: Migrate .NET apps to Azure + expanded: true + items: + - name: Migrate a .NET project + href: ../../azure/migration/appmod/quickstart.md?toc=/dotnet/navigate/github-copilot-modernize/toc.json&bc=/dotnet/breadcrumb/toc.json + - name: Migration sample + href: ../../azure/migration/appmod/sample.md?toc=/dotnet/navigate/github-copilot-modernize/toc.json&bc=/dotnet/breadcrumb/toc.json + - name: Troubleshooting + href: ../../azure/migration/appmod/faq.md?toc=/dotnet/navigate/github-copilot-modernize/toc.json&bc=/dotnet/breadcrumb/toc.json diff --git a/docs/navigate/migration-guide/index.yml b/docs/navigate/migration-guide/index.yml index ba42ce5e9cb4f..7fa63436eb2d4 100644 --- a/docs/navigate/migration-guide/index.yml +++ b/docs/navigate/migration-guide/index.yml @@ -1,26 +1,69 @@ ### YamlMime:Landing -title: .NET migration documentation -summary: Learn about migrating apps from .NET Framework to .NET. +title: Upgrade .NET apps documentation +summary: Learn about upgrading apps from .NET Framework to .NET. metadata: - title: .NET migration documentation - description: Learn about migrating apps from .NET Framework to .NET. + title: Upgrade .NET apps documentation + description: Learn about upgrading apps from .NET Framework to .NET. ms.topic: landing-page - ms.date: 01/17/2023 + ms.date: 09/15/2025 landingContent: - # Card - - title: Migrate from .NET Framework + - title: .NET upgrade guide linkLists: - linkListType: overview links: - - text: Port from .NET Framework to .NET Core + - text: Upgrade apps to the latest version of .NET url: ../../core/porting/index.md - - text: Upgrade Assistant - url: ../../core/porting/upgrade-assistant-overview.md - - linkListType: reference + - text: Use GitHub Copilot to assist in upgrading + url: ../../core/porting/github-copilot-app-modernization-overview.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - text: Plan your .NET Framework upgrade + url: ../../core/porting/framework-overview.md + - linkListType: concept links: - - text: Versioning info - url: ../../core/porting/versioning-sdk-msbuild-vs.md + - text: Breaking changes and app compatibility + url: ../../core/porting/breaking-changes.md + - text: Unsupported APIs + url: ../../core/compatibility/unsupported-apis.md + + + - title: GitHub Copilot app modernization + linkLists: + - linkListType: overview + links: + - text: GitHub Copilot app modernization overview + url: ../../core/porting/github-copilot-app-modernization-overview.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - text: GitHub Copilot app modernization FAQ + url: ../../core/porting/github-copilot-app-modernization-faq.yml?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - linkListType: concept + links: + - text: Using Copilot to speed up porting and modernization + url: ../../core/porting/github-copilot-app-modernization-overview.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json#how-does-it-work + + - title: Migrate .NET apps to Azure + linkLists: + - linkListType: overview + links: + - text: Migrate .NET apps to Azure (app modernization) + url: ../../azure/migration/appmod/overview.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - text: Azure migration quickstart + url: ../../azure/migration/appmod/quickstart.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - linkListType: sample + links: + - text: Migration sample + url: ../../azure/migration/appmod/sample.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - linkListType: concept + links: + - text: Azure migration FAQ + url: ../../core/porting/github-copilot-app-modernization-faq.yml?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + + - title: Get help and community + linkLists: + - linkListType: overview + links: + - text: .NET on Q&A + url: /answers/products/dotnet + - text: .NET tech community forums + url: https://techcommunity.microsoft.com/category/dotnet diff --git a/docs/navigate/migration-guide/toc.yml b/docs/navigate/migration-guide/toc.yml index 93f715bca9489..c1a993770d468 100644 --- a/docs/navigate/migration-guide/toc.yml +++ b/docs/navigate/migration-guide/toc.yml @@ -1,28 +1,98 @@ items: - - name: .NET migration guide + - name: .NET upgrade guide href: index.yml - name: Overview href: ../../core/porting/index.md - - name: General information + - name: Use GitHub Copilot to upgrade expanded: true items: - - name: About .NET + - name: Overview + href: ../../core/porting/github-copilot-app-modernization-overview.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + displayName: copilot, upgrade + - name: FAQ + href: ../../core/porting/github-copilot-app-modernization-faq.yml?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + displayName: copilot, upgrade + - name: Upgrade .NET apps + expanded: false items: - - name: Versioning info for .NET SDK, MSBuild, and Visual Studio - href: ../../core/porting/versioning-sdk-msbuild-vs.md - - name: Choose between .NET and .NET Framework for server apps - href: ../../standard/choosing-core-framework-server.md - - name: GitHub Copilot app modernization - items: - - name: Overview - href: ../../core/porting/github-copilot-app-modernization-overview.md + - name: How to upgrade with GitHub Copilot + href: ../../core/porting/how-to-upgrade-with-github-copilot.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json displayName: copilot, upgrade - - name: Install - href: ../../core/porting/github-copilot-app-modernization-install.md - displayName: copilot, upgrade - - name: FAQ - href: ../../core/porting/github-copilot-app-modernization-faq.yml - displayName: copilot, upgrade, faq + - name: Migrate .NET apps to Azure + expanded: false + items: + - name: Migrate a .NET project + href: ../../azure/migration/appmod/quickstart.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - name: Migration sample + href: ../../azure/migration/appmod/sample.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - name: Troubleshooting + href: ../../azure/migration/appmod/faq.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + + - name: Plan an upgrade from .NET Framework + items: + - name: Overview + href: ../../core/porting/framework-overview.md + - name: Upgrade with GitHub Copilot + href: ../../core/porting/github-copilot-app-modernization-overview.md?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + displayName: copilot, upgrade, modernization + - name: General information + items: + - name: About .NET + items: + - name: Versioning info for .NET SDK, MSBuild, and Visual Studio + href: ../../core/porting/versioning-sdk-msbuild-vs.md + - name: Choose between .NET and .NET Framework for server apps + href: ../../standard/choosing-core-framework-server.md + - name: Breaking changes + items: + - name: Overview + displayName: app compatibility + href: ../../core/porting/breaking-changes.md + - name: Breaking changes + href: ../../core/compatibility/fx-core.md + - name: Pre-upgrade + expanded: false + items: + - name: Assess the portability of your project + items: + - name: Unsupported dependencies + href: ../../core/porting/third-party-deps.md + - name: Use the Windows Compatibility Pack + href: ../../core/porting/windows-compat-pack.md + - name: Unavailable technologies + href: ../../core/porting/net-framework-tech-unavailable.md + - name: Unsupported APIs + items: + - name: Tools to find unsupported APIs + href: ../../core/porting/unsupported-apis.md + - name: Unsupported API list + href: ../../core/compatibility/unsupported-apis.md + - name: Needed changes before porting code + href: ../../core/porting/premigration-needed-changes.md + - name: Upgrade + expanded: false + items: + - name: Create a porting plan + items: + - name: Approaches + href: ../../core/porting/porting-approaches.md + - name: Project structure + href: ../../core/porting/project-structure.md + - name: Application porting guides + items: + - name: Windows Forms + href: /dotnet/desktop/winforms/migration/?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - name: Windows Presentation Foundation + href: /dotnet/desktop/wpf/migration/?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json + - name: C++/CLI projects + href: ../../core/porting/cpp-cli.md + - name: Post-upgrade + expanded: false + items: + - name: Modernize + href: ../../core/porting/modernize.md + - name: Other tools + items: - name: .NET Upgrade Assistant tool items: - name: Overview @@ -35,7 +105,6 @@ items: href: ../../core/porting/upgrade-assistant-how-to-upgrade.md displayName: upgrade assistant - name: Analyze - expanded: true items: - name: Overview href: ../../core/porting/upgrade-assistant-analyze-overview.md @@ -44,7 +113,6 @@ items: href: ../../core/porting/upgrade-assistant-how-to-analyze.md displayName: upgrade assistant - name: Project upgrade guide - expanded: true items: - name: ASP.NET href: /aspnet/core/migration/fx-to-core/tooling @@ -58,51 +126,3 @@ items: href: ../../core/porting/upgrade-assistant-wcf.md - name: Telemetry href: ../../core/porting/upgrade-assistant-telemetry.md - - name: Breaking changes - items: - - name: Overview - displayName: app compatibility - href: ../../core/porting/breaking-changes.md - - name: Breaking changes - href: ../../core/compatibility/fx-core.md - - name: Pre-migration - expanded: true - items: - - name: Assess the portability of your project - items: - - name: Unsupported dependencies - href: ../../core/porting/third-party-deps.md - - name: Use the Windows Compatibility Pack - href: ../../core/porting/windows-compat-pack.md - - name: Unavailable technologies - href: ../../core/porting/net-framework-tech-unavailable.md - - name: Unsupported APIs - items: - - name: Tools to find unsupported APIs - href: ../../core/porting/unsupported-apis.md - - name: Unsupported API list - href: ../../core/compatibility/unsupported-apis.md - - name: Needed changes before porting code - href: ../../core/porting/premigration-needed-changes.md - - name: Migration - expanded: true - items: - - name: Create a porting plan - items: - - name: Approaches - href: ../../core/porting/porting-approaches.md - - name: Project structure - href: ../../core/porting/project-structure.md - - name: Application porting guides - items: - - name: Windows Forms - href: /dotnet/desktop/winforms/migration/?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json - - name: Windows Presentation Foundation - href: /dotnet/desktop/wpf/migration/?toc=/dotnet/navigate/migration-guide/toc.json&bc=/dotnet/breadcrumb/toc.json - - name: C++/CLI projects - href: ../../core/porting/cpp-cli.md - - name: Post-migration - expanded: true - items: - - name: Modernize - href: ../../core/porting/modernize.md diff --git a/docs/standard/analyzers/portability-analyzer.md b/docs/standard/analyzers/portability-analyzer.md index 2897ee2935b2c..d4d50690354c2 100644 --- a/docs/standard/analyzers/portability-analyzer.md +++ b/docs/standard/analyzers/portability-analyzer.md @@ -6,7 +6,7 @@ ms.date: 01/19/2025 # The .NET Portability Analyzer -[!INCLUDE[](~/includes/deprecating-api-port.md)] +[!INCLUDE [deprecating-api-port](../../../includes/deprecating-api-port.md)] Want to make your libraries support multi-platform? Want to see how much work is required to make your .NET Framework application run on .NET Core? The [.NET Portability Analyzer](https://github.com/microsoft/dotnet-apiport) is a tool that analyzes assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms. The Portability Analyzer is a [console app](https://aka.ms/apiportdownload) that analyzes assemblies by specified files or directory.