From c25b901bca41af9302ea1edce519f060be7576bc Mon Sep 17 00:00:00 2001 From: "Andy De George (from Dev Box)" Date: Mon, 6 Apr 2026 09:05:51 -0700 Subject: [PATCH 01/13] Update GitHub Copilot modernization docs with latest features - Update overview.md with 8 scenarios, VB support, new project types, four-phase workflow, upgrade strategies, flow modes, state management - Update install.md with correct VS Code extension name, VB support - Update faq.yml with new scenarios, version matrix, new Q&As - Update how-to-upgrade with upgrade options phase, flow modes - Create concepts.md covering scenarios, skills, tasks, workflow, state management, flow modes, and resumability - Create scenarios-and-skills.md with full reference of 8 scenarios and 30+ built-in migration skills organized by domain - Create best-practices.md with preparation, collaboration, pitfalls, recovery, security, and performance guidance - Create troubleshooting.md covering workflow, build, Git, performance, and customization issues - Update toc.yml and index.yml with new articles Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../best-practices.md | 196 +++++++++++++++ .../concepts.md | 216 +++++++++++++++++ .../github-copilot-app-modernization/faq.yml | 41 +++- .../how-to-upgrade-with-github-copilot.md | 48 ++-- .../index.yml | 8 + .../install.md | 11 +- .../overview.md | 105 ++++++-- .../scenarios-and-skills.md | 226 ++++++++++++++++++ .../github-copilot-app-modernization/toc.yml | 8 + .../troubleshooting.md | 189 +++++++++++++++ 10 files changed, 1005 insertions(+), 43 deletions(-) create mode 100644 docs/core/porting/github-copilot-app-modernization/best-practices.md create mode 100644 docs/core/porting/github-copilot-app-modernization/concepts.md create mode 100644 docs/core/porting/github-copilot-app-modernization/scenarios-and-skills.md create mode 100644 docs/core/porting/github-copilot-app-modernization/troubleshooting.md diff --git a/docs/core/porting/github-copilot-app-modernization/best-practices.md b/docs/core/porting/github-copilot-app-modernization/best-practices.md new file mode 100644 index 0000000000000..3ddbc39706e07 --- /dev/null +++ b/docs/core/porting/github-copilot-app-modernization/best-practices.md @@ -0,0 +1,196 @@ +--- +title: Best practices for GitHub Copilot modernization +description: "Learn best practices for using GitHub Copilot modernization to upgrade .NET projects, including preparation, collaboration tips, common pitfalls, and recovery strategies." +ms.topic: best-practice +ms.date: 04/06/2026 +ai-usage: ai-assisted + +#customer intent: As a developer, I want to follow best practices when using GitHub Copilot modernization so that I can get the best results from my .NET upgrades and avoid common problems. + +--- + +# Best practices for GitHub Copilot modernization + +Follow these guidelines to get the best results from GitHub Copilot modernization when upgrading and migrating .NET projects. + +## Before you start + +### Verify that your solution builds and tests pass + +The agent validates every change it makes by running builds and tests. If your solution is already broken before you start, the agent can't distinguish pre-existing failures from problems it introduced. + +```dotnetcli +dotnet build YourSolution.sln +dotnet test YourSolution.sln +``` + +If there are known test failures, document them in `scenario-instructions.md` so the agent knows to ignore them. + +### Commit or stash uncommitted work + +Start with a clean working directory to avoid mixing your uncommitted changes with the agent's modifications. A clean baseline makes it easier to review or revert changes. + +```console +git stash +git status +``` + +### Back up non-Git repositories + +The agent also works with folders that aren't under source control. If your project isn't in a Git repository, the agent skips branch and commit operations. In this case, back up your project folder before starting so you can restore it if needed. + +### Review your test coverage + +The agent relies on tests to validate that its changes don't break behavior. Projects with good test coverage get higher-confidence upgrades. + +> [!TIP] +> You don't need 100% coverage. Focus on the code most likely to be affected by the upgrade—API boundaries, serialization, database access, and authentication. + +### Start small + +If this is your first time using the agent, pick a small, low-risk project as a pilot. A class library or utility project is ideal. Starting small lets you understand the workflow, build confidence, and discover any repo-specific issues before tackling your main application. + +## During the upgrade + +### Use guided mode for your first upgrade + +The agent supports both guided and automatic modes. In guided mode, the agent pauses at key decision points for your review and approval. Start with guided mode to understand what the agent does and why. Switch to automatic mode once you're comfortable with the workflow. + +### Review the assessment carefully + +The assessment phase is your best opportunity to catch issues before the agent starts making changes. Look for: + +- Projects the agent might have missed or misidentified. +- Dependencies that you know are problematic. +- Anything unusual about your solution that the agent should know. + +If you spot something, tell the agent in chat or add the information to `scenario-instructions.md`. + +### Take time with the planning phase + +The agent generates a task plan based on its assessment. Review the plan before proceeding: + +- Does the order make sense for your codebase? +- Are there dependencies the agent might not know about? +- Should any projects be excluded or handled differently? + +You can ask the agent to reorder tasks, skip projects, or change its approach. You know your codebase better than the agent—use that knowledge. + +### Give feedback immediately + +The agent learns from your corrections within a session. If the agent makes a choice you disagree with: + +- Tell it right away: *"Don't use that pattern, use X instead."* +- Add persistent guidance to `scenario-instructions.md` so the agent remembers across tasks and sessions. + +## Common pitfalls + +### Large solutions with 50+ projects + +The agent works project-by-project, so large solutions take time. Be patient and monitor progress. Consider starting with one representative project end-to-end before committing to the full solution. Doing so surfaces systemic issues early. + +### Private NuGet feeds + +For private NuGet feeds, authenticate before starting the upgrade (for example, through your organization's credential provider or feed configuration). Without authentication, package restore failures block progress. + +### Custom MSBuild targets and imports + +Complex build customizations—custom `.targets` files, conditional imports, or non-standard build logic—can confuse the assessment and cause unexpected build failures. If your solution has these customizations, mention them in chat or in `scenario-instructions.md` so the agent can account for them. + +### Session timeouts + +Long-running upgrades might span multiple sessions. The agent tracks its progress in workflow files (under `.github/upgrades/`), so the agent can pick up where it left off. When you start a new session, mention where you were: *"Continue the .NET 10 upgrade—I was in the middle of the Data.Access project."* + +## Collaborate effectively + +### Be specific about scope + +The more specific you are, the better the agent performs: + +| Instead of | Try | +|---|---| +| *"Upgrade everything"* | *"Upgrade the Data.Access project to .NET 10"* | +| *"Fix the build"* | *"Fix the build error in CustomerService.cs related to the removed API"* | +| *"Migrate the database stuff"* | *"Migrate Entity Framework 6 to EF Core in the Repository project"* | + +### Share your constraints + +Tell the agent about real-world constraints upfront: + +- *"We can't break backward compatibility for the public API."* +- *"We have a release deadline in two weeks—prioritize the web projects."* +- *"The legacy reporting module should be excluded from this upgrade."* + +### Explain your architecture + +The agent analyzes code structure, but it doesn't know your team's mental model. Help the agent understand: + +- *"Project A is our shared library—B, C, and D all depend on it."* +- *"The WebApi project is our public-facing API; Internal.Api is for internal services only."* +- *"The Models project is auto-generated from our OpenAPI spec—don't modify it directly."* + +### Ask why + +The agent can explain its reasoning. If a decision doesn't look right, ask: + +- *"Why did you choose bottom-up order?"* +- *"Why are you upgrading this package to version X instead of Y?"* +- *"Why did you break this into sub-tasks?"* + +Understanding the reasoning helps you give better feedback. + +### Save preferences early + +If you have strong preferences about coding style, patterns, or approaches, add them to `scenario-instructions.md` in the first session. This file persists across sessions and is always in the agent's context, making it the most reliable way to influence behavior. + +## Recover from problems + +### Build failures after a task + +Tell the agent: *"The build is failing after the last task."* The agent analyzes the error and attempts to fix it. If the agent can't resolve the issue: + +1. Provide a manual fix and tell the agent what you did—the agent learns from it. +1. Revert the commit (`git revert` or reset to the previous commit) and ask the agent to try a different approach. +1. Skip the problematic task and come back to it later. + +### Wrong strategy chosen + +If the agent's overall approach doesn't work for your codebase, restart the planning phase: + +- *"Let's redo the plan—I want to upgrade the web projects first instead of bottom-up."* +- *"Change the strategy to upgrade all shared libraries in one batch."* + +### Agent stuck in a loop + +If the agent repeats the same fix without progress, say *"Stop"* and describe what you're observing. The agent can reset its approach and try something different. + +### Undo all changes + +If you used a Git branch for the upgrade, undo everything by switching back to your original branch: + +```console +git checkout your-original-branch +git branch -D upgrade-branch +``` + +Your original code is untouched. If you're working without source control, restore from the backup you made before starting. + +## Security and privacy + +- **Code snippets** sent to GitHub Copilot for analysis are processed according to [GitHub's Copilot privacy policy](https://docs.github.com/en/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-your-ide) and aren't retained beyond the immediate session. +- **Workflow files** (`scenario-instructions.md`, custom tasks, preferences) are stored locally in your repository under `.github/upgrades/`. These files aren't transmitted to external services. +- **The `.github/upgrades/` folder** is part of your repository. Commit the folder—it contains your upgrade progress and state. The agent needs the folder to resume work across sessions. You can remove it after the upgrade is complete. +- **Telemetry** can be disabled through your IDE's telemetry settings. + +## Performance tips + +- **Close unnecessary files and tabs** — The agent analyzes the active workspace, and fewer open files means less noise. +- **Upgrade in stages for very large solutions** — Rather than upgrading all projects at once, batch them. For example, upgrade all libraries first, then all web projects, then tests. +- **Use build caching** — The agent runs many incremental builds during validation. Warm build caches make validation significantly faster. Avoid cleaning the build output between tasks. + +## Related content + +- [What is GitHub Copilot modernization?](overview.md) +- [Upgrade a .NET app with GitHub Copilot modernization](how-to-upgrade-with-github-copilot.md) +- [Core concepts](concepts.md) +- [Troubleshoot GitHub Copilot modernization](troubleshooting.md) diff --git a/docs/core/porting/github-copilot-app-modernization/concepts.md b/docs/core/porting/github-copilot-app-modernization/concepts.md new file mode 100644 index 0000000000000..19470e4831913 --- /dev/null +++ b/docs/core/porting/github-copilot-app-modernization/concepts.md @@ -0,0 +1,216 @@ +--- +title: GitHub Copilot modernization core concepts +description: "Learn the key concepts behind GitHub Copilot modernization, including scenarios, skills, tasks, the four-phase workflow, state management, and flow modes." +ms.topic: concept-article +ms.date: 04/06/2026 +ai-usage: ai-assisted + +#customer intent: As a developer, I want to understand the core concepts of GitHub Copilot modernization so that I can use the agent effectively and get the best results from my upgrades. + +--- + +# GitHub Copilot modernization concepts + +GitHub Copilot modernization uses a structured approach to upgrade and migrate .NET projects. Understanding how the agent works—its scenarios, skills, tasks, and workflow—helps you collaborate with the agent effectively and get the best results. + +> [!TIP] +> Think of the agent as a skilled colleague who understands .NET deeply, follows a structured plan, and adapts to your feedback. The more context you give, the better the agent performs. + +## The agent as a teammate + +The agent is designed for collaboration, not automation in a vacuum: + +- **Deep .NET knowledge** — The agent understands project files, NuGet dependencies, breaking changes, and migration patterns across dozens of .NET technologies for both C# and Visual Basic projects. +- **Structured workflow** — Every upgrade goes through assessment, planning, and execution. No random changes, no surprises. +- **Learns your preferences** — When you say "always use explicit types instead of `var`," the agent writes that preference to `scenario-instructions.md` and remembers it across sessions. +- **Correctable mid-flight** — Made a wrong call? Tell the agent. It adapts and applies the correction going forward. +- **Explains its reasoning** — Ask "why did you choose that approach?" and the agent walks you through the decision. + +## Scenarios + +A _scenario_ is a managed, end-to-end modernization workflow. When you tell the agent "upgrade my solution to .NET 10," you're triggering the `.NET version upgrade` scenario. + +### How scenarios are discovered + +You don't need to memorize scenario names. The agent discovers relevant scenarios automatically: + +1. Analyzes your codebase to understand what technologies you're using—language, framework version, libraries, and project types. +1. Identifies which scenarios are relevant to your projects. +1. Ranks scenarios by importance and weight—the most relevant ones surface first. +1. You can also ask directly: *"What scenarios are available for my solution?"* + +### Scenario persistence + +Each active scenario gets its own folder at `.github/upgrades/{scenarioId}/`. This folder contains the plan, task progress, your preferences, and execution logs. The folder is part of your Git repository. + +For a complete list of scenarios, see [Scenarios and skills reference](scenarios-and-skills.md). + +## The workflow lifecycle + +Every scenario follows the same four-phase lifecycle. + +### Phase 1: Pre-initialization + +The agent gathers everything it needs before starting work: + +- **Target framework** — What version you're upgrading to. +- **Git strategy** — The agent suggests branching and you control the details: branch name, whether to use per-task branches, and commit timing. +- **Flow mode** — Automatic (agent drives) or Guided (you approve each phase). +- **Scenario-specific parameters** — Depending on the scenario, the agent might ask additional questions. + +The agent initializes the scenario workspace at `.github/upgrades/{scenarioId}/`. + +### Phase 2: Assessment + +The agent analyzes your codebase: + +- Project dependency graph (topological order) +- NuGet package compatibility with the target framework +- Breaking API changes +- Test coverage +- Complexity and risk factors + +The assessment produces a comprehensive report saved to `assessment.md`. In **Guided mode**, the agent pauses here for your review before proceeding. + +### Phase 3: Planning + +Based on the assessment, the agent determines your upgrade options and generates a task plan. This phase has two parts: + +**Upgrade options confirmation** — The agent evaluates your solution and identifies which upgrade decisions are relevant. It presents sensible defaults and lets you review and override any choice. + +Options might include: + +- **Upgrade strategy** — Bottom-up, top-down, or all-at-once. +- **Project migration approach** — In-place rewrite or side-by-side for web applications; in-place or multi-targeting for libraries. +- **Technology modernization** — Choices for Entity Framework migration, dependency injection, logging, and configuration. +- **Package management** — Whether and when to adopt Central Package Management. +- **Compatibility handling** — How to address unsupported APIs and packages. + +Confirmed decisions are saved to `upgrade-options.md`. + +**Plan generation** — The agent creates the task plan. Planning produces three key files: + +- `plan.md` — The upgrade plan with strategy and task descriptions. +- `scenario-instructions.md` — Your preferences, decisions, and the agent's memory. +- `tasks.md` — Visual progress dashboard. + +### Phase 4: Execution + +The agent works through tasks sequentially. For each task, the agent follows a cycle: start, execute, validate (build and test), and complete. You control when and how changes are committed—per task, per group of tasks, or at the end. + +## Upgrade strategies + +During the upgrade options confirmation, the agent evaluates your solution and recommends one of these strategies: + +| Strategy | Best for | How it works | +|---|---|---| +| **Bottom-up** | Large solutions with deep dependency graphs | Start with leaf projects (no dependencies), work upward | +| **Top-down** | Quick feedback on the main app | Start with the application project, fix dependencies as needed | +| **All-at-once** | Small, simple solutions | Upgrade everything in one pass | + +> [!TIP] +> The agent only surfaces decisions that are relevant to your project. A simple console app doesn't see web framework choices, and a project without Entity Framework doesn't see database migration options. + +## Skills + +_Skills_ are focused modernization capabilities—smaller, targeted upgrade operations. When the agent encounters EF6 code during an upgrade, it loads the EF6-to-EF-Core skill with detailed, step-by-step migration instructions. You can also invoke a skill directly: *"migrate the WCF services in my project to CoreWCF."* + +The agent ships with 30+ built-in skills organized by domain: + +- **Data access** — EF6 to EF Core (code-first and EDMX), LINQ to SQL, SqlClient migration +- **Web/ASP.NET** — Identity, Global.asax, OWIN, MVC routing/filters/bundling, WCF to CoreWCF +- **Serialization** — Newtonsoft.Json to System.Text.Json +- **Cloud** — Azure Functions in-process to isolated worker model +- **Libraries** — ADAL to MSAL, SignalR, PowerShell SDK, and more + +Skills load automatically based on what the agent detects in your codebase. You don't need to manage skill loading—just describe what you need. + +For the complete list, see [Scenarios and skills reference](scenarios-and-skills.md). + +## Tasks + +_Tasks_ are the atomic units of work within a scenario. Each task represents a specific, bounded piece of the upgrade, such as "Upgrade CommonLib from .NET 6 to .NET 10" or "Migrate EF6 usage in DataLayer to EF Core." + +### Task lifecycle + +Tasks move through these states: + +- **Available** — Ready to start, all dependencies met. +- **In Progress** — The agent is actively working on the task. +- **Completed** — Code changes applied, build passes, tests pass. + +For each task, the agent: + +1. Loads related skills and context. +1. Assesses complexity and decides whether the task needs subtasks. +1. Writes a scope summary to `tasks/{taskId}/task.md`. +1. Executes code changes. +1. Validates by running build and tests. +1. Records results in `tasks/{taskId}/progress-details.md`. +1. Commits changes and moves to the next task. + +## State management + +The agent maintains persistent state so you can stop and resume at any time. Everything lives in your repository under `.github/upgrades/{scenarioId}/`. + +| File | Purpose | +|---|---| +| `scenario-instructions.md` | Your preferences, decisions, and custom instructions—the agent's persistent memory | +| `upgrade-options.md` | Confirmed upgrade decisions | +| `plan.md` | The upgrade plan with strategy and task descriptions | +| `tasks.md` | Visual progress dashboard showing task status | +| `execution-log.md` | Detailed log of all changes and decisions | +| `tasks/{taskId}/task.md` | Per-task scope and context | +| `tasks/{taskId}/progress-details.md` | Per-task execution notes and results | + +### Resumability + +Close the chat, close your IDE, or come back the next day. The agent picks up where it left off: + +1. On your next interaction, the agent checks the current state of your workspace automatically. +1. The agent detects the existing scenario and shows current progress, such as "3 of 8 tasks completed." +1. The agent detects stale tasks (stuck in progress from a previous interrupted session) and offers to resume or restart them. +1. Your preferences in `scenario-instructions.md` are reloaded. + +### Cross-IDE continuity + +Because state lives in Git, you can switch between VS Code and Visual Studio mid-upgrade. The `.github/upgrades/` folder is the shared state that both IDEs understand. + +> [!TIP] +> Commit the `.github/upgrades/` folder to your branch. Push it to a remote repository to let team members view progress or to continue the upgrade on a different machine. + +## Flow modes + +The agent supports two flow modes that control how much oversight you have: + +### Automatic mode + +The agent works through all phases—assessment, planning, execution—without pausing for approval. It surfaces key findings and progress updates, but keeps moving forward. + +Best for experienced users, straightforward upgrades, and small solutions. + +### Guided mode + +The agent pauses at each phase boundary for your review: + +- After assessment: *"Here's what I found. Shall I proceed with planning?"* +- After planning: *"Here's the task plan. Do you want me to start execution?"* +- Before complex task breakdowns: *"This task is complex. Here's how I'd break it down."* + +Best for first-time users, complex solutions, and when you want to learn the process. + +### Switch modes at any time + +- Say **"pause"** or **"switch to guided"** to switch to Guided mode. +- Say **"continue"** or **"go ahead"** to switch to Automatic mode. + +> [!TIP] +> Start with Guided mode for your first upgrade to understand the workflow, then switch to Automatic once you're comfortable. + +## Related content + +- [What is GitHub Copilot modernization?](overview.md) +- [Scenarios and skills reference](scenarios-and-skills.md) +- [Upgrade a .NET app with GitHub Copilot modernization](how-to-upgrade-with-github-copilot.md) +- [Best practices](best-practices.md) +- [Troubleshoot GitHub Copilot modernization](troubleshooting.md) diff --git a/docs/core/porting/github-copilot-app-modernization/faq.yml b/docs/core/porting/github-copilot-app-modernization/faq.yml index 41efcdc324e3e..cc4ea8344154a 100644 --- a/docs/core/porting/github-copilot-app-modernization/faq.yml +++ b/docs/core/porting/github-copilot-app-modernization/faq.yml @@ -4,7 +4,7 @@ metadata: description: "This article answers frequently asked questions about GitHub Copilot modernization for .NET." titleSuffix: "" ms.topic: faq - ms.date: 03/05/2026 + ms.date: 04/06/2026 title: GitHub Copilot modernization FAQ summary: | @@ -52,9 +52,9 @@ sections: - question: Can I customize or guide the agent? answer: | - The agent uses customization Copilot provides, such as instruction files and skills. Customization is based on what your Copilot supports. + The agent uses customization Copilot provides, such as instruction files and skills. Customization is based on what your Copilot supports. The agent includes 30+ built-in migration skills that load automatically based on the technologies detected in your codebase. You can also create custom skills and scenarios. For more information, see [Apply custom upgrade instructions](how-to-custom-upgrade-instructions.md). - If you manually adjust a fix, provide additional instructions in chat, or update the Markdown in the plan file, it learns from that interaction in the short term. + If you manually adjust a fix, provide additional instructions in chat, or update the Markdown in the plan file, the agent learns from that interaction in the short term. Preferences and decisions are saved to `scenario-instructions.md` in the `.github/upgrades/` folder so they persist across sessions. - question: Does the agent store my source code? answer: | @@ -79,7 +79,9 @@ sections: questions: - question: What can the agent upgrade? answer: | - GitHub Copilot modernization helps you upgrade your .NET projects or migrate them to Azure. Besides upgrading the target framework, the agent works with these project types: + GitHub Copilot modernization helps you upgrade your .NET projects or migrate them to Azure. The agent supports multiple scenarios beyond framework upgrades, including Aspire integration, SDK-style conversion, Newtonsoft.Json migration, SqlClient migration, Azure Functions upgrade, and Semantic Kernel to Agents migration. For a full reference, see [Scenarios and skills reference](scenarios-and-skills.md). + + The agent works with these project types: - Azure Functions - Console apps and class libraries @@ -88,10 +90,37 @@ sections: - Blazor - Razor Pages - Web API - - Desktop technologies such as Windows Forms and Windows Presentation Foundation - - Test projects such as MSTest and NUnit + - Desktop technologies such as Windows Forms, Windows Presentation Foundation, and WinUI + - .NET MAUI and Xamarin + - Test projects such as MSTest, NUnit, and xUnit - .NET Framework projects + The agent supports both C# and Visual Basic. + + - question: What .NET versions can I upgrade to? + answer: | + The agent supports the following upgrade paths: + + | Source | Target | + |---|---| + | .NET Framework (any version) | .NET 8, 9, 10, or later | + | .NET Core 1.x–3.x | .NET 8, 9, 10, or later | + | .NET 5–7 | .NET 8, 9, 10, or later | + | .NET 8 | .NET 9, 10, or later | + | .NET 9 | .NET 10 or later | + + - question: Can I use the agent offline? + answer: | + No. The agent requires an internet connection and the GitHub Copilot cloud infrastructure. The agent works with all Copilot subscription tiers, including the free tier. + + - question: Does the agent modify files outside the solution? + answer: | + No. The agent only modifies files within your workspace and the `.github/upgrades/` folder. Custom task data stays in your repository. + + - question: Can I partially accept the agent's changes? + answer: | + Yes. Because each task is committed separately, you can cherry-pick specific commits by using standard Git commands. Review the commit history with `git log --oneline` and use `git cherry-pick` to select individual changes. + - name: Migrate to Azure questions: - question: What can the agent migrate? 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 db0bbcc03f2f8..56e2b79405902 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 modernization -description: "Learn how to upgrade your .NET applications to newer versions using GitHub Copilot modernization. This step-by-step guide covers the three-stage workflow: assessment, planning, and execution." +description: "Learn how to upgrade your .NET applications to newer versions using GitHub Copilot modernization. This step-by-step guide covers the four-phase workflow: assessment, upgrade options, planning, and execution." ms.topic: how-to -ms.date: 03/23/2026 +ms.date: 04/06/2026 ai-usage: ai-assisted -#customer intent: As a developer, I want to upgrade my .NET app using GitHub Copilot modernization so that I can modernize my codebase efficiently with AI assistance through a structured three-stage process. +#customer intent: As a developer, I want to upgrade my .NET app using GitHub Copilot modernization so that I can modernize my codebase efficiently with AI assistance through a structured four-phase process. --- # Upgrade a .NET app with GitHub Copilot modernization -GitHub Copilot modernization is an AI-powered agent 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. +GitHub Copilot modernization is an AI-powered agent that upgrades .NET projects to newer versions and migrates applications to Azure. This article guides you through upgrading your .NET applications using a structured four-phase workflow: assessment, upgrade options, planning, and execution. -The modernization agent analyzes your projects and dependencies, creates detailed upgrade documentation at each stage, and helps 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 phase, and helps 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 @@ -25,17 +25,18 @@ To start an upgrade, use the `modernize-dotnet` agent in Copilot: [!INCLUDE[github-copilot-how-to-initiate](./includes/how-to-initiate.md)] -When you start the upgrade, Copilot collects pre-initialization information: the target framework version, Git branching strategy, and workflow mode (automatic or guided by you). Copilot then runs a three-stage workflow, writing a Markdown file for each stage under `.github/upgrades/{scenarioId}` in your repository. The `{scenarioId}` is a unique identifier for the upgrade type, such as `dotnet-version-upgrade`. If `.github/upgrades/{scenarioId}` already exists from a prior attempt, Copilot asks whether to continue or start fresh. +When you start the upgrade, Copilot collects pre-initialization information: the target framework version, Git branching strategy, and workflow mode (automatic or guided by you). Copilot then runs a four-phase workflow, writing Markdown files for each phase under `.github/upgrades/{scenarioId}` in your repository. The `{scenarioId}` is a unique identifier for the upgrade type, such as `dotnet-version-upgrade`. If `.github/upgrades/{scenarioId}` already exists from a prior attempt, Copilot asks whether to continue or start fresh. -The three stages are: +The four phases are: -- **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. +- **Assessment phase** — Copilot examines your project to identify breaking changes, compatibility problems, and upgrade requirements. +- **Upgrade options phase** — Copilot presents strategy decisions for review, such as upgrade strategy, project migration approach, and technology modernization options. +- **Planning phase** — Copilot creates a detailed specification explaining how to resolve every problem. +- **Execution phase** — Copilot breaks the plan into sequential tasks and performs the upgrade. ## Start assessment and review results -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/{scenarioId}`. +The assessment phase examines your project structure, dependencies, and code patterns to identify what needs to change. Copilot automatically starts this phase and generates an `assessment.md` file in `.github/upgrades/{scenarioId}`. The assessment lists breaking changes, API compatibility problems, deprecated patterns, and the upgrade scope. The following example shows part of an assessment for an ASP.NET Core project upgrading from .NET 6.0 to .NET 10.0: @@ -73,11 +74,25 @@ To review and customize the assessment: 1. Open the `assessment.md` file in `.github/upgrades/{scenarioId}`. 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. +1. Tell Copilot to move to the upgrade options phase. + +## Review upgrade options + +After the assessment, Copilot evaluates your solution and presents upgrade strategy decisions for your review. The agent recommends an approach based on your project's structure and saves confirmed decisions to `upgrade-options.md` in `.github/upgrades/{scenarioId}`. + +The options typically include: + +- **Upgrade strategy** — Bottom-up (leaf projects first), top-down (application first), or all-at-once (all projects in one pass). +- **Project migration approach** — In-place rewrite or side-by-side migration. +- **Technology modernization** — Whether to upgrade technologies like Entity Framework (EF6 to EF Core), dependency injection, logging, and configuration. +- **Package management** — Whether to adopt Central Package Management. +- **Compatibility handling** — How to address unsupported APIs, incompatible packages, and platform-specific functionality. + +Review the proposed options and confirm or override them. Tell Copilot to proceed to the planning phase. ## Start planning and review the plan -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/{scenarioId}`. +The planning phase converts the assessment and your confirmed upgrade options 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/{scenarioId}`. The agent also creates a `scenario-instructions.md` file that stores preferences, decisions, and custom instructions for the upgrade. 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: @@ -123,11 +138,11 @@ To review and customize the plan: > [!CAUTION] > The plan is based on project interdependencies. The upgrade doesn'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. -1. Tell Copilot to move to the execution stage. +1. Tell Copilot to move to the execution phase. ## Start execution and run the upgrade -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/{scenarioId}`. +The execution phase 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/{scenarioId}`. The task list describes each task and how Copilot validates success. The following example shows the task list for a solution containing ASP.NET Core and WPF projects: @@ -227,4 +242,7 @@ To verify the upgrade: - [What is GitHub Copilot modernization?](overview.md) - [Install GitHub Copilot modernization](install.md) +- [Core concepts](concepts.md) +- [Best practices](best-practices.md) +- [Troubleshoot GitHub Copilot modernization](troubleshooting.md) - [GitHub Copilot modernization FAQ](faq.yml) diff --git a/docs/core/porting/github-copilot-app-modernization/index.yml b/docs/core/porting/github-copilot-app-modernization/index.yml index bd59324058d47..3e256c830828d 100644 --- a/docs/core/porting/github-copilot-app-modernization/index.yml +++ b/docs/core/porting/github-copilot-app-modernization/index.yml @@ -19,6 +19,10 @@ landingContent: url: overview.md - text: Install url: install.md + - text: Core concepts + url: concepts.md + - text: Scenarios and skills reference + url: scenarios-and-skills.md - text: FAQ url: faq.yml - linkListType: how-to-guide @@ -27,6 +31,10 @@ landingContent: url: how-to-upgrade-with-github-copilot.md - text: How to apply custom upgrade instructions url: how-to-custom-upgrade-instructions.md + - text: Best practices + url: best-practices.md + - text: Troubleshooting + url: troubleshooting.md - title: Migrate .NET apps to Azure linkLists: diff --git a/docs/core/porting/github-copilot-app-modernization/install.md b/docs/core/porting/github-copilot-app-modernization/install.md index db0a50da8d4f7..504f0c14a23ab 100644 --- a/docs/core/porting/github-copilot-app-modernization/install.md +++ b/docs/core/porting/github-copilot-app-modernization/install.md @@ -2,7 +2,7 @@ title: Install GitHub Copilot modernization description: "Learn how to install and set up GitHub Copilot modernization across Visual Studio, Visual Studio Code, GitHub Copilot CLI, and GitHub.com." ms.topic: install-set-up-deploy -ms.date: 03/04/2026 +ms.date: 04/06/2026 ai-usage: ai-assisted zone_pivot_groups: copilot-modernization-install @@ -25,7 +25,7 @@ Before you install, make sure you have the following: - [.NET desktop development workload](/visualstudio/install/modify-visual-studio?view=visualstudio&preserve-view=true#change-workloads-or-individual-components) with these optional components enabled: **GitHub Copilot**, **GitHub Copilot modernization**. - GitHub Copilot subscription (paid or free). - [Sign in to Visual Studio with a GitHub account](/visualstudio/ide/work-with-github-accounts) that has [Copilot access](https://docs.github.com/copilot/get-started/plans#ready-to-choose-a-plan). -- Code written in C#. +- Code written in C# or Visual Basic. ## Install @@ -50,7 +50,11 @@ Before you install, make sure you have the following: ## Install -Install the [GitHub Copilot modernization extension](https://marketplace.visualstudio.com/items?itemName=vscjava.migrate-java-to-azure) from the VS Code Marketplace. +1. In Visual Studio Code, open the **Extensions** view (Ctrl+Shift+X). +1. Search for **GitHub Copilot modernization for .NET**. +1. Select **Install**. + +The extension automatically acquires the .NET SDK if it's missing, registers tools, and adds the agent to Copilot Chat as `modernize-dotnet`. ## Verify the installation @@ -118,4 +122,5 @@ The `modernize-dotnet` agent appears as an available coding agent in your reposi - [What is GitHub Copilot modernization?](overview.md) - [Upgrade a .NET app with GitHub Copilot modernization](how-to-upgrade-with-github-copilot.md) +- [Core concepts](concepts.md) - [GitHub Copilot modernization FAQ](faq.yml) diff --git a/docs/core/porting/github-copilot-app-modernization/overview.md b/docs/core/porting/github-copilot-app-modernization/overview.md index 428e40b279f13..fb2a7dd34b5ed 100644 --- a/docs/core/porting/github-copilot-app-modernization/overview.md +++ b/docs/core/porting/github-copilot-app-modernization/overview.md @@ -3,7 +3,7 @@ title: GitHub Copilot modernization overview description: "Learn about GitHub Copilot modernization, a Copilot agent available across Visual Studio, Visual Studio Code, GitHub Copilot CLI, and GitHub.com that upgrades .NET projects and migrates apps to Azure." titleSuffix: "" ms.topic: overview -ms.date: 03/04/2026 +ms.date: 04/06/2026 ai-usage: ai-assisted #customer intent: As a developer, I want to learn about what GitHub Copilot modernization is, so that I understand its capabilities and how I can take advantage of it. @@ -24,9 +24,26 @@ Use this agent to: - Fix issues and apply best practices for cloud migration. - Validate that your app builds and tests successfully. +## Scenarios + +The agent provides multiple end-to-end modernization workflows called _scenarios_. Each scenario is a managed workflow that guides you through a specific type of upgrade or migration: + +| Scenario | Description | Example prompt | +|---|---|---| +| **.NET version upgrade** | Upgrades from older .NET versions to .NET 8, 9, 10, or later | *"Upgrade my solution to .NET 10"* | +| **Aspire integration** | Adds .NET Aspire orchestration to your solution | *"Add Aspire to my solution"* | +| **Aspire version upgrade** | Upgrades existing .NET Aspire projects to a newer version | *"Upgrade Aspire to latest"* | +| **SDK-style conversion** | Converts legacy project format to SDK-style | *"Convert to SDK-style"* | +| **Newtonsoft.Json migration** | Replaces Newtonsoft.Json with System.Text.Json | *"Migrate from Newtonsoft.Json"* | +| **SqlClient migration** | Migrates from System.Data.SqlClient to Microsoft.Data.SqlClient | *"Update SqlClient"* | +| **Azure Functions upgrade** | Upgrades Azure Functions from in-process to isolated worker model | *"Upgrade my Azure Functions"* | +| **Semantic Kernel to Agents** | Migrates Semantic Kernel Agents to Microsoft Agents AI | *"Migrate my SK agents"* | + +For a full reference of all scenarios and 30+ built-in migration skills, see [Scenarios and skills reference](scenarios-and-skills.md). + ## Provide feedback -Microsoft values your feedback and uses it to improve this agent. There are two ways to leave feedback: +Microsoft values your feedback and uses it to improve the agent. There are two ways to leave feedback: - In Visual Studio, use the [Suggest a feature](/visualstudio/ide/suggest-a-feature) and [Report a problem](/visualstudio/ide/report-a-problem) options. @@ -38,26 +55,32 @@ Set up GitHub Copilot modernization in your development environment before using ## Upgrade .NET projects -The modernization agent supports upgrading C# projects of the following types: +The modernization agent supports upgrading C# and Visual Basic projects of the following types: - ASP.NET Core (and related technologies such as MVC, Razor Pages, and Web API) - Blazor - Azure Functions - Windows Presentation Foundation (WPF) - Windows Forms +- WinUI +- .NET MAUI and Xamarin - Class libraries - Console apps +- Test projects (MSTest, NUnit, and xUnit) To start an upgrade, see [Upgrade a .NET app with GitHub Copilot modernization](how-to-upgrade-with-github-copilot.md). -### Upgrade paths +### Supported upgrade paths The agent supports the following upgrade paths: -- Upgrade projects from older .NET versions to the latest. -- Upgrade .NET Framework projects to .NET. -- Modernize your code base by using new features. -- Migrate components and services to Azure. +| Source | Target | +|---|---| +| .NET Framework (any version) | .NET 8, 9, 10, or later | +| .NET Core 1.x–3.x | .NET 8, 9, 10, or later | +| .NET 5–7 | .NET 8, 9, 10, or later | +| .NET 8 | .NET 9, 10, or later | +| .NET 9 | .NET 10 or later | ## Migrate .NET projects to Azure @@ -129,28 +152,68 @@ To start an upgrade or migration process, see: [!INCLUDE[github-copilot-how-to-initiate](./includes/how-to-initiate.md)] -When you ask the modernization agent to upgrade your app, Copilot first prompts you to create a new branch if you're working in a Git repository. Then Copilot runs a three-stage workflow. Each stage writes a Markdown file under `.github/upgrades` in your repository so you can review what comes next before you continue. If `.github/upgrades` already exists from a prior attempt, Copilot asks whether to continue or start fresh. +When you ask the modernization agent to upgrade your app, Copilot first prompts you to create a new branch if you're working in a Git repository. Then Copilot runs a four-phase workflow. Each phase produces Markdown files under `.github/upgrades/{scenarioId}` in your repository so you can review what comes next before you continue. If `.github/upgrades/{scenarioId}` already exists from a prior attempt, Copilot asks whether to continue or start fresh. + +The four phases are: + +1. **Assessment** — Copilot examines your project structure, dependencies, and code patterns to build a comprehensive assessment. The `assessment.md` file lists breaking changes, API compatibility problems, deprecated patterns, and the upgrade scope. + +1. **Upgrade options** — Copilot presents strategy decisions for your review, such as the upgrade strategy (bottom-up, top-down, or all-at-once), project migration approach, technology modernization options, and compatibility handling. Confirmed decisions are saved to `upgrade-options.md`. + +1. **Planning** — Copilot converts the assessment and your confirmed options into a detailed specification. The `plan.md` file documents upgrade strategies, refactoring approaches, dependency paths, and risk mitigations. + +1. **Execution** — Copilot breaks the plan into sequential, concrete tasks with validation criteria in `tasks.md`. Each task describes a single change and how Copilot confirms it succeeded. + +Edit any of the Markdown files in `.github/upgrades/{scenarioId}` to adjust upgrade steps or add context before you move forward. + +### Upgrade strategies + +During the upgrade options phase, the agent evaluates your solution and recommends one of these strategies: + +| Strategy | Best for | Description | +|---|---|---| +| **Bottom-up** | Large solutions with deep dependency graphs | Upgrades leaf projects first, then works upward | +| **Top-down** | Quick feedback on the main application | Upgrades the application project first, then fixes dependencies | +| **All-at-once** | Small, simple solutions | Upgrades all projects in one pass | + +### Flow modes + +The agent supports two flow modes that control how much it pauses for your input: + +- **Automatic** — The agent works through all stages without pausing, stopping only at genuine blockers. Best for experienced users and straightforward upgrades. +- **Guided** — The agent pauses at each stage boundary so you can review the assessment, plan, and tasks before proceeding. Best for first-time users and complex solutions. + +Switch between modes at any time by saying "pause" (to enter guided mode) or "continue" (to enter automatic mode). + +### State management -- **Assessment stage (`assessment.md`)**\ -Copilot examines your project structure, dependencies, and code patterns to build a comprehensive assessment. The document lists breaking changes, API compatibility problems, deprecated patterns, and the upgrade scope so you know exactly what needs attention. +The agent stores all upgrade state in `.github/upgrades/{scenarioId}/`. This folder contains: -- **Planning stage (`plan.md`)**\ -Copilot converts the assessment into a detailed specification that explains how to resolve every problem. The plan documents upgrade strategies, refactoring approaches, dependency upgrade paths, and risk mitigations. +| File | Purpose | +|---|---| +| `assessment.md` | Analysis of your solution | +| `upgrade-options.md` | Confirmed upgrade decisions | +| `plan.md` | Ordered task plan | +| `tasks.md` | Live progress dashboard | +| `scenario-instructions.md` | Agent's persistent memory—preferences, decisions, and custom instructions | +| `execution-log.md` | Detailed audit trail of all changes | +| `tasks/{taskId}/task.md` | Per-task scope and context | +| `tasks/{taskId}/progress-details.md` | Per-task execution notes and results | -- **Execution stage (`tasks.md`)**\ -Copilot breaks the plan into sequential, concrete tasks with validation criteria. Each task describes a single change and how Copilot confirms it succeeded. +Because all state lives in this folder, you can close your IDE, switch between sessions, or even switch between development environments (for example, start in VS Code and continue in Visual Studio). The agent picks up where it left off. -Edit any of the Markdown files in `.github/upgrades` to adjust upgrade steps or add context before you move forward. +> [!TIP] +> Commit the `.github/upgrades/` folder to your branch. The committed state serves as a backup and lets team members view upgrade progress. ### Perform the upgrade -After each stage completes, review and modify the generated tasks as needed, and then tell Copilot to continue to the next stage. +After each phase completes, review and modify the generated files as needed, and then tell Copilot to continue to the next phase. -When you reach the **Execution stage**, tell Copilot to start the upgrade. If Copilot runs into a problem, it tries to identify the cause and apply a fix. If Copilot can't correct the problem, it asks for your help. When you intervene, Copilot learns from the changes you make and tries to automatically apply them if the problem comes up again. +When you reach the **Execution** phase, tell Copilot to start the upgrade. If Copilot runs into a problem, it tries to identify the cause and apply a fix. If Copilot can't correct the problem, it asks for your help. When you intervene, Copilot learns from the changes you make and tries to automatically apply them if the problem comes up again. ### Upgrade results -As Copilot runs each task, it updates the `tasks.md` file in `.github/upgrades` with the status of every step. Monitor progress by reviewing this file. The tool creates a Git commit for every portion of the process, so you can roll back changes or review what changed. +As Copilot runs each task, it updates the `tasks.md` file in `.github/upgrades/{scenarioId}` with the status of every step. Monitor progress by reviewing this file. The tool creates a Git commit for every portion of the process, so you can roll back changes or review what changed. When the upgrade finishes, Copilot displays next steps in the chat response. @@ -162,5 +225,9 @@ The tool collects data about project types, intent to upgrade, and upgrade durat - [Install GitHub Copilot modernization](install.md) - [Upgrade a .NET app with GitHub Copilot modernization](how-to-upgrade-with-github-copilot.md) +- [Core concepts](concepts.md) +- [Scenarios and skills reference](scenarios-and-skills.md) +- [Best practices](best-practices.md) +- [Troubleshoot GitHub Copilot modernization](troubleshooting.md) - [Quickstart: Migrate a .NET project](../../../azure/migration/appmod/quickstart.md) - [GitHub Copilot modernization FAQ](faq.yml) diff --git a/docs/core/porting/github-copilot-app-modernization/scenarios-and-skills.md b/docs/core/porting/github-copilot-app-modernization/scenarios-and-skills.md new file mode 100644 index 0000000000000..2aa4ca3c65066 --- /dev/null +++ b/docs/core/porting/github-copilot-app-modernization/scenarios-and-skills.md @@ -0,0 +1,226 @@ +--- +title: Scenarios and skills reference for GitHub Copilot modernization +description: "Complete reference of all scenarios and built-in migration skills available in GitHub Copilot modernization for .NET, organized by domain." +ms.topic: concept-article +ms.date: 04/06/2026 +ai-usage: ai-assisted + +#customer intent: As a developer, I want to see all the scenarios and skills that GitHub Copilot modernization supports so that I can understand which upgrade and migration tasks the agent can handle for me. + +--- + +# Scenarios and skills reference + +GitHub Copilot modernization for .NET helps you modernize through _scenarios_ and _skills_: + +- **Scenarios** are end-to-end managed workflows for major upgrade goals, such as upgrading from .NET Framework to .NET 10. Scenarios coordinate the full lifecycle: assessment, planning, and task-by-task execution. +- **Skills** are focused capabilities for specific migration tasks, such as converting EF6 to EF Core or replacing WCF with CoreWCF. Skills activate automatically when the agent encounters relevant code during an upgrade. + +Both C# and Visual Basic projects are supported. + +> [!TIP] +> You don't need to memorize names. Describe what you want—*"upgrade to .NET 10"*, *"migrate my EF6 code"*, *"replace Newtonsoft.Json"*—and the agent loads the right scenario and skills automatically. You can also ask: *"What can you help me with?"* + +## Scenarios + +Scenarios are the agent's top-level upgrade workflows. When you start a conversation, the agent identifies the best scenario for your goal and walks you through it step by step. + +| Scenario | What it does | Example prompt | +|---|---|---| +| [**.NET version upgrade**](#net-version-upgrade) | Upgrades projects from any older .NET version to .NET 8, 9, 10, or later | *"Upgrade my solution to .NET 10"* | +| [**Aspire integration**](#aspire-integration) | Adds .NET Aspire orchestration for inner-loop development and optional Azure deployment | *"Add Aspire to my solution"* | +| [**Aspire version upgrade**](#aspire-version-upgrade) | Upgrades existing Aspire projects to a newer Aspire version with code transforms and TFM updates | *"Upgrade my Aspire project to latest"* | +| [**SDK-style conversion**](#sdk-style-conversion) | Converts legacy project files to modern SDK-style format | *"Convert my projects to SDK-style"* | +| [**Newtonsoft.Json migration**](#newtonsoftjson-migration) | Replaces Newtonsoft.Json with System.Text.Json across a solution | *"Migrate from Newtonsoft.Json"* | +| [**SqlClient migration**](#sqlclient-migration) | Migrates System.Data.SqlClient to Microsoft.Data.SqlClient | *"Update SqlClient to the modern package"* | +| [**Azure Functions upgrade**](#azure-functions-upgrade) | Migrates Azure Functions from in-process to isolated worker model | *"Upgrade my Azure Functions"* | +| [**Semantic Kernel to Agents**](#semantic-kernel-to-agents) | Migrates from SK Agents to Microsoft Agents AI Framework | *"Migrate my SK agents"* | + +For a detailed walkthrough of how scenarios work end to end, see [Core concepts](concepts.md). + +### .NET version upgrade + +The most commonly used scenario. Upgrades your projects from any older .NET variant to the latest: + +| Source | Target | +|---|---| +| .NET Framework (any version) | .NET 8, 9, 10, or later | +| .NET Core 1.x, 2.x, 3.x | .NET 8, 9, 10, or later | +| .NET 5, 6, 7, 8, 9 | .NET 10 or later | + +The agent analyzes your dependency graph, checks NuGet compatibility, identifies breaking changes, and creates a task plan using the best strategy for your solution (bottom-up, top-down, or all-at-once). If your projects need format conversions, the agent handles them automatically as part of the upgrade. + +### Aspire integration + +Adds .NET Aspire orchestration to an existing solution. Works with any .NET project targeting `net8.0` or later, including desktop apps (WPF, WinForms, Avalonia, MAUI), web APIs, workers, and console applications. + +The agent: + +1. Scans your solution for compatible projects, infrastructure resources (databases, caches, message brokers), and inter-service communication. +1. Asks you to choose: inner-loop only (local development) or inner-loop and Azure deployment. +1. Lets you pick a file-based or project-based AppHost approach. +1. Generates the AppHost with all resources, projects, and wiring in one pass. +1. Validates everything works locally through the Aspire Dashboard. +1. (Optional) Configures Azure deployment through `aspire deploy`. + +### Aspire version upgrade + +Upgrades an existing Aspire project from its current version to a newer Aspire version. The agent handles the full upgrade lifecycle: + +1. Detects the current Aspire version from your AppHost SDK, packages, and configuration. +1. Determines the target version and required .NET TFM (for example, Aspire 13.x requires `net10.0`). +1. Auto-fixes breaking API changes across version transitions (type renames, method renames, argument reorders, fluent chain refactors). +1. Updates all Aspire packages and handles package renames (for example, `Aspire.Hosting.NodeJs` to `Aspire.Hosting.JavaScript`). +1. Consolidates AppHost SDK format and migrates config files to unified `aspire.config.json`. +1. Validates the upgraded solution builds and runs correctly. + +Supports upgrades from any Aspire version (8.x, 9.x, 13.0) to the latest, handling all intermediate breaking changes automatically. + +### SDK-style conversion + +Converts legacy `.csproj` and `.vbproj` files to the modern SDK-style format without changing target frameworks. The agent handles the conversion automatically when needed during version upgrades, but you can also run this scenario independently. + +### Newtonsoft.Json migration + +Replaces `Newtonsoft.Json` with `System.Text.Json` across your solution. Handles custom converters, `[JsonProperty]` attributes, `JObject`/`JArray` usage, and serialization settings. + +### SqlClient migration + +Migrates from `System.Data.SqlClient` to `Microsoft.Data.SqlClient`. Handles the `Encrypt=true` default behavior change and connection string differences. + +### Azure Functions upgrade + +Migrates Azure Functions from the in-process hosting model to the isolated worker model with `Program.cs` and `HostApplicationBuilder`. Includes Application Insights migration. + +### Semantic Kernel to Agents + +Migrates from Semantic Kernel Agents (`ChatCompletionAgent`, `OpenAIAssistantAgent`) to the Microsoft Agents AI Framework. Updates packages and API patterns. + +## Migration skills—common + +General-purpose migration skills that apply across project types. + +| Skill | What it does | +|---|---| +| **Converting to SDK-style** | Converts legacy project files to modern SDK-style format. Uses topological ordering for multi-project solutions. | +| **Migrating Autofac to .NET DI** | Removes Autofac entirely and migrates all registrations to built-in ASP.NET Core dependency injection. | +| **Integrating Autofac with .NET** | Keeps Autofac as the DI container but modernizes its ASP.NET Core integration. | +| **Migrating cryptography namespaces** | Fixes the `System.Security.Cryptography` namespace split for types like `X509Certificate2` and `SignedCms`. | +| **Migrating Newtonsoft to System.Text.Json** | Full migration from `Newtonsoft.Json`—handles converters, attributes, dynamic types, and settings. | +| **Migrating Semantic Kernel to Agents** | Migrates Semantic Kernel agent APIs to the Microsoft Agents AI Framework. | +| **Migrating to MSMQ.Messaging** | Migrates from `System.Messaging` (.NET Framework only) to `MSMQ.Messaging` for .NET Core. | +| **Converting to Central Package Management** | Converts per-project NuGet package versioning to centralized package management using `Directory.Packages.props`. | +| **Modernizing C# version** | Upgrades C# code to use newer language features (C# 7.0 through 15). Batches mechanical changes through `dotnet format` and uses LLM judgment for semantic transformations. | +| **Migrating C# nullable references** | Enables nullable reference types and systematically resolves all CS86xx warnings. Covers rollout strategies, annotation guidance, and framework-specific considerations. | + +## Migration skills—data access + +Skills for migrating data access layers, including Entity Framework, LINQ to SQL, and SQL client libraries. + +| Skill | What it does | +|---|---| +| **Migrating EDMX to Code-First** | Converts EF6 Database-First (`.edmx`) models to EF Core Code-First. Scaffolds entities from the database. | +| **Migrating EF DbContext** | Registers `DbContext` in ASP.NET Core dependency injection. Handles both EF6 to EF Core and existing EF Core patterns. | +| **Migrating EF6 Code-First to EF Core** | Upgrades EF6 Code-First to EF Core. Swaps packages, updates namespaces, and replaces `EntityTypeConfiguration` and `DbModelBuilder`. | +| **Migrating LINQ to SQL to EF Core** | Migrates `System.Data.Linq` to EF Core. Converts `DataContext` to `DbContext` and handles stored procedures. | +| **Migrating to Microsoft.Data.SqlClient** | Migrates from `System.Data.SqlClient`. Handles the `Encrypt=true` default change and connection string differences. | + +## Migration skills—web and ASP.NET + +Skills for migrating ASP.NET Framework applications to ASP.NET Core. + +### ASP.NET Framework migration + +| Skill | What it does | +|---|---| +| **Migrating ASP.NET Framework to Core** | Comprehensive migration from ASP.NET Framework (MVC/WebAPI) to ASP.NET Core, including controllers, views, middleware, authentication, and configuration. | +| **Migrating ASP.NET Identity** | Migrates ASP.NET MVC Identity to ASP.NET Core Identity—`IdentityDbContext`, `UserManager`, `SignInManager`, and auth middleware. | +| **Migrating Global.asax** | Converts `Global.asax` lifecycle events (`Application_Start`, `Application_Error`) to ASP.NET Core `Program.cs` and middleware. | +| **Migrating OWIN to middleware** | Replaces OWIN/Katana middleware (`IAppBuilder`, `OwinMiddleware`) with ASP.NET Core equivalents. | +| **Migrating OWIN Cookie Authentication** | Migrates OWIN cookie authentication middleware to ASP.NET Core cookie authentication. | +| **Migrating OWIN OAuth to JWT** | Migrates OWIN OAuth bearer token authentication to ASP.NET Core JWT bearer authentication. | +| **Migrating OWIN OpenID Connect** | Migrates OWIN OpenID Connect middleware to ASP.NET Core OpenID Connect authentication. | + +### MVC features + +| Skill | What it does | +|---|---| +| **Migrating MVC authentication** | Migrates ASP.NET MVC authentication to ASP.NET Core Identity and authentication middleware. | +| **Migrating MVC bundling** | Converts `System.Web.Optimization` bundling to direct `