How .NET Modernization Works with the Copilot Upgrade Agent

Microsoft published a free course called .NET Modernization for Beginners, alongside a full documentation section for the Copilot modernization agent it's built around. Both are genuinely good material, and modernization gets far less coverage than starting something new does.

Why modernization is a real subject

Most content about .NET assumes an empty folder. Pick the latest version, pick your patterns, go. That's the fun part, and it's a fraction of the actual work in the industry.

A large amount of .NET in production runs on .NET Framework, written years ago by people making reasonable decisions for the tooling of the time. Those applications still need maintaining, and eventually they need moving, for support lifecycles, security patching, performance, cloud hosting, or simply to keep being able to hire people who want to work on them.

Upgrading a real application is harder than starting a new one, because the framework version is never the hard part. The hard part is the dozen things that quietly depended on old behaviour.

The workflow: assess, plan, execute

The whole approach is built on three stages, in that order, and the ordering is the useful idea.

Assessment examines project structure, dependencies, and code patterns, then reports breaking changes, API compatibility problems, deprecated patterns, and the scope of the work.

Planning turns that assessment plus your confirmed decisions into a specification: upgrade strategy, refactoring approach, dependency paths, risk mitigations.

Execution breaks the plan into sequential concrete tasks, each with validation criteria, so every change has a definition of "this worked."

The point of separating those is that an assessment report is a decision tool, not output to skim. Reading it and deciding what's actually risky is the skill. The mechanical edits are the easy half.

What the course covers

Five chapters following that shape:

• 00 introduction and the overall workflow
• 01 assessment, running compatibility analysis against a legacy app
• 02 planning, turning findings into a prioritised strategy
• 03 execution, the migration itself
• 04 deploying the modernised application to Azure

It works on a sample application called BookCatalog: a legacy ASP.NET MVC 5 app on .NET Framework 4.8, taken to .NET 10. Using a real codebase with accumulated decisions in it matters, because a clean toy example wouldn't produce the compatibility problems that make the assessment stage worth learning in the first place.

Prerequisites for following it as written are Windows 11, Visual Studio 2026, a GitHub Copilot subscription, and both the .NET Framework 4.8 and .NET 10 SDKs.

What the agent handles

The modernization agent runs in Visual Studio, VS Code, the GitHub Copilot CLI, and on GitHub.com. You point it at a solution and describe what you want:

Upgrade my solution to .NET 10
Convert to SDK-style
Upgrade from Newtonsoft.Json
Migrate my Web Forms app to Blazor

The supported upgrade paths cover more than just jumping to the newest version:

Beyond version upgrades there are targeted scenarios for specific migrations: Newtonsoft.Json to System.Text.Json, System.Data.SqlClient to Microsoft.Data.SqlClient, Azure Functions from the in-process model to the isolated worker model, Web Forms to Blazor, and adding Aspire support.

Project types covered include ASP.NET Core with MVC, Razor Pages and Web API, Web Forms, Blazor, Azure Functions, WPF, Windows Forms, WinUI, MAUI and Xamarin, class libraries, console apps, and test projects on MSTest, NUnit, or xUnit.

The design detail worth paying attention to

The agent writes its work to disk as Markdown, in .github/upgrades/{scenarioId}:

assessment.md            analysis of the solution
upgrade-options.md       confirmed upgrade decisions
plan.md                  ordered task plan
tasks.md                 live progress dashboard
scenario-instructions.md persistent memory, preferences and decisions

Those files are editable before you let it continue. That's what makes this a tool rather than a magic button: if the assessment misread something, you correct the Markdown and the plan follows from your correction.

Because all the state lives in that folder, the process survives closing the IDE, and can even be continued in a different editor than the one it started in. It commits as it goes, so rolling back a bad step is an ordinary git operation rather than an undo you hope works.

Strategies and flow control

During assessment the agent recommends one of three strategies, and which one fits depends on the shape of the solution:

• Bottom-up upgrades leaf projects first and works upward, for large solutions with deep dependency graphs
• Top-down upgrades the application project first then fixes dependencies, for fast feedback on the main app
• All-at-once does everything in one pass, for small solutions

There are also two flow modes. Automatic runs through all stages and stops only at genuine blockers. Guided pauses at every stage boundary so you can review the assessment, the plan, and the tasks before it proceeds. You switch between them mid-run by saying "pause" or "continue."

Why this is worth knowing

Version upgrades are the visible part of modernization and the smallest part. What this material actually teaches is the process around it: that an assessment produces a document you're meant to argue with, that the strategy depends on the dependency graph rather than preference, and that the work should be committed incrementally so any step can be undone.

That knowledge applies whether or not you use the Copilot agent to do the work, and it's the kind of thing that's much better to have read before it becomes urgent than during the week it does.