diff --git a/docs/core/porting/github-copilot-app-modernization/best-practices.md b/docs/core/porting/github-copilot-app-modernization/best-practices.md index 2e1632ddd93ab..4607b10e7d8bb 100644 --- a/docs/core/porting/github-copilot-app-modernization/best-practices.md +++ b/docs/core/porting/github-copilot-app-modernization/best-practices.md @@ -11,7 +11,7 @@ ai-usage: ai-assisted # Best practices for GitHub Copilot modernization -Follow these guidelines to get the best results from GitHub Copilot modernization when upgrading and migrating .NET projects. +Follow these guidelines to get the best results from GitHub Copilot modernization when upgrading .NET projects. ## Before you start @@ -77,7 +77,7 @@ The assessment is your best opportunity to catch issues before the agent starts - 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. +If you spot something, tell the agent in chat or add the information to `scenario-instructions.md`. 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 @@ -107,7 +107,7 @@ Execution isn't hands-off. Before telling the agent to start, review `tasks.md`: - 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. +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. @@ -143,7 +143,7 @@ The more specific you are, the better the agent performs: |---|---| | _"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"_ | +| _"Upgrade the database stuff"_ | _"Upgrade Entity Framework 6 to EF Core in the Repository project"_ | ### Share your constraints diff --git a/docs/core/porting/github-copilot-app-modernization/concepts.md b/docs/core/porting/github-copilot-app-modernization/concepts.md index caf0a1dda39bf..db536c222c65f 100644 --- a/docs/core/porting/github-copilot-app-modernization/concepts.md +++ b/docs/core/porting/github-copilot-app-modernization/concepts.md @@ -11,7 +11,7 @@ ai-usage: ai-assisted # 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. +GitHub Copilot modernization uses a structured approach to upgrade .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. @@ -20,7 +20,7 @@ GitHub Copilot modernization uses a structured approach to upgrade and migrate . 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. +- **Deep .NET knowledge:** The agent understands project files, NuGet dependencies, breaking changes, and upgrade 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. @@ -76,8 +76,8 @@ Based on the assessment, the agent evaluates your solution and identifies which 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. +- **Project upgrade approach:** In-place rewrite or side-by-side for web applications; in-place or multi-targeting for libraries. +- **Technology modernization:** Choices for Entity Framework upgrade, dependency injection, logging, and configuration. - **Package management:** Whether and when to adopt Central Package Management. - **Compatibility handling:** How to address unsupported APIs and packages. @@ -108,15 +108,15 @@ During the assessment stage, the agent evaluates your solution and recommends on | **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. +> 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 upgrade 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."_ +_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 upgrade instructions. Invoke a skill directly during an upgrade: _"upgrade 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 +- **Data access:** EF6 to EF Core (code-first and EDMX), LINQ to SQL, and SqlClient upgrade - **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 @@ -128,7 +128,7 @@ For the complete list, see [Scenarios and skills reference](scenarios-and-skills ## 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." +_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 "Upgrade EF6 usage in DataLayer to EF Core." ### Task lifecycle diff --git a/docs/core/porting/github-copilot-app-modernization/customization.md b/docs/core/porting/github-copilot-app-modernization/customization.md index d9cc4ebca6745..7a679fb353b4e 100644 --- a/docs/core/porting/github-copilot-app-modernization/customization.md +++ b/docs/core/porting/github-copilot-app-modernization/customization.md @@ -1,17 +1,17 @@ --- 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." +description: "Learn how to customize GitHub Copilot modernization with custom skills, custom scenarios, scenario artifact edits, and chat instructions to encode your team's upgrade 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. +#customer intent: As a developer, I want to customize GitHub Copilot modernization so that I can encode my team's upgrade 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. +GitHub Copilot modernization is extensible. The agent provides multiple customization points to encode your team's upgrade patterns, enforce coding standards during upgrades, and define new upgrade workflows. ## Customization points overview @@ -101,13 +101,13 @@ Each task in `tasks/{taskId}/task.md` contains the task specification and workin ## 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. +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 upgrade, 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/skills/my-skill.md` | Repository (shared with team) | Team-wide upgrade 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 | @@ -181,7 +181,7 @@ equivalents, updating configuration, and verifying behavior. | Field | Required | Description | |---|---|---| -| `name` | Yes | Unique identifier in kebab-case. Start with a gerund verb (for example, `migrating-`, `converting-`). Maximum 64 characters. | +| `name` | Yes | Unique identifier in kebab-case. Start with a gerund verb (for example, `upgrading-`, `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`. | @@ -192,8 +192,8 @@ equivalents, updating configuration, and verifying behavior. - **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`. +- **Keep skills focused:** One skill per upgrade or task type. A skill for "upgrading FooBar v2 to v3" is better than "upgrading all internal libraries." +- **Name with a gerund verb:** Use `upgrading-foobar-v2-to-v3`, not `foobar-upgrade` or `foobar-v3`. - **Use `lazy` discovery:** Use `lazy` discovery for most custom skills to avoid bloating the agent's context window. ## Create custom scenarios diff --git a/docs/core/porting/github-copilot-app-modernization/faq.yml b/docs/core/porting/github-copilot-app-modernization/faq.yml index 1b7e833fbba9a..febe7481d30c0 100644 --- a/docs/core/porting/github-copilot-app-modernization/faq.yml +++ b/docs/core/porting/github-copilot-app-modernization/faq.yml @@ -27,7 +27,7 @@ sections: questions: - question: What can the agent do? answer: | - GitHub Copilot modernization helps you upgrade your .NET (.NET, .NET Core, and .NET Framework) projects to newer versions of .NET. It also helps migrate services to Azure, upgrades dependencies, and fixes errors in code after migration. The agent performs the following steps in a Copilot chat session: + GitHub Copilot modernization helps you upgrade your .NET (.NET, .NET Core, and .NET Framework) projects to newer versions of .NET. It also helps modernize services for Azure, upgrades dependencies, and fixes errors in code after the upgrade. The agent performs the following steps in a Copilot chat session: - Analyzes your projects and proposes a modernization plan. - Runs a series of tasks to modernize your projects according to the plan. @@ -39,7 +39,7 @@ sections: - question: What limitations are there? answer: | - The agent requires a local Git repository. - - The upgrade or migration suggestions aren't guaranteed to follow best practices. + - The upgrade suggestions aren't guaranteed to follow best practices. - Code fixes and corrections you provide to Copilot during the upgrade process don't persist and aren't remembered for future upgrades. - question: Which model should I use? @@ -58,14 +58,14 @@ sections: - question: Does the agent store my source code? answer: | - The agent never stores your codebase or uses your code to train the model. Once an upgrade or migration completes, the agent deletes session data. + The agent never stores your codebase or uses your code to train the model. Once an upgrade completes, the agent deletes session data. - question: Can I provide feedback? answer: | Yes! There are two ways to provide feedback: - In Visual Studio, use the [Suggest a feature](/visualstudio/ide/suggest-a-feature) and [Report a Problem](/visualstudio/ide/report-a-problem) features. - - File an issue at the [@modernize-dotnet GitHub repository](https://github.com/dotnet/modernize-dotnet). + - File an issue at the [modernize-dotnet GitHub repository](https://github.com/dotnet/modernize-dotnet). - question: What data is collected? answer: | @@ -79,7 +79,7 @@ sections: questions: - question: What can the agent upgrade? answer: | - 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). + GitHub Copilot modernization helps you upgrade your .NET projects or modernize them for Azure. The agent supports multiple scenarios beyond framework upgrades, including Aspire integration, SDK-style conversion, Newtonsoft.Json upgrade, SqlClient upgrade, Azure Functions upgrade, and Semantic Kernel to Microsoft Agent Framework upgrade. For a full reference, see [Scenarios and skills reference](scenarios-and-skills.md). The agent works with these project types: @@ -132,7 +132,7 @@ sections: The migration scenarios include: - - Modernizing databases + - Migrating databases - Storage - Identity - Messaging @@ -145,7 +145,7 @@ sections: - question: Can I monitor assessment progress? answer: | - Yes. Monitor the assessment progress through the Visual Studio interface. The agent provides real-time feedback and status updates on the migration process. Other development environments might offer different monitoring options. + Yes. Monitor the assessment progress through the Visual Studio interface. The agent provides real-time feedback and status updates. Other development environments might offer different monitoring options. In Visual Studio, monitor assessment progress by viewing the command-line output while the assessment runs: 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 382935a974650..fb39e2cc6fe5a 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 @@ -87,7 +87,7 @@ Before running the instruction during an upgrade, validate it in isolation. Isol ```text > Getting instructions for 'replace Newtonsoft with System.Text.Json'. - Perfect! I've retrieved the scenario instructions for migrating from Newtonsoft.Json to System.Text.Json. Now I'll begin the analysis following the scenario-specific instructions. + Perfect! I've retrieved the scenario instructions for upgrading from Newtonsoft.Json to System.Text.Json. Now I'll begin the analysis following the scenario-specific instructions. ``` 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. 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 afbabed6457af..45ee2ed5011c9 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 @@ -13,7 +13,7 @@ ai-usage: ai-assisted 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. The agent 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 upgrades from .NET Framework to modern .NET. ## Prerequisites @@ -82,7 +82,7 @@ After the assessment, Copilot evaluates your solution and presents upgrade strat 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. +- **Project upgrade approach.** In-place rewrite or side-by-side upgrade. - **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. @@ -135,7 +135,7 @@ To review and customize the plan: 1. Edit the plan to adjust upgrade steps or add context as needed. > [!CAUTION] - > 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. + > The plan depends on project interdependencies. The upgrade doesn't succeed if you modify the plan in a way that prevents the upgrade 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._ diff --git a/docs/core/porting/github-copilot-app-modernization/install.md b/docs/core/porting/github-copilot-app-modernization/install.md index 84607aee08870..c950cdc87bd2c 100644 --- a/docs/core/porting/github-copilot-app-modernization/install.md +++ b/docs/core/porting/github-copilot-app-modernization/install.md @@ -6,7 +6,7 @@ ms.date: 04/06/2026 ai-usage: ai-assisted zone_pivot_groups: copilot-modernization-install -#customer intent: As a developer, I want to install GitHub Copilot modernization so that I can upgrade and migrate my .NET applications. +#customer intent: As a developer, I want to install GitHub Copilot modernization so that I can upgrade my .NET applications. --- diff --git a/docs/core/porting/github-copilot-app-modernization/overview.md b/docs/core/porting/github-copilot-app-modernization/overview.md index 47fe2c9ba0e44..cc581d1c74d68 100644 --- a/docs/core/porting/github-copilot-app-modernization/overview.md +++ b/docs/core/porting/github-copilot-app-modernization/overview.md @@ -32,12 +32,12 @@ The agent provides multiple end-to-end modernization workflows called _scenarios |---|---|---| | **.NET version upgrade** | Upgrades from older .NET versions to .NET 8, 9, 10, or later. | _"Upgrade my solution to .NET 10"_ | | **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"_ | +| **Newtonsoft.Json upgrade** | Replaces Newtonsoft.Json with System.Text.Json. | _"Upgrade from Newtonsoft.Json"_ | +| **SqlClient upgrade** | Upgrades 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"_ | +| **Semantic Kernel to Agents** | Upgrades Semantic Kernel Agents to Microsoft Agent Framework. | _"Upgrade 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). +For a full reference of all scenarios and 30+ built-in upgrade skills, see [Scenarios and skills reference](scenarios-and-skills.md). ## Provide feedback @@ -154,7 +154,7 @@ Copilot starts by examining your project structure, dependencies, and code patte 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. **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 upgrade 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. @@ -225,5 +225,5 @@ The tool collects data about project types, intent to upgrade, and upgrade durat - [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) +- [Quickstart: Migrate a .NET project to Azure](../../../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 index bf7ffb3ef5e05..2c9ffa8556ec0 100644 --- a/docs/core/porting/github-copilot-app-modernization/scenarios-and-skills.md +++ b/docs/core/porting/github-copilot-app-modernization/scenarios-and-skills.md @@ -1,11 +1,11 @@ --- 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." +description: "Complete reference of all scenarios and built-in upgrade skills available in GitHub Copilot modernization for .NET, organized by domain." ms.topic: reference 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. +#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 tasks the agent can handle for me. --- @@ -14,12 +14,12 @@ ai-usage: ai-assisted 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. +- **Skills** are focused capabilities for specific upgrade 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?"_ +> You don't need to memorize names. Describe what you want (_"upgrade to .NET 10"_, _"upgrade 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 @@ -29,10 +29,10 @@ Scenarios are the agent's top-level upgrade workflows. When you start a conversa |---|---|---| | [**.NET version upgrade**](#net-version-upgrade) | Upgrades projects from any older .NET version to .NET 8 or later. | _"Upgrade my solution to .NET 10"_ | | [**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 Agent Framework. | _"Migrate my SK agents"_ | +| [**Newtonsoft.Json upgrade**](#newtonsoftjson-upgrade) | Replaces Newtonsoft.Json with System.Text.Json across a solution. | _"Upgrade from Newtonsoft.Json"_ | +| [**SqlClient upgrade**](#sqlclient-upgrade) | Upgrades System.Data.SqlClient to Microsoft.Data.SqlClient. | _"Update SqlClient to the modern package"_ | +| [**Azure Functions upgrade**](#azure-functions-upgrade) | Upgrades Azure Functions from in-process to isolated worker model. | _"Upgrade my Azure Functions"_ | +| [**Semantic Kernel to Agents**](#semantic-kernel-to-microsoft-agent-framework) | Upgrades from SK Agents to Microsoft Agent Framework. | _"Upgrade my SK agents"_ | For an end-to-end walkthrough, see [Core concepts](concepts.md). @@ -52,123 +52,119 @@ The agent analyzes your dependency graph, checks NuGet compatibility, identifies 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 +### Newtonsoft.Json upgrade Replaces `Newtonsoft.Json` with `System.Text.Json` across your solution. Handles custom converters, `[JsonProperty]` attributes, `JObject`/`JArray` usage, and serialization settings. -### SqlClient migration +### SqlClient upgrade -Migrates from `System.Data.SqlClient` to `Microsoft.Data.SqlClient`. Handles the `Encrypt=true` default behavior change and connection string differences. +Upgrades 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. +Upgrades Azure Functions from the in-process hosting model to the isolated worker model with `Program.cs` and `HostApplicationBuilder`. Includes Application Insights upgrade. -### Semantic Kernel to Agents +### Semantic Kernel to Microsoft Agent Framework -Migrates from Semantic Kernel Agents (`ChatCompletionAgent`, `OpenAIAssistantAgent`) to [Microsoft Agent Framework](/agent-framework/overview/). Updates packages and API patterns. +Upgrades from Semantic Kernel Agents (`ChatCompletionAgent`, `OpenAIAssistantAgent`) to [Microsoft Agent Framework](/agent-framework/overview/). Updates packages and API patterns. -## Migration skills: common +## Upgrade skills: common -General-purpose migration skills that apply across project types. +General-purpose upgrade 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. | +| **Upgrading Autofac to .NET DI** | Removes Autofac entirely and upgrades 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. | +| **Upgrading cryptography namespaces** | Fixes the `System.Security.Cryptography` namespace split for types like `X509Certificate2` and `SignedCms`. | +| **Upgrading Newtonsoft to System.Text.Json** | Full upgrade from `Newtonsoft.Json`. Handles converters, attributes, dynamic types, and settings. | +| **Upgrading Semantic Kernel to Agents** | Upgrades Semantic Kernel agent APIs to the Microsoft Agents AI Framework. | +| **Upgrading to MSMQ.Messaging** | Upgrades 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. | +| **Upgrading 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 +## Upgrade skills: data access -Skills for migrating data access layers, including Entity Framework, LINQ to SQL, and SQL client libraries. +Skills for upgrading 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`. | -| [**Semantic Kernel to Agents**](#semantic-kernel-to-agents) | Migrates from Semantic Kernel Agents (`ChatCompletionAgent`, `OpenAIAssistantAgent`) to [Microsoft Agent Framework](/agent-framework/overview/). Updates packages and API patterns. | -| **Migrating to Microsoft.Data.SqlClient** | Migrates from `System.Data.SqlClient`. Handles the `Encrypt=true` default change and connection string differences. | +| **Upgrading EDMX to Code-First** | Converts EF6 Database-First (`.edmx`) models to EF Core Code-First. Scaffolds entities from the database. | +| **Upgrading EF DbContext** | Registers `DbContext` in ASP.NET Core dependency injection. Handles both EF6 to EF Core and existing EF Core patterns. | +| **Upgrading EF6 Code-First to EF Core** | Upgrades EF6 Code-First to EF Core. Swaps packages, updates namespaces, and replaces `EntityTypeConfiguration` and `DbModelBuilder`. | +| **Upgrading to Microsoft.Data.SqlClient** | Upgrades from `System.Data.SqlClient`. Handles the `Encrypt=true` default change and connection string differences. | -## Migration skills: web and ASP.NET +## Upgrade skills: web and ASP.NET -Skills for migrating ASP.NET Framework applications to ASP.NET Core. +Skills for upgrading ASP.NET Framework applications to ASP.NET Core. -### ASP.NET Framework migration +### ASP.NET Framework upgrade | 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. | +| **Upgrading ASP.NET Framework to Core** | Comprehensive upgrade from ASP.NET Framework (MVC/WebAPI) to ASP.NET Core, including controllers, views, middleware, authentication, and configuration. | +| **Upgrading ASP.NET Identity** | Upgrades ASP.NET MVC Identity to ASP.NET Core Identity, including `IdentityDbContext`, `UserManager`, `SignInManager`, and auth middleware. | +| **Upgrading Global.asax** | Converts `Global.asax` lifecycle events (`Application_Start`, `Application_Error`) to ASP.NET Core `Program.cs` and middleware. | +| **Upgrading OWIN to middleware** | Replaces OWIN/Katana middleware (`IAppBuilder`, `OwinMiddleware`) with ASP.NET Core equivalents. | +| **Upgrading OWIN Cookie Authentication** | Upgrades OWIN cookie authentication middleware to ASP.NET Core cookie authentication. | +| **Upgrading OWIN OAuth to JWT** | Upgrades OWIN OAuth bearer token authentication to ASP.NET Core JWT bearer authentication. | +| **Upgrading OWIN OpenID Connect** | Upgrades 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 `