diff --git a/docs/core/porting/github-copilot-app-modernization/how-to-custom-upgrade-instructions.md b/docs/core/porting/github-copilot-app-modernization/how-to-custom-upgrade-instructions.md index 7585854d227eb..aa7b4e4448f42 100644 --- a/docs/core/porting/github-copilot-app-modernization/how-to-custom-upgrade-instructions.md +++ b/docs/core/porting/github-copilot-app-modernization/how-to-custom-upgrade-instructions.md @@ -1,20 +1,20 @@ --- -title: How to apply custom upgrade instructions during an upgrade -description: "Learn how to apply custom upgrade instructions with GitHub Copilot app modernization so they're executed automatically during a .NET upgrade." +title: Apply custom upgrade instructions for .NET upgrades +description: "Create and apply custom upgrade instructions with GitHub Copilot to automate .NET upgrades. Learn to write, test, and integrate instructions for consistent transformations." author: kschlobohm ms.topic: how-to -ms.date: 12/08/2025 +ms.date: 12/12/2025 ai-usage: ai-assisted #customer intent: As a developer, I want to apply custom upgrade instructions during a .NET upgrade so that I can automate specific changes consistently. --- -# Apply custom upgrade instructions during a .NET upgrade +# Apply custom upgrade instructions for .NET upgrades -GitHub Copilot app modernization executes reusable, task-focused guidance stored as custom upgrade instruction files. During an upgrade, incorporate these instructions into the generated plan so Copilot applies opinionated replacements, refactorings, or policy-driven changes. For example, replacing `Newtonsoft.Json` with `System.Text.Json`. +Custom upgrade instructions are markdown files that guide GitHub Copilot app modernization to apply specific transformations during an upgrade. Create these files to automate repetitive changes, such as replacing one library with another or guiding how to apply a specific upgrade of an API. -This article shows how to create a custom upgrade instruction, test it with a fast inner loop, and apply it automatically during a full upgrade. +This article explains how to create a custom upgrade instruction file, test it in isolation, and use it during the assessment stage of an upgrade. You learn how to structure the instruction file, verify it works correctly, and integrate it into the upgrade workflow. ## Prerequisites @@ -24,10 +24,10 @@ Before you begin, ensure you have these requirements: ## Understand custom upgrade instructions -Custom upgrade instructions are markdown files that Copilot retrieves on demand while planning or executing an upgrade. They differ from `copilot-instructions.md` because they're: +GitHub Copilot app modernization retrieves custom upgrade instructions as markdown files on demand during the assessment and planning stages of an upgrade. They differ from `copilot-instructions.md` because they're: - Targeted to automating code and dependency changes. -- Retrieved only when relevant to the current user request or plan modification. +- Retrieved only when relevant to the current upgrade assessment or plan. - Reusable across solutions when copied into each repository. Structure your instruction files with: @@ -44,77 +44,92 @@ Follow these steps to generate and refine a new instruction file. These sections 1. In the **Solution Explorer** window, right-click the **solution** > **Modernize**. 1. In the chat, type: `I want to generate a custom upgrade instruction`. 1. When asked, provide a scenario like `I want to replace Newtonsoft with System.Text.Json` to have Copilot create the file. -1. (Optional) Add the file to the solution for visibility if it isn't already included. 1. When Copilot creates the new file, such as `replace_newtonsoft_with_system_text_json.md`, review the content and refine it in chat. For example, ask Copilot to "clarify detection criteria" or "add a prerequisite section." -1. (Recommended) Strengthen the instruction with a real diff example: + + > [!TIP] + > Add the file to the solution for visibility if it isn't already included. + +1. Strengthen the instruction with real diff examples. + 1. Make the desired code changes manually in one project. For example, "remove the `Newtonsoft.Json` package, update using directives, and replace `JsonConvert` code with `JsonSerializer`." 1. In chat, with the instruction file open, type: `Check my git changes and add diffs as examples to my instruction file`. 1. Confirm Copilot used a git diff and appended a fenced diff block or structured example to the markdown file. ### Authoring tips -- Use clear conditional phrasing: "If code references X, then do Y." +Follow these guidelines to write clear, effective custom upgrade instructions that Copilot can interpret reliably: + +- Use clear conditional phrasing: `If code references X, then do Y.` - Keep one transformation per file; use prerequisites when multiple files must run in sequence. -- Provide at least one concrete example (diff or before/after snippet) to improve transformation accuracy. -- Avoid ambiguous verbs like "improve" or "fix"—use explicit actions like replace, remove, update. +- Improve transformation accuracy by providing at least one concrete example, such as a diff or before/after snippet. +- Avoid ambiguous verbs like "improve" or "fix"; use explicit actions like "replace," "remove," and "update." ## Test a custom upgrade instruction (one-time run) -Before running the instruction during an upgrade plan, validate it in isolation. This fast inner loop helps you refine detection and validate the code changes. +Before running the instruction during an upgrade, validate it in isolation. This fast inner loop helps you refine detection and validate the code changes. 1. In the **Solution Explorer** window, right-click the **solution** > **Modernize**. -1. In chat, invoke the instruction using wording similar to the file name. For example, "replace Newtonsoft with System.Text.Json." -1. Confirm in the chat window that Copilot retrieved the instruction file (it shows the text "Getting more instructions"). If it didn't, retry by using the key words from the file's name such as using the same verb (replace/update/remove) and nouns (Newtonsoft/System.Text.Json). +1. In chat, invoke the instruction by using wording similar to the file name. For example, `replace Newtonsoft with System.Text.Json`. +1. Confirm in the chat window that Copilot retrieved the instruction file: + + ```text + > Getting instructions for 'replace Newtonsoft with System.Text.Json'. + + Perfect! I've retrieved the scenario instructions for migrating from Newtonsoft.Json to System.Text.Json. Now I'll begin the analysis following the scenario-specific instructions. + ``` + + If you don't see an indication that the instructions were found, retry using key words from the file's name, such as the same verb and noun combinations. + 1. Review the proposed changes (solution diffs, pending commits, or previewed modifications) to validate the custom upgrade instruction behaves as planned. ### Validation tips +If the test run doesn't produce the expected results, use these troubleshooting tips to refine your instruction file: + - If Copilot only updates package versions instead of performing a replacement, ensure the instruction explicitly says to remove or replace the old package. - Use consistent naming so natural language activation matches. For example, the file name starts with `replace_` and your chat request begins with "Replace ...". - Add missing code patterns you discover during testing as more examples to improve coverage. ## Apply custom instructions during an upgrade -Use these steps to incorporate an existing custom upgrade instruction into an upgrade plan. +Use these steps to incorporate an existing custom upgrade instruction into the assessment stage of an upgrade. 1. In the **Solution Explorer** window, right-click the **solution** > **Modernize**. -1. In the chat, choose `Upgrade to a newer version of .NET`. Answer Copilot's questions until it generates the plan markdown file. -1. Review the generated plan. Confirm whether the intended transformation is already present. If it only lists a version bump, your custom instruction isn't yet applied. -1. In chat, explicitly reference the instruction using language similar to the file name. For example, "modify the plan using the custom instructions to replace Newtonsoft with System.Text.Json." -1. Wait for Copilot to confirm it retrieved the file. In chat, you see that it opened the markdown instruction file. If you don't see a reference, restate the request using the file's key verbs (replace, update, remove) and package names. -1. Review the plan file and verify that it includes the custom instruction's details. - - - Review package actions. - - For example, when replacing Newtonsoft, the plan switches from a version upgrade to replacing or removing the package. +1. In the chat, choose `Upgrade to a newer version of .NET`. Answer Copilot's questions until it begins the assessment. +1. Monitor the chat to see if Copilot automatically retrieves your custom instruction file during the assessment. You should see a message indicating it opened the markdown instruction file. - The plan might start as a version upgrade, as shown in the following image: + If the custom instructions aren't automatically applied, explicitly request them. Use wording similar to the file name. For example, `use the custom instructions to replace Newtonsoft with System.Text.Json during the assessment`. - :::image type="content" source="./media/how-to-custom-upgrade-instructions/visualstudio-copilot-upgrade6.png" alt-text="The screenshot shows the project-level (feature) actions added by the custom upgrade instruction. Projects that previously referenced Newtonsoft.Json are now slated for code refactoring to use System.Text.Json APIs."::: +1. Wait for Copilot to confirm it retrieved the file. If you don't see a reference to the instruction file, restate the request using the file's key verbs (replace, update, remove) and package names. +1. Review the generated `assessment.md` file in the `.github/upgrades` folder. Confirm the assessment includes issues and changes identified by your custom instruction. - But then the plan changes to remove the package: + For example, when replacing Newtonsoft, the assessment identifies: + - Projects using `Newtonsoft.Json` packages. + - Code patterns that need refactoring to use `System.Text.Json`. + - Dependencies that need to be removed or replaced. - :::image type="content" source="./media/how-to-custom-upgrade-instructions/visualstudio-copilot-upgrade5.png" alt-text="The screenshot shows the effect of applying a custom upgrade instruction to the upgrade plan. Instead of upgrading Newtonsoft.Json, the plan now removes it and incorporates System.Text.Json as the replacement, explicitly listing the package removal and corresponding additions/changes that occur during execution."::: - - - Review execution steps. Any new execution steps referencing the transformation appear under the plan's step list. - -1. Tell Copilot to proceed with the upgrade once the plan reflects your custom instruction. -1. Monitor the **Upgrade Progress Details**. If Copilot pauses due to conflicts or compilation errors, resolve issues and instruct it to continue. +1. If needed, edit the `assessment.md` file to add context or adjust the identified issues before proceeding. +1. Tell Copilot to continue to the planning stage once the assessment reflects your custom instruction. +1. Review the `plan.md` file that Copilot generates. It should include strategies for addressing the issues identified during assessment. +1. Continue through the execution stage by telling Copilot to proceed. Monitor the `tasks.md` file as Copilot applies the transformations. ### Tips for better activation -- Match the file's verb: if the file name uses `replace`, use that phrasing (not `upgrade` or `fix`). -- Keep one transformation per file for clarity and reuse; sequence multiple files by listing prerequisites in each file. -- Ask Copilot to modify the plan rather than manually editing; this approach reduces the risk of breaking dependency ordering. -- Avoid ambiguous requests like "improve the plan"; be explicit: "apply the replace_newtonsoft_with_system_text_json instructions." +How you name and invoke custom upgrade instructions affects whether Copilot retrieves them automatically. Follow these guidelines to improve activation reliability: + +- Match the file's verb. If the file name uses `replace`, use that phrasing (not `upgrade` or `fix`). +- Keep one transformation per file for clarity and reuse. Sequence multiple files by listing prerequisites in each file. +- Request custom instructions during the assessment stage for best results, rather than waiting until planning or execution. +- Avoid ambiguous requests like "improve the assessment." Be explicit: "apply the replace_newtonsoft_with_system_text_json instructions during assessment." ## Validate the applied changes After the upgrade completes: -1. Review the upgrade report for commits related to the custom instruction. +1. Review the `tasks.md` file in `.github/upgrades` to see the status of tasks related to your custom instruction. +1. Check the Git commits created during the execution stage for changes related to the custom instruction. 1. Run your tests to ensure functional behavior remains correct. -1. (Optional) Capture a diff example from the successful change and add it to the instruction file to strengthen future automation. +1. **Optional**: Capture a diff example from the successful change and add it to the instruction file to strengthen future automation. ## Clean up resources diff --git a/docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md b/docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md index abb5e9dffbd03..52e54c3919fff 100644 --- a/docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md +++ b/docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md @@ -1,19 +1,19 @@ --- 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." +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 the three-stage workflow: assessment, planning, and execution." ms.topic: how-to -ms.date: 12/08/2025 +ms.date: 12/12/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. +#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 through a structured three-stage process. --- # 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. +GitHub Copilot app modernization is an AI-powered agent in Visual Studio that upgrades .NET projects to newer versions and migrates applications to Azure. This article guides you through upgrading your .NET applications using a structured three-stage workflow: assessment, planning, and execution. -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. +The modernization agent analyzes your projects and dependencies, creates detailed upgrade documentation at each stage, 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 @@ -21,134 +21,211 @@ Before you begin, ensure you have the following requirements: [!INCLUDE [github-copilot-app-modernization-prereqs](../../../includes/github-copilot-app-modernization-prereqs.md)] -## Start the upgrade process +## Initiate the upgrade -The first step to upgrading is generating a plan by interacting with GitHub Copilot. Follow these steps to initiate the upgrade: +To start an upgrade, interact with GitHub Copilot chat to initiate the modernization agent: [!INCLUDE[github-copilot-how-to-initiate](./includes/how-to-initiate.md)] -## Generate an upgrade plan +When you start the upgrade, Copilot prompts you to create a new branch if you're working in a Git repository. Copilot then runs a three-stage workflow, writing a Markdown file for each stage under `.github/upgrades` in your repository. If `.github/upgrades` already exists from a prior attempt, Copilot asks whether to continue or start fresh. -When you start the process, Copilot analyzes your projects and their dependencies. It then asks you a series of questions about the upgrade. After you answer these questions, Copilot writes an upgrade plan as a Markdown file. +The three stages are: -To generate and customize your plan: +- **Assessment stage** - Copilot examines your project to identify breaking changes, compatibility problems, and upgrade requirements. +- **Planning stage** - Copilot creates a detailed specification explaining how to resolve every problem. +- **Execution stage** - Copilot breaks the plan into sequential tasks and performs the upgrade. -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. +## Start assessment and review results -> [!CAUTION] -> The plan is generated based on the interdependencies 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 assessment stage examines your project structure, dependencies, and code patterns to identify what needs to change. Copilot automatically starts this stage and generates an `assessment.md` file in `.github/upgrades`. -The following snippet demonstrates the structure of a plan: +The assessment lists breaking changes, API compatibility problems, deprecated patterns, and the upgrade scope so you know exactly what needs attention. The following example shows part of an assessment for an ASP.NET Core project upgrading from .NET 6.0 to .NET 9.0: -```md -# .NET 9.0 Upgrade Plan +```markdown +# Projects and dependencies analysis -## Execution Steps +This document provides a comprehensive overview of the projects and their dependencies in the context of upgrading to .NETCoreApp,Version=v10.0. -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 +## Table of Contents -## Settings +- [Executive Summary](#executive-Summary) + - [Highlevel Metrics](#highlevel-metrics) + - [Projects Compatibility](#projects-compatibility) + - [Package Compatibility](#package-compatibility) + - [API Compatibility](#api-compatibility) +- [Aggregate NuGet packages details](#aggregate-nuget-packages-details) +- [Top API Migration Challenges](#top-api-migration-challenges) + - [Technologies and Features](#technologies-and-features) + - [Most Frequent API Issues](#most-frequent-api-issues) +- [Projects Relationship Graph](#projects-relationship-graph) +- [Project Details](#project-details) -This section contains settings and data used by execution steps. + - [MvcMovie.Tests\MvcMovie.Tests.csproj](#mvcmovietestsmvcmovietestscsproj) + - [MvcMovie\MvcMovie.csproj](#mvcmoviemvcmoviecsproj) + - [RazorMovie.Tests\RazorMovie.Tests.csproj](#razormovietestsrazormovietestscsproj) + - [RazorMovie\RazorMovie.csproj](#razormovierazormoviecsproj) + - [WpfMovie.Tests\WpfMovie.Tests.csproj](#wpfmovietestswpfmovietestscsproj) + - [WpfMovie\WpfMovie.csproj](#wpfmoviewpfmoviecsproj) -### Aggregate NuGet packages modifications across all projects +... +``` + +To review and customize the plan: + +1. Open the `assessment.md` file in `.github/upgrades`. +1. Review the identified breaking changes and compatibility problems. +1. Add any project-specific context or concerns to the document. +1. Tell Copilot to move to the planning stage. + +## Start planning and review the plan -NuGet packages used across all selected projects or their dependencies that need version update in projects that reference them. +The planning stage converts the assessment into a detailed specification that explains how to resolve every issue. When you tell Copilot to proceed to planning, it generates a `plan.md` file in `.github/upgrades`. -| 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 | +The plan documents upgrade strategies, refactoring approaches, dependency upgrade paths, and risk mitigations. The following example shows part of a plan for an ASP.NET Core project: + +```markdown +# .NET 10 Upgrade Plan + +## Table of Contents + +- [Executive Summary](#executive-summary) +- [Migration Strategy](#migration-strategy) +- [Detailed Dependency Analysis](#detailed-dependency-analysis) +- [Project-by-Project Plans](#project-by-project-plans) +- ... ... +- ... + +--- + +## Executive Summary + +### Scenario Description +Upgrade all projects in the MvcMovieNet6 solution from .NET 6 to .NET 10 (Long Term Support). The solution contains: +- **RazorMovie**: ASP.NET Core Razor Pages application (primary focus) +- **MvcMovie**: ASP.NET Core MVC application +- **WpfMovie**: Windows Presentation Foundation desktop application +- **3 Test Projects**: Unit test projects for each application + +### Scope & Current State +- **6 projects** requiring framework upgrade (net6.0 → net10.0) +- **1,862 total lines of code** across 54 files +- **16 NuGet packages** (6 require updates, 10 compatible) +- **65 identified issues** (1 security vulnerability, 1 deprecated package, 51 WPF API issues, minor behavioral changes) +- **All projects are SDK-style** (modern project format) ... ``` -## Perform the upgrade +To review and customize the plan: -When your 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. 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. +1. Open the `plan.md` file in `.github/upgrades`. +1. Review the upgrade strategies and dependency updates. +1. Edit the plan to adjust upgrade steps or add context if needed. -Each major step in the upgrade process is committed to the local Git repository. + > [!CAUTION] + > The plan is based on project interdependencies. 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. -## Review upgrade results +1. Tell Copilot to move to the execution stage. -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. +## Start execution and run the upgrade -The following example shows the report of a completed upgrade that contained a test failure: +The execution stage breaks the plan into sequential, concrete tasks with validation criteria. When you tell Copilot to proceed to execution, it generates a `tasks.md` file in `.github/upgrades`. -```md -# .NET 9 Upgrade Report +The task list describes each task and explains how Copilot confirms it succeeded. The following example shows the task list for a solution containing ASP.NET Core and WPF projects: -## Project modifications +```markdown +# MvcMovieNet6 .NET 10 Upgrade Tasks -| 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 | +## Overview -## NuGet Packages +This document tracks the execution of the MvcMovieNet6 solution upgrade from .NET 6 to .NET 10. All projects will be upgraded simultaneously in a single atomic operation. -| 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 | +**Progress**: 0/3 tasks complete (0%) ![0%](https://progress-bar.xyz/0) -## 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 | +## Tasks -## Test Results +### [ ] TASK-001: Verify prerequisites +**References**: Plan §Phase 0 -| Project Name | Passed | Failed | Skipped | -|:-----------------------|:------:|:------:|:-------:| -| RazorMovie.Tests | 0 | 0 | 0 | -| MvcMovie.Tests | 2 | 0 | 0 | -| WpfMovie.Tests | 6 | 1 | 0 | +- [ ] (1) Verify .NET 10 SDK installed per Plan §Phase 0 +- [ ] (2) .NET 10 SDK meets minimum requirements (**Verify**) -## Next steps +--- + +### [ ] TASK-002: Atomic framework and package upgrade with compilation fixes +**References**: Plan §Phase 1, Plan §Package Update Reference, Plan §Breaking Changes Catalog, Plan §Project-by-Project Plans + +- [ ] (1) Update TargetFramework to net10.0 in MvcMovie.csproj, MvcMovie.Tests.csproj, RazorMovie.csproj, RazorMovie.Tests.csproj per Plan §Phase 1 +- [ ] (2) Update TargetFramework to net10.0-windows in WpfMovie.csproj, WpfMovie.Tests.csproj per Plan §Phase 1 +- [ ] (3) All project files updated to target framework (**Verify**) +- [ ] (4) Update package references per Plan §Package Update Reference (MvcMovie: EF Core 10.0.1, Code Generation 10.0.0; RazorMovie: HtmlSanitizer 9.0.889 security fix) +- [ ] (5) All package references updated (**Verify**) +- [ ] (6) Restore all dependencies across solution +- [ ] (7) All dependencies restored successfully (**Verify**) +- [ ] (8) Build solution and fix all compilation errors per Plan §Breaking Changes Catalog (focus: BinaryFormatter removal in WpfMovie, WPF control API binary incompatibilities, UseExceptionHandler behavioral changes, HtmlSanitizer API changes) +- [ ] (9) Solution builds with 0 errors (**Verify**) +- [ ] (10) Commit changes with message: "TASK-002: Complete atomic upgrade to .NET 10 (all projects, packages, and compilation fixes)" + +--- -- 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. +### [ ] TASK-003: Run full test suite and validate upgrade +**References**: Plan §Phase 2, Plan §Testing & Validation Strategy + +- [ ] (1) Run tests in MvcMovie.Tests, RazorMovie.Tests, and WpfMovie.Tests projects +- [ ] (2) Fix any test failures (reference Plan §Breaking Changes Catalog for common issues: HtmlSanitizer behavior, BinaryFormatter replacement, framework behavioral changes) +- [ ] (3) Re-run all tests after fixes +- [ ] (4) All tests pass with 0 failures (**Verify**) +- [ ] (5) Commit test fixes with message: "TASK-003: Complete testing and validation for .NET 10 upgrade" ``` -## Next steps +To run the upgrade: + +1. Tell Copilot to start the upgrade. +1. Monitor progress by reviewing the `tasks.md` file as Copilot updates task statuses. +1. If Copilot encounters a problem it can't resolve, provide the requested help. +1. Let Copilot learn from your interventions and continue the upgrade. + +The tool creates a Git commit for every portion of the process, so you can easily roll back changes or get detailed information about what changed. + +## Verify the upgrade + +When the upgrade finishes, Copilot shows next steps in the chat response to guide you on what to do after the process. Review the `tasks.md` file for the status of every step. The tool creates a Git commit for every portion of the upgrade process, so you can easily roll back changes or get detailed information about what changed. + +The following example shows completed tasks for an ASP.NET Core project upgrade: + +```markdown +# MvcMovieNet6 .NET 10 Upgrade Tasks + +## Overview + +This document tracks the execution of the MvcMovieNet6 solution upgrade from .NET 6 to .NET 10. All projects will be upgraded simultaneously in a single atomic operation. + +**Progress**: 3/3 tasks complete (100%) ![0%](https://progress-bar.xyz/100) + +--- + +## Tasks + +### [✓] TASK-001: Verify prerequisites *(Completed: 2025-12-12 21:09)* +**References**: Plan §Phase 0 + +- [✓] (1) Verify .NET 10 SDK installed per Plan §Phase 0 +- [✓] (2) .NET 10 SDK meets minimum requirements (**Verify**) + +... +``` -After completing the upgrade process: +To verify the upgrade: -- Review the generated upgrade report and any test results. -- Address any failing tests or compilation errors. -- 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. +1. Review the final task status in `tasks.md`. +1. Address any failing tests or compilation errors. +1. Ensure all updated NuGet packages are compatible with your application. +1. Test your application thoroughly to verify the upgrade succeeded. +1. Apply new features and improvements available in the upgraded .NET version. ## Related content +- [What is GitHub Copilot app modernization?](overview.md) - [GitHub Copilot app modernization FAQ](faq.yml) diff --git a/docs/core/porting/github-copilot-app-modernization/media/how-to-custom-upgrade-instructions/visualstudio-copilot-upgrade5.png b/docs/core/porting/github-copilot-app-modernization/media/how-to-custom-upgrade-instructions/visualstudio-copilot-upgrade5.png deleted file mode 100644 index 0b8ccfe9fb6fd..0000000000000 Binary files a/docs/core/porting/github-copilot-app-modernization/media/how-to-custom-upgrade-instructions/visualstudio-copilot-upgrade5.png and /dev/null differ diff --git a/docs/core/porting/github-copilot-app-modernization/media/how-to-custom-upgrade-instructions/visualstudio-copilot-upgrade6.png b/docs/core/porting/github-copilot-app-modernization/media/how-to-custom-upgrade-instructions/visualstudio-copilot-upgrade6.png deleted file mode 100644 index fcd50e4390ab6..0000000000000 Binary files a/docs/core/porting/github-copilot-app-modernization/media/how-to-custom-upgrade-instructions/visualstudio-copilot-upgrade6.png and /dev/null differ diff --git a/docs/core/porting/github-copilot-app-modernization/overview.md b/docs/core/porting/github-copilot-app-modernization/overview.md index 2345b9cfa4cfc..3928d2935fc2b 100644 --- a/docs/core/porting/github-copilot-app-modernization/overview.md +++ b/docs/core/porting/github-copilot-app-modernization/overview.md @@ -36,6 +36,9 @@ Before using GitHub Copilot app modernization, you need these items: [!INCLUDE [github-copilot-app-modernization-prereqs](../../../includes/github-copilot-app-modernization-prereqs.md)] +> [!NOTE] +> GitHub Copilot app modernization is supported in Visual Studio Code through the [marketplace extension](https://marketplace.visualstudio.com/items?itemName=vscjava.migrate-java-to-azure). + ## Upgrade .NET projects The modernization agent supports upgrading projects coded in C#. The agent supports the following project types: diff --git a/docs/includes/github-copilot-app-modernization-prereqs.md b/docs/includes/github-copilot-app-modernization-prereqs.md index 525715ef2baaa..d450507ab3c3e 100644 --- a/docs/includes/github-copilot-app-modernization-prereqs.md +++ b/docs/includes/github-copilot-app-modernization-prereqs.md @@ -11,7 +11,7 @@ ms.topic: include - [.NET desktop development workload](/visualstudio/install/modify-visual-studio?view=visualstudio&preserve-view=true#change-workloads-or-individual-components) with the following optional components enabled: - GitHub Copilot - - GitHub Copilot app modernization for .NET + - GitHub Copilot app modernization - GitHub Copilot Subscription (paid or free).