|
| 1 | +--- |
| 2 | +title: How to upgrade a .NET app with GitHub Copilot app modernization |
| 3 | +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." |
| 4 | +author: adegeo |
| 5 | +ms.author: adegeo |
| 6 | +ms.topic: how-to |
| 7 | +ms.date: 09/15/2025 |
| 8 | +ai-usage: ai-generated |
| 9 | + |
| 10 | +#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. |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +# How to upgrade a .NET app with GitHub Copilot app modernization |
| 15 | + |
| 16 | +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. |
| 17 | + |
| 18 | +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. |
| 19 | + |
| 20 | +## Prerequisites |
| 21 | + |
| 22 | +Before you begin, ensure you have the following requirements: |
| 23 | + |
| 24 | +- Windows Operating System |
| 25 | +- [Visual Studio 2022 version 17.14.16 or newer](https://visualstudio.microsoft.com/downloads/) (To be released) |
| 26 | +- [.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: |
| 27 | + - GitHub Copilot |
| 28 | + - GitHub Copilot app modernization for .NET |
| 29 | +- GitHub account with Copilot access and supported subscription plan: |
| 30 | + - [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) |
| 31 | + - Supported subscription plans: Copilot Pro, Copilot Pro+, Copilot Business, or Copilot Enterprise |
| 32 | + - If you change subscriptions, you must restart Visual Studio |
| 33 | +- A .NET project written in C# that you want to upgrade |
| 34 | + |
| 35 | +## Start the upgrade process |
| 36 | + |
| 37 | +The first step to upgrading is generating a plan by interacting with GitHub Copilot. Follow these steps to initiate the upgrade: |
| 38 | + |
| 39 | +1. Open your .NET project or solution in Visual Studio. |
| 40 | +1. Access the GitHub Copilot app modernization agent using one of these methods: |
| 41 | + |
| 42 | + Right-click on the solution or project in **Solution Explorer** and select **Modernize**. |
| 43 | + |
| 44 | + —or— |
| 45 | + |
| 46 | + Open the **GitHub Copilot Chat** window and type `@modernize` followed by your upgrade request. |
| 47 | + |
| 48 | +1. Tell the `@modernize` agent what you want to upgrade. |
| 49 | + |
| 50 | +## Generate an upgrade plan |
| 51 | + |
| 52 | +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. |
| 53 | + |
| 54 | +To generate and customize your plan: |
| 55 | + |
| 56 | +1. Answer Copilot's questions about your upgrade requirements and preferences. |
| 57 | +1. Review the generated upgrade plan in the Markdown file. |
| 58 | +1. Optionally, edit the Markdown file to change the upgrade steps or add more context. |
| 59 | +1. Tell Copilot to proceed with the upgrade when you're satisfied with the plan. |
| 60 | + |
| 61 | +> [!CAUTION] |
| 62 | +> 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. |
| 63 | +
|
| 64 | +## Perform the upgrade |
| 65 | + |
| 66 | +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. |
| 67 | + |
| 68 | +Each major step in the upgrade process is committed to the local Git repository. |
| 69 | + |
| 70 | +## Review upgrade results |
| 71 | + |
| 72 | +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. |
| 73 | + |
| 74 | +## Next steps |
| 75 | + |
| 76 | +After completing the upgrade process: |
| 77 | + |
| 78 | +- Review the generated upgrade report and any test results. |
| 79 | +- Address any failing tests or compilation errors that might remain. |
| 80 | +- Ensure all updated NuGet packages are compatible with your application. |
| 81 | +- Test your application thoroughly to verify the upgrade was successful. |
| 82 | +- Apply new features and improvements available in the upgraded .NET version. |
| 83 | + |
| 84 | +## Related content |
| 85 | + |
| 86 | +- [GitHub Copilot app modernization FAQ](github-copilot-app-modernization-faq.yml) |
0 commit comments