Every .NET team has at least one of them: the project still targeting .NET 6 because nobody wants to spend a week wrestling with breaking changes, deprecated packages, and the inevitable cascade of test failures. You know the drill -- update the TFM, run dotnet build, stare at a wall of errors, and slowly chip away at them while second-guessing whether the whole thing is worth it.

Microsoft clearly knows this pain point. In March 2026, they expanded the modernize-dotnet agent beyond Visual Studio to run across VS Code, the GitHub Copilot CLI, and GitHub.com itself. It is not a simple find-and-replace tool -- it follows a structured assess, plan, execute workflow that produces reviewable Markdown artefacts at each stage, letting you stay in control while the agent handles the tedious parts.

Here is what it actually does, how to use it, and where it falls short.

What the agent covers

The modernize-dotnet agent handles two broad categories of work: version upgrades (moving from an older .NET version to the latest) and Azure migrations (shifting on-premises services to their Azure equivalents).

For version upgrades, it supports the project types you would expect:

It also handles .NET Framework to modern .NET migrations for ASP.NET MVC, Web API, Windows Forms, WPF, and Azure Functions. Web Forms support is listed as coming soon, though given the complexity of that migration, expectations should be tempered.

On the Azure migration side, it offers predefined tasks for common modernisation scenarios -- migrating databases to Azure SQL or PostgreSQL with managed identity, replacing local file I/O with Azure Blob Storage, transitioning from MSMQ or RabbitMQ to Azure Service Bus, moving authentication to Microsoft Entra ID, and adopting OpenTelemetry on Azure. Each of these follows the same structured workflow.

The three-stage workflow

The agent does not just start rewriting your code. It runs a deliberate three-stage process, writing Markdown files into .github/upgrades/{scenarioId} in your repository at each stage. This is arguably its best design decision -- you get full visibility into what the agent plans to do before it touches a line of code.

Stage 1: Assessment

The agent examines your project structure, dependencies, and code patterns. It produces an assessment.md file that catalogues breaking changes, API compatibility issues, deprecated patterns, and the overall scope of the upgrade.

For a typical ASP.NET Core project moving from .NET 6 to .NET 10, the assessment includes an executive summary with metrics (total files, NuGet packages needing updates, identified issues), a dependency compatibility matrix, and a list of the most challenging API migrations. You can review and annotate this file before proceeding.

Stage 2: Planning

The agent converts the assessment into a plan.md file -- a detailed specification covering upgrade strategies, refactoring approaches, dependency upgrade paths, and risk mitigations. It sequences the work based on project interdependencies.

// WARNING

Editing the plan to remove a project that other projects depend on will break the upgrade. The agent builds a dependency graph and sequences tasks accordingly -- removing a node from that graph can leave downstream projects in a broken state.

Stage 3: Execution

Finally, the agent generates a tasks.md file with sequential, concrete tasks. Each task has validation criteria -- specific checks the agent runs to confirm the step succeeded before moving on.

.github/upgrades/dotnet-version-upgrade/tasks.md 
### [ ] TASK-002: Atomic framework and package upgrade
**References**: Plan Phase 1, Package Update Reference

- [ ] Update TargetFramework to net10.0 in all project files
- [ ] Update package references per dependency analysis
- [ ] Restore all dependencies across solution
- [ ] All dependencies restored successfully (**Verify**)
- [ ] Build solution and fix compilation errors
- [ ] Solution builds with 0 errors (**Verify**)
- [ ] Commit changes

The agent creates Git commits at each stage, so you can review diffs, roll back individual steps, or cherry-pick changes. When it encounters a problem it cannot resolve, it asks for help -- and learns from your fix to apply it if the same issue appears later in the upgrade.

Using the agent across environments

One of the key improvements in the March 2026 expansion is that the same workflow runs identically regardless of where you invoke it.

Visual Studio

Right-click your solution or project in Solution Explorer and select Modernize, or open GitHub Copilot Chat and type @Modernize. This is the most integrated experience -- the agent has full access to Solution Explorer context and can trigger builds directly.

Requirements: Visual Studio 2026 (v18.1+) or Visual Studio 2022 (v17.14.17+) with the .NET desktop development workload and GitHub Copilot components enabled.

Visual Studio Code

Open the GitHub Copilot Chat panel and select modernize-dotnet from the Agent picker. You will need to install the GitHub Copilot modernization extension from the VS Code Marketplace first.

GitHub Copilot CLI

For terminal-first workflows:

terminal 
# Add the marketplace source
/plugin marketplace add dotnet/modernize-dotnet

# Install the plugin
/plugin install modernize-dotnet@modernize-dotnet-plugins

# Start the agent
/agent
# Select modernize-dotnet, then prompt:
# "upgrade my solution to .NET 10"

// TIP

You may need to restart the Copilot CLI after installing the plugin for it to appear in the agent list.

GitHub.com

The agent can also run as a Copilot coding agent directly in your repository, creating a pull request with the upgrade changes. This is useful for kicking off upgrades on repositories you do not have cloned locally.

Pre-initialisation decisions

Before the agent starts its three-stage workflow, it asks you three questions:

  1. Target framework version -- which .NET version to upgrade to.
  2. Git branching strategy -- whether to work on a new branch (recommended) or the current one.
  3. Workflow mode -- automatic (the agent runs through all stages) or guided (you review and approve each stage before proceeding).

The guided mode is the sensible default for your first upgrade. Once you are comfortable with the artefacts the agent produces, automatic mode is faster for routine version bumps.

Custom skills for organisational standards

The agent supports custom skills -- reusable behaviour definitions that encode your organisation's specific migration patterns, internal frameworks, or architectural standards. Any skills placed in the repository are automatically discovered and applied during the upgrade.

This is where the agent starts to become genuinely useful at scale. If your organisation has a standard approach to, say, replacing a legacy logging framework with Serilog, or migrating from a custom DI container to the built-in one, you can encode that as a skill. The agent applies it consistently across every upgrade, rather than each developer reinventing the same migration path.

A practical example: .NET 6 to .NET 10

To make this concrete, consider upgrading a solution with an ASP.NET Core MVC app, a Razor Pages app, a WPF desktop app, and their associated test projects -- six projects in total.

The assessment identifies 65 issues: a security vulnerability in HtmlSanitizer, a deprecated package, 51 WPF API binary incompatibilities related to BinaryFormatter removal, and several behavioural changes in UseExceptionHandler. Across the solution, 6 of 16 NuGet packages need updates.

The plan sequences the work into phases: prerequisites verification, an atomic framework and package upgrade (all projects upgraded simultaneously to avoid cross-project reference issues), and a final testing and validation pass.

During execution, the agent updates all .csproj files, bumps package versions, restores dependencies, builds the solution, and fixes compilation errors referencing the breaking changes catalogue from the assessment. It then runs the test suite, fixes any failures, and commits the results.

The entire process produces three commits and three Markdown artefacts you can review as a team before merging.

Common pitfalls

Skipping the assessment review. The assessment is not just informational -- it is the foundation for the plan and execution stages. If it misidentifies a dependency or misses a breaking change, those errors cascade. Spend five minutes reviewing it.

Editing the plan without understanding the dependency graph. Removing a project from the plan because it "looks simple" can break the upgrade if other projects depend on it. The agent sequences tasks based on project references -- respect that ordering.

Running in automatic mode on complex solutions. For solutions with .NET Framework projects, custom MSBuild targets, or non-standard project structures, guided mode gives you the chance to correct course before the agent goes too far down a wrong path.

Expecting it to handle everything. The agent is good at mechanical migrations -- TFM changes, package updates, API replacements. It is less effective at architectural modernisation like replacing a hand-rolled service locator with proper dependency injection. Those changes still need human judgement.

Forgetting about runtime behaviour changes. The agent focuses on compilation. Behavioural changes that do not produce build errors (like the UseExceptionHandler middleware changes in .NET 10) may slip through. Your test suite is the safety net -- make sure it is comprehensive before you start.

What it does not do

The agent is explicitly a migration tool, not a modernisation-in-depth tool. It will not refactor your codebase to use newer C# language features (like primary constructors or collection expressions) unless those changes are required to fix a breaking change. It will not restructure your architecture, add missing tests, or improve your CI pipeline.

It also requires a GitHub Copilot subscription -- Copilot Free (in VS 2026 v18.1+), Copilot Pro, Pro+, Business, or Enterprise all qualify. There is no standalone version.

Summary