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..2e1632ddd93ab --- /dev/null +++ b/docs/core/porting/github-copilot-app-modernization/best-practices.md @@ -0,0 +1,230 @@ +--- +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 + +Prepare your projects before starting an upgrade to get the best results. + +### Verify that your solution builds and tests pass + +The agent validates changes 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. + +Document any known test failures 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. If so, back up your project folder before starting so you can restore it if needed. + +Consider initializing a local Git repository before starting the upgrade, even if you don't push to a cloud provider. A local Git repository lets you: + +- Roll back individual changes with `git revert`. +- Track upgrade progress step by step in the commit history. +- Control which changes to keep or discard. +- Keep your original code safe on the main branch while the agent works on a separate branch. + +```console +cd your-project-folder +git init +git add . +git commit -m "Baseline before upgrade" +``` + +### 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 code the upgrade is most likely to change, such as 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 + +Follow these guidelines while the agent works through your 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 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`. You can also edit `assessment.md` directly to add context, correct misidentified projects, or flag concerns before the agent proceeds to planning. + +### Take time with the planning stage + +The agent generates a 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? + +Ask the agent to reorder tasks, skip projects, or change its approach. You know your codebase better than the agent, so use that knowledge. Edit the `plan.md` file directly to adjust task order, add tasks, or remove tasks. + +> [!CAUTION] +> Be careful when editing `plan.md` directly. The agent might not fully interpret your changes if they create contradictory instructions. For example, removing a dependency project while keeping the projects that depend on it. + +### 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. + +### Stay engaged during execution + +Execution isn't hands-off. Before telling the agent to start, review `tasks.md`: + +- Does the task order make sense for your codebase? +- Are there tasks you want to skip or resequence? +- Are any tasks missing? + +Ask the agent to adjust the task list, or edit `tasks.md` directly before execution begins. Once execution starts, if the agent makes a bad call mid-task, tell it immediately — it applies your correction going forward. + +You know your codebase better than the agent, so use that knowledge at every stage. + +## Common pitfalls + +Watch for these common issues that can slow down or complicate an upgrade. + +### 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. A single-project pilot 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, such as 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 it 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 + +The quality of your interaction directly affects the quality of the results. + +### 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, so 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 + +Use these strategies when the upgrade doesn't go as expected. + +### 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 your fix. +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 stage: + +- _"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, or stop the session manually. 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**: GitHub Copilot processes these according to [GitHub's Copilot privacy policy](https://docs.github.com/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-your-ide) and doesn't retain them beyond the immediate session. +- **Workflow files** (`scenario-instructions.md`, custom tasks, preferences) stay in your repository under `.github/upgrades/`. GitHub doesn't transmit these files to external services. +- **The `.github/upgrades/` folder** is part of your repository. Commit the folder because 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**: Disable 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..fec6e6b7c7b28 --- /dev/null +++ b/docs/core/porting/github-copilot-app-modernization/concepts.md @@ -0,0 +1,214 @@ +--- +title: GitHub Copilot modernization core concepts +description: "Learn the key concepts behind GitHub Copilot modernization, including scenarios, skills, tasks, the three-stage 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, including 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 excels at 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, including 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}/`. The scenario 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 lifecycle: a three-stage workflow. + +### Stage 1: Assessment + +The agent gathers everything it needs before starting work: + +- **Target framework:** The 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 stage). +- **Scenario-specific parameters:** Depending on the scenario, the agent might ask more questions. + +The agent initializes the scenario workspace at `.github/upgrades/{scenarioId}/`. + +The agent then 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 agent saves a comprehensive assessment report to `assessment.md`. + +Based on the assessment, 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. + +The agent saves confirmed decisions to `upgrade-options.md`. + +In **Guided mode**, the agent pauses here for your review before proceeding. + +### Stage 2: Planning + +The agent creates the task plan based on the assessment and your confirmed options. 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` — The ordered list of tasks the agent will execute. + +### Stage 3: Execution + +The agent works through tasks sequentially. For each task in `tasks.md`, the agent follows a cycle: start, execute, validate (build and test), and complete. You control when and how the agent commits changes: per task, per group of tasks, or at the end. As the agent works, it updates `tasks.md` with live status indicators so you can track progress. + +## Upgrade strategies + +During the assessment stage, 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 smaller, targeted modernization capabilities. When the agent encounters EF6 code during an upgrade, it loads the EF6-to-EF-Core skill with detailed, step-by-step migration instructions. Invoke a skill directly during an upgrade: _"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, and SqlClient migration +- **Web/ASP.NET:** Identity, Global.asax, OWIN, MVC routing/filters/bundling, and 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. The agent reloads your preferences from `scenario-instructions.md`. + +### Cross-IDE continuity + +Because state lives in Git, you can switch between VS Code, Visual Studio, and Copilot CLI mid-upgrade. The `.github/upgrades/` folder is the shared state that both IDEs understand. + +> [!TIP] +> Commit the `.github/upgrades/` folder to your branch. Push the branch to a remote repository to let team members view progress or 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 stages (assessment, planning, and 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 stage boundary for your review: + +- After assessment: _"Here's what I found. Shall I proceed with upgrade options?"_ +- 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/customization.md b/docs/core/porting/github-copilot-app-modernization/customization.md new file mode 100644 index 0000000000000..d9cc4ebca6745 --- /dev/null +++ b/docs/core/porting/github-copilot-app-modernization/customization.md @@ -0,0 +1,304 @@ +--- +title: Customize GitHub Copilot modernization +description: "Learn how to customize GitHub Copilot modernization with custom skills, custom scenarios, scenario artifact edits, and chat instructions to encode your team's migration patterns." +ms.topic: concept-article +ms.date: 04/06/2026 +ai-usage: ai-assisted + +#customer intent: As a developer, I want to customize GitHub Copilot modernization so that I can encode my team's migration patterns, enforce coding standards during upgrades, and define custom upgrade workflows. + +--- + +# Customize GitHub Copilot modernization + +GitHub Copilot modernization is extensible. The agent provides multiple customization points to encode your team's migration patterns, enforce coding standards during upgrades, and define new upgrade workflows. + +## Customization points overview + +| Customization point | Scope | Persistence | Effort | +|---|---|---|---| +| **Chat instructions** | Per session or upgrade | Session or saved to `scenario-instructions.md` | Minimal | +| **Scenario artifacts** | Per upgrade | Duration of upgrade | Low | +| **Custom skills** | Team or personal | Permanent (checked into repo or user profile) | Medium | +| **Custom scenarios** | Team or personal | Permanent | High | + +> [!TIP] +> Start with chat instructions and scenario artifact edits. Move to custom skills when you find yourself repeating the same instructions across upgrades. + +## Customize through chat + +Customize the agent's behavior in real time through natural conversation. The agent either applies your instruction immediately or persists it to `scenario-instructions.md` for future reference. + +| You say | What happens | +|---|---| +| _"From now on, always commit after each task"_ | Saved to `scenario-instructions.md` as an execution preference | +| _"Skip test validation for this task"_ | Applied immediately to the current task only | +| _"Use the bottom-up strategy for this upgrade"_ | Affects the planning phase strategy | +| _"Don't touch the Logging project"_ | Added to preferences; agent excludes that project | +| _"Always use file-scoped namespaces"_ | Saved as a coding standard preference | +| _"Pause after each task for my review"_ | Saved as an execution style preference | + +> [!TIP] +> To make an instruction persist across the entire upgrade, phrase it as a permanent preference: _"From now on, always..."_ or _"For all tasks in this upgrade..."_. The agent writes the instruction to `scenario-instructions.md`. + +## Edit scenario artifacts + +When the agent runs an upgrade, it creates a workspace in `.github/upgrades/{scenarioId}/`. The upgrade folder contains editable artifacts that directly control the agent's behavior. + +### scenario-instructions.md + +The `scenario-instructions.md` file is the agent's persistent memory for the upgrade. The agent always loads this file into context, so anything you write here directly influences every decision the agent makes. + +Add sections like these to guide the agent: + +```markdown +## User Preferences + +### Technical Preferences +- Always prefer explicit type declarations over `var` +- Use `ILogger` instead of `ILoggerFactory` for dependency injection +- Target .NET 10 for all projects +- Keep Newtonsoft.Json in the shared library (don't migrate to System.Text.Json) + +### Execution Style +- **Pace**: Methodical +- **Pause Points**: After assessment, after each task group + +### Custom Instructions + +#### 02-common-lib +- Skip the database migration for now — it has external dependencies +- Use the connection string from `appsettings.Production.json` for testing + +#### 03-data-layer +- Keep existing repository interfaces during migration +- Preserve all Entity Framework conventions + +## Key Decisions Log +- 2025-01-15: Keep Newtonsoft.Json in SharedLib — third-party SDK requires it +- 2025-01-16: Skip database project — DBA team will handle separately +``` + +### plan.md + +The `plan.md` file defines the tasks and their scope. Edit `plan.md` to: + +- Reorder tasks to change the execution sequence. +- Add tasks the agent didn't plan for. +- Remove tasks that don't apply. +- Add notes to provide context for specific tasks. + +### Individual task files + +Each task in `tasks/{taskId}/task.md` contains the task specification and working notes. Edit these files to: + +- Refine a task's scope. +- Add domain-specific context the agent missed. +- Provide code examples for the desired outcome. + +> [!IMPORTANT] +> The agent's tools manage `tasks.md` as a read-only dashboard. Don't edit `tasks.md` directly. The agent overwrites any manual changes. Edit `scenario-instructions.md` or individual `task.md` files instead. + +## Create custom skills + +Skills are the primary extension point for the agent. A skill is a Markdown file with a metadata header that teaches the agent how to handle a specific migration, pattern, or task. + +### Where to place custom skills + +| Location | Scope | Use when | +|---|---|---| +| `.github/skills/my-skill.md` | Repository (shared with team) | Team-wide migration patterns | +| `.github/upgrades/skills/my-skill.md` | Repository (upgrade-specific) | Skills specific to upgrade scenarios | +| `%UserProfile%/.copilot/skills/my-skill.md` | User profile (personal, all repos) | Personal preferences and patterns | + +> [!TIP] +> Repository-level skills (`.github/skills/`) are the most common choice. They travel with the code, and the entire team can use them. + +### Skill file structure + +Every skill file has two parts: a metadata header (which the agent uses to understand when the skill applies) and a Markdown body (instructions the agent follows). + +```yaml +--- +name: migrating-foobar-v2-to-v3 +description: > + Migrate our internal FooBar library from v2 to v3. Activates when + FooBar.v2 NuGet package is detected, or when asked to "upgrade FooBar", + "migrate FooBar", or "update FooBar library". +metadata: + discovery: lazy + traits: .NET | CSharp +--- + +# Migrating FooBar Library v2 to v3 + +## Overview + +FooBar v3 introduces a new async-first API surface. This skill guides the +agent through replacing synchronous FooBar.v2 calls with their v3 async +equivalents, updating configuration, and verifying behavior. + +## Workflow + +1. **Identify FooBar.v2 references** + - Search for `PackageReference` elements referencing `FooBar.v2` + - Locate all `using FooBar.V2;` directives + +2. **Update package references** + - Replace `FooBar.v2` with `FooBar.v3` in all `.csproj` files + - Run `dotnet restore` to verify resolution + +3. **Migrate API calls** + - Replace `FooBarClient.Send(...)` with `await FooBarClient.SendAsync(...)` + - Replace `FooBarConfig.LoadFromFile(...)` with `FooBarConfig.LoadFromJsonAsync(...)` + - Update method signatures to `async Task` where needed + +4. **Update configuration** + - Rename `foobar.config` to `foobar.json` + - Migrate XML config entries to JSON format + +5. **Verify** + - Build the project: `dotnet build` + - Run existing tests: `dotnet test` + - Verify no remaining references to `FooBar.V2` namespace + +## Success Criteria + +- [ ] No references to `FooBar.v2` NuGet package remain +- [ ] All `FooBar.V2` namespace usages replaced with `FooBar.V3` +- [ ] Project builds without errors +- [ ] All existing tests pass + +## Error Handling + +- If `FooBar.v3` is not available in the configured NuGet feeds, instruct + the user to add the internal feed +- If async migration causes deadlocks in legacy synchronous code paths, + wrap calls with `.GetAwaiter().GetResult()` and add a TODO comment +``` + +### Metadata fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | Unique identifier in kebab-case. Start with a gerund verb (for example, `migrating-`, `converting-`). Maximum 64 characters. | +| `description` | Yes | Determines when the agent loads the skill. Include trigger phrases, such as words and patterns that should activate the skill. | +| `metadata.discovery` | No | Controls when the skill loads: `preload` (always available), `lazy` (on-demand when description matches, default and recommended), or `scenario` (defines a workflow orchestrator). | +| `metadata.traits` | No | Keywords describing the technologies in your project, such as `.NET`, `CSharp`, `VisualBasic`, or `DotNetCore`. | + +### Skill authoring best practices + +- **Be specific in the description:** Include exact package names, library names, and natural-language trigger phrases users might type. +- **Include clear, step-by-step workflows:** Number the steps. Be explicit about what files to change and what commands to run. +- **Include success criteria:** Without success criteria, the agent doesn't know when to stop. Use checkboxes or a clear list of verifiable conditions. +- **Include error handling:** Anticipate common failure modes, such as missing packages, build failures, or broken tests. +- **Keep skills focused:** One skill per migration or task type. A skill for "migrating FooBar v2 to v3" is better than "migrating all internal libraries." +- **Name with a gerund verb:** Use `migrating-foobar-v2-to-v3`, not `foobar-migration` or `foobar-v3`. +- **Use `lazy` discovery:** Use `lazy` discovery for most custom skills to avoid bloating the agent's context window. + +## Create custom scenarios + +For advanced users who want to define entirely new upgrade workflows, custom scenarios let you orchestrate a full multi-phase upgrade pipeline. A scenario is a skill with `metadata.discovery: scenario` that defines the phases the agent follows. + +```yaml +--- +name: migrating-soap-to-rest-api +description: > + Migrate legacy WCF/SOAP services to ASP.NET Core REST APIs. Activates + when WCF service references, .svc files, or SOAP clients are detected, + or when asked to "migrate SOAP to REST", "replace WCF", or "convert + web services to REST". +metadata: + discovery: scenario + traits: .NET | CSharp + scenarioTraitsSet: [wcf, soap, web-services] +--- + +# SOAP to REST API Migration + +## Pre-initialization + +Gather from the user: +- Which SOAP services to migrate (all or specific ones) +- Whether to maintain backward compatibility with a SOAP facade +- Authentication mechanism for the new REST APIs +- API versioning strategy (URL path, header, query string) + +## Assessment + +Analyze the solution for: +- `.svc` files and WCF service contracts +- WSDL files and service references +- `System.ServiceModel` usage and binding configurations +- Data contracts and their serialization requirements +- Client proxies consuming SOAP services + +## Planning + +Create tasks in this order: +1. Create shared DTOs — Convert `[DataContract]` types to POCOs +2. Create REST controllers — One controller per `[ServiceContract]` +3. Map operations to HTTP methods +4. Migrate service implementations +5. Update clients — Replace `ChannelFactory`/generated proxies with `HttpClient` +6. Remove WCF infrastructure +7. Add API documentation — Swagger/OpenAPI via Swashbuckle + +## Execution + +For each service contract: +1. Create a corresponding controller +2. Create a service interface and implementation +3. Register the service in DI +4. Map WCF operations to REST endpoints +5. Update any in-solution clients to use the new REST endpoints +6. Build and run existing tests +``` + +Place scenario files in `.github/skills/` or `.github/upgrades/skills/` for the agent to discover them. + +> [!TIP] +> The `scenarioTraitsSet` field defines traits that the agent uses to match your scenario against the solution's characteristics. These traits help the agent suggest your scenario when appropriate. + +## Source control and branching + +The agent offers to work on a Git branch, but you have full control over the strategy: + +- **Branch naming:** Tell the agent what branch name to use, or let the agent suggest one. +- **Per-task branches:** Request a separate branch per task for granular review. +- **Commit timing:** Choose when the agent commits: after every completed task (default), only at the end of the full upgrade, or on demand. +- **No source control:** The agent also works with non-Git folders but recommends backing up your project first. + +Example chat instructions: + +- _"Use branch name 'upgrade/dotnet10' for this upgrade"_ +- _"Create a branch per task so I can review each one separately"_ +- _"Don't commit until I explicitly ask you to"_ +- _"Commit after every task with a descriptive message"_ + +> [!TIP] +> For large multi-project upgrades, per-task branches give you flexibility to review and merge each change independently, or roll back a single task without affecting the rest. + +## Skill loading priority + +When the agent discovers multiple skills, it resolves them using a priority system. Higher-priority sources override or supplement lower-priority ones: + +| Priority | Source | Location | +|---|---|---| +| 5 (highest) | Custom skills (user-provided through API) | — | +| 4 | User profile skills | `%UserProfile%/.copilot/skills/` | +| 3 | Repository upgrade skills | `.github/upgrades/skills/` | +| 2 | Repository skills | `.github/skills/` | +| 1 (lowest) | Embedded skills (built into the agent) | — | + +The agent collects skills from all sources. When skills have overlapping scope, higher-priority sources take precedence. The `discovery` field controls when the skill loads. `lazy` means on demand when relevant, and `preload` means always available. + +> [!TIP] +> You don't need to replace a built-in skill to change behavior. A higher-priority repository skill supplements the built-in skill, adding your team's specific conventions on top of the baseline behavior. + +## Related content + +- [Core concepts](concepts.md) +- [Scenarios and skills reference](scenarios-and-skills.md) +- [Apply custom upgrade instructions](how-to-custom-upgrade-instructions.md) +- [Best practices](best-practices.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..bda6f6d9cef37 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 modernization 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-custom-upgrade-instructions.md b/docs/core/porting/github-copilot-app-modernization/how-to-custom-upgrade-instructions.md index 98dde134799e0..382935a974650 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 @@ -22,7 +22,7 @@ Set up GitHub Copilot modernization in your development environment before creat ## Understand custom upgrade instructions -GitHub Copilot 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: +GitHub Copilot modernization retrieves custom upgrade instructions as Markdown files on demand during the assessment and planning stages of an upgrade. Custom upgrade instructions differ from `copilot-instructions.md` because they're: - Targeted to automating code and dependency changes. - Retrieved only when relevant to the current upgrade assessment or plan. @@ -32,10 +32,10 @@ Structure your instruction files with: - A short title describing the action. For example, "replace Newtonsoft.Json with System.Text.Json." - A concise problem statement or prerequisite section. -- Explicit step logic ("If X is found, do Y")—avoid vague language. +- Explicit step logic ("If X is found, do Y"). Avoid vague language. - (Recommended) One or more diff examples captured from actual local edits to guide transformations. -Beyond custom upgrade instructions, GitHub Copilot modernization is extensible through the standard skills and instructions system that your development environment and Copilot support. Skills let you extend the agent with extra capabilities, and instruction files (like `copilot-instructions.md`) provide global guidance to the agent. +Beyond custom upgrade instructions, you can extend GitHub Copilot modernization through the standard skills and instructions system. Skills add capabilities to the agent, and instruction files (like `copilot-instructions.md`) provide global guidance. ## Create a custom upgrade instruction @@ -52,7 +52,7 @@ Follow these steps to generate and refine a new instruction file. These sections 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. 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. 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."_ > [!TIP] > Add the file to the solution for visibility if it isn't already included. @@ -61,7 +61,7 @@ Follow these steps to generate and refine a new instruction file. These sections 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. + 1. Confirm Copilot used a git diff and appended a fenced diff block or structured example to the Markdown file. ### Authoring tips @@ -69,12 +69,12 @@ Follow these guidelines to write clear, effective custom upgrade instructions th - 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. -- Improve transformation accuracy by providing at least one concrete example, such as a diff or before/after snippet. +- Provide at least one concrete example, such as a diff or before/after snippet, to improve transformation accuracy. - 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, validate it in isolation. This fast inner loop helps you refine detection and verify the code changes. +Before running the instruction during an upgrade, validate it in isolation. Isolated testing helps you refine detection and verify code changes. 1. In the **Solution Explorer** window, right-click the **solution** > **Modernize**. @@ -90,7 +90,7 @@ Before running the instruction during an upgrade, validate it in isolation. This 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 with keywords from the file's name, such as the same verb and noun combinations. + If Copilot doesn't indicate it found the instructions, retry with keywords 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 confirm the custom upgrade instruction behaves as expected. @@ -99,8 +99,8 @@ Before running the instruction during an upgrade, validate it in isolation. This 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 replacing the package, 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. +- Use consistent naming so that natural-language activation matches. For example, start the file name with `replace_` and begin your chat request with "Replace ...". +- During testing, add any missing code patterns as examples to improve coverage. ## Apply custom instructions during an upgrade @@ -112,11 +112,11 @@ Use these steps to incorporate an existing custom upgrade instruction into the a > These steps apply to Visual Studio. In Visual Studio Code and other environments, invoke the `modernize-dotnet` agent directly from the Copilot chat panel. 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. Look for a message indicating it opened the markdown instruction file. +1. Monitor the chat to see if Copilot automatically retrieves your custom instruction file during the assessment. Look for a message indicating it opened the Markdown instruction file. If Copilot doesn't automatically apply the custom instructions, 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`. -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. Wait for Copilot to confirm it retrieved the Markdown 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 that your custom instruction identified. For example, when replacing Newtonsoft, the assessment identifies: @@ -136,7 +136,7 @@ How you name and invoke custom upgrade instructions affects whether Copilot retr - 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." +- Avoid ambiguous requests like _"improve the assessment."_ Be explicit: "apply the replace_newtonsoft_with_system_text_json instructions during assessment." ## Validate the applied changes @@ -149,7 +149,7 @@ After the upgrade completes: ## Clean up resources -If you create temporary instruction files for experimentation, remove or consolidate them to avoid overlapping transformations in future upgrades. +Remove or consolidate any temporary instruction files to avoid overlapping transformations in future upgrades. ## Related content 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..afbabed6457af 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,8 +1,8 @@ --- 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 assessment and the three-stage workflow: assessment, 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. @@ -11,9 +11,9 @@ ai-usage: ai-assisted # 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 walks you through upgrading your .NET applications with a structured three-stage workflow: assessment, 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 stage, and helps with code fixes throughout the process. The agent supports upgrading from older .NET versions to the latest, including migrations from .NET Framework to modern .NET. ## Prerequisites @@ -25,19 +25,19 @@ 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 assesses your project and runs a three-stage workflow, writing Markdown files for each stage under `.github/upgrades/{scenarioId}` in your repository. The `{scenarioId}` value 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: -- **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 stage.** Copilot examines your project, presents strategy decisions for your review, and saves confirmed decisions. Customize the assessment before proceeding. +- **Planning stage.** Copilot creates a detailed specification with the steps to reach the target upgrade. +- **Execution stage.** Copilot breaks the plan into sequential tasks and performs the upgrade. -## Start assessment and review results +## Review the assessment -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 examines your project structure, dependencies, and code patterns to identify what needs to change. Copilot automatically starts the assessment 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: +The assessment lists breaking changes, API compatibility problems, deprecated patterns, and 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: ```markdown # Projects and dependencies analysis @@ -72,12 +72,26 @@ 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. Add project-specific context or concerns to the document. +1. Tell Copilot to _proceed to the planning stage._ + +## 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 stage._ ## 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 stage 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: @@ -118,18 +132,18 @@ To review and customize the plan: 1. Open the `plan.md` file in `.github/upgrades/{scenarioId}`. 1. Review the upgrade strategies and dependency updates. -1. Edit the plan to adjust upgrade steps or add context if needed. +1. Edit the plan to adjust upgrade steps or add context as needed. > [!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. + > The plan depends on project interdependencies. The upgrade doesn't succeed if you modify the plan in a way that prevents the migration path from completing. 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 stage._ ## 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 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: +The task list describes each task and how Copilot validates success. The following example shows a task list for a solution containing ASP.NET Core and WPF projects: ```markdown # MvcMovieNet6 .NET 10 Upgrade Tasks @@ -180,7 +194,7 @@ This document tracks the execution of the MvcMovieNet6 solution upgrade from .NE To run the upgrade: -1. Tell Copilot to start 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. Based on your decisions and changes, Copilot adapts its strategy to the remaining tasks and continues the upgrade. @@ -227,4 +241,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/includes/how-to-initiate.md b/docs/core/porting/github-copilot-app-modernization/includes/how-to-initiate.md index ea5629de56c29..9d6352b16e534 100644 --- a/docs/core/porting/github-copilot-app-modernization/includes/how-to-initiate.md +++ b/docs/core/porting/github-copilot-app-modernization/includes/how-to-initiate.md @@ -6,9 +6,9 @@ ms.topic: include --- 1. Open your .NET project or solution in your development environment. -1. Start the agent using one of these methods: +1. Start the agent by using one of these methods: - - **Visual Studio**: Right-click the solution or project in **Solution Explorer** and select **Modernize**. Or open the **GitHub Copilot Chat** window and type `@Modernize`. + - **Visual Studio**: Right-click the solution or project in **Solution Explorer** and select **Modernize**. Or, open the **GitHub Copilot Chat** window and type `@Modernize`. - **Visual Studio Code**: Open the **GitHub Copilot Chat** panel and type `@modernize-dotnet`. - **GitHub Copilot CLI**: Type `@modernize-dotnet` followed by your upgrade or migration request. - **GitHub.com**: Use the `modernize-dotnet` coding agent in your repository. diff --git a/docs/core/porting/github-copilot-app-modernization/index.yml b/docs/core/porting/github-copilot-app-modernization/index.yml index bd59324058d47..c109ff1721a71 100644 --- a/docs/core/porting/github-copilot-app-modernization/index.yml +++ b/docs/core/porting/github-copilot-app-modernization/index.yml @@ -19,6 +19,14 @@ landingContent: url: overview.md - text: Install url: install.md + - text: Core concepts + url: concepts.md + - text: Working with the agent + url: working-with-agent.md + - text: Scenarios and skills reference + url: scenarios-and-skills.md + - text: Customization + url: customization.md - text: FAQ url: faq.yml - linkListType: how-to-guide @@ -27,6 +35,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..f55f2c71405e9 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 @@ -12,24 +12,24 @@ zone_pivot_groups: copilot-modernization-install # Install GitHub Copilot modernization -GitHub Copilot modernization is available across multiple development environments. Choose your preferred environment to get started with installation and setup. +GitHub Copilot modernization works across multiple development environments. Choose your preferred environment to install and set up GitHub Copilot modernization. ::: zone pivot="visualstudio" ## Prerequisites -Before you install, make sure you have the following: +Before you install, make sure you have: - Windows operating system. - [Visual Studio 2026](https://visualstudio.microsoft.com/downloads/) (or Visual Studio 2022 version 17.14.17+). - [.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 -GitHub Copilot modernization is included in Visual Studio and doesn't require a separate installation. Enable the **GitHub Copilot** and **GitHub Copilot modernization** optional components in the **.NET desktop development** workload through the Visual Studio Installer. +Visual Studio includes GitHub Copilot modernization, so you don't need to install it separately. Enable the **GitHub Copilot** and **GitHub Copilot modernization** optional components in the **.NET desktop development** workload through the Visual Studio Installer. ## Verify the installation @@ -42,7 +42,7 @@ GitHub Copilot modernization is included in Visual Studio and doesn't require a ## Prerequisites -Before you install, make sure you have the following: +Before you install, make sure you have: - Visual Studio Code. - GitHub Copilot extension installed. @@ -50,12 +50,16 @@ 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 1. Open a project in Visual Studio Code. -1. Open the Copilot chat and type `@modernize-dotnet`. +1. Open **GitHub Copilot Chat** and type `@modernize-dotnet`. ::: zone-end @@ -63,14 +67,14 @@ Install the [GitHub Copilot modernization extension](https://marketplace.visuals ## Prerequisites -Before you install, make sure you have the following: +Before you install, make sure you have: - GitHub Copilot CLI installed. - GitHub Copilot subscription (paid or free). ## Install -Complete these three steps to install: +To install: 1. Open the GitHub Copilot chat window. @@ -96,7 +100,7 @@ Run `/agent` to confirm that `modernize-dotnet` appears in the agent list. ## Prerequisites -Before you install, make sure you have the following: +Before you install, make sure you have: - GitHub Copilot Enterprise or Business subscription with coding agents enabled. - Repository admin access. @@ -105,12 +109,12 @@ Before you install, make sure you have the following: Add the custom coding agent to your repository: -1. Learn about [adding custom coding agents to your repo](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents). +1. Review [adding custom coding agents to your repository](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents). 1. Add the `modernize-dotnet` agent. See the [coding agent README](https://github.com/dotnet/modernize-dotnet/blob/main/coding-agent/README.md) for details. ## Verify the installation -The `modernize-dotnet` agent appears as an available coding agent in your repository. +Confirm that the `modernize-dotnet` agent appears as an available coding agent in your repository. ::: zone-end @@ -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..b03509238efcc 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. Leave feedback using either of these options: - 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 @@ -109,15 +132,15 @@ GitHub Copilot modernization for .NET offers predefined tasks that capture indus - **Migrate to Azure Communication Service email** - Replace direct SMTP email sending by using Azure Communication Service for scalable, secure email delivery. + Replace direct SMTP email sending with Azure Communication Service for scalable, secure email delivery. - **Migrate to Confluent Cloud/Azure Event Hub for Apache Kafka** - Transition from local or on-premises Kafka to managed event streaming by using Confluent Cloud or Azure Event Hubs. + Transition from local or on-premises Kafka to managed event streaming with Confluent Cloud or Azure Event Hubs. - **Migrate to OpenTelemetry on Azure** - Transition from local logging frameworks like log4net, serilog, and Windows event log to OpenTelemetry on Azure. + Transition from local logging frameworks such as log4net, Serilog, and Windows event log to OpenTelemetry on Azure. - **Migrate to Azure Cache for Redis by using Managed Identity** @@ -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 assesses your project and runs a three-stage workflow. Each stage 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. + +Copilot starts by examining 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. + +After the assessment, Copilot runs the following three stages: + +1. **Assessment:** Copilot examines your project structure, dependencies, and code patterns, then 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. Copilot saves confirmed decisions 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 assessment stage, 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}/`. The 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, including 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 stage completes, review and modify the generated files as needed, and then tell Copilot to continue to the next stage. -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** 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. ### 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. Copilot 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..2ad5e8959b5af --- /dev/null +++ b/docs/core/porting/github-copilot-app-modernization/scenarios-and-skills.md @@ -0,0 +1,226 @@ +--- +title: GitHub Copilot modernization scenarios and skills +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. + +The agent supports both C# and Visual Basic projects. + +> [!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 an end-to-end walkthrough, see [Core concepts](concepts.md). + +### .NET version upgrade + +The most common 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 to a newer 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, and 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 during version upgrades. Run this scenario independently if needed. + +### 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, including `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 `