What Happened to the .NET Upgrade Assistant?

Microsoft's free migration tool has been deprecated in favor of an AI-powered approach. Here's what changed, what it means for your migration plans, and how to access both options.

If you've recently opened Visual Studio 2026 or updated to Visual Studio 2022 17.14.16+ and tried to use the .NET Upgrade Assistant, you may have noticed something different. The familiar "Upgrade" context menu now launches a different experience and your old workflow is nowhere to be found.

Here's what happened, and what you need to know.

The .NET Upgrade Assistant: A Brief History

Microsoft introduced the .NET Upgrade Assistant in March 2021 as an open-source tool to help developers migrate applications from .NET Framework to modern .NET. Available as both a Visual Studio extension and a command-line tool, it guided developers through the migration process step by step.

The tool automated several mechanical aspects of migration:

• Converting legacy .csproj files to the modern SDK-style format
• Updating the Target Framework Moniker (TFM)
• Upgrading NuGet package references to compatible versions
• Adding template files for ASP.NET Core projects
• Applying basic code fixes for common API changes

For many developers, especially those working on smaller projects or straightforward migrations, the Upgrade Assistant provided a helpful starting point. It was free, deterministic, and integrated directly into Visual Studio.

What Changed: Official Deprecation

As of late 2025, the .NET Upgrade Assistant is officially deprecated. Microsoft's documentation now states:

".NET Upgrade Assistant is officially deprecated. Use the GitHub Copilot app modernization chat agent instead, which is included with Visual Studio 2026 and Visual Studio 2022 17.14.16 or later."

This is a big shift in Microsoft's approach to .NET migration tooling. They've moved from a rule-based, deterministic tool to an AI-powered experience built on GitHub Copilot.

The Replacement: GitHub Copilot App Modernization

Microsoft's new solution is GitHub Copilot App Modernization, an AI-powered agent that operates through the Copilot Chat interface in Visual Studio. Rather than following a fixed sequence of upgrade steps, the new tool uses AI to analyze your codebase, generate a migration plan, and apply changes.

How It Works

The modernization agent follows a three-stage workflow:

1. Assessment Stage: Copilot examines your project structure, dependencies, and code patterns to identify what needs to change. It generates an assessment.md file in your repository.
2. Planning Stage: Based on the assessment, Copilot creates a detailed migration plan explaining how to resolve identified issues. This is saved as plan.md.
3. Execution Stage: Copilot breaks the plan into sequential tasks and performs the upgrade, creating Git commits along the way so you can review changes incrementally.

Major Capabilities

• Upgrades from older .NET versions to the latest (including .NET Framework to modern .NET)
• Analyzes dependencies and identifies compatibility issues
• Applies automated code fixes
• Creates Git commits for each change, enabling easy rollback
• Learns from manual interventions and applies patterns to similar issues

Requirements

To use GitHub Copilot App Modernization, you'll need:

• Visual Studio 2026 or Visual Studio 2022 version 17.14.17+
• Windows operating system
• .NET desktop development workload installed
• GitHub Copilot subscription (Pro, Pro+, Business, or Enterprise)
• GitHub account signed into Visual Studio with Copilot access

Subscription Costs

Unlike the free Upgrade Assistant, the Copilot-based replacement requires a paid GitHub Copilot subscription:

Note: GitHub occasionally offers limited free tiers or trials. Check current GitHub Copilot pricing for the latest options.

How to Access the Legacy Upgrade Assistant

For developers who prefer the original tool, or who don't have a Copilot subscription, the legacy Upgrade Assistant is still available, though it's now hidden by default.

In Visual Studio 2026 / Visual Studio 2022 17.14.16+

1. Open Visual Studio
2. Navigate to Tools → Options
3. Go to Projects and Solutions → Modernization
4. Enable "Enable legacy Upgrade Assistant"
5. Restart Visual Studio

After enabling this setting, you'll see the traditional Upgrade Assistant experience when you right-click a project and select "Upgrade."

Command-Line Tool

The CLI version of the Upgrade Assistant is available as a .NET global tool:

bash
 dotnet tool install -g upgrade-assistant

If you have multiple NuGet feed sources configured, you might need to add the --ignore-failed-sources flag:

bash
 dotnet tool install -g upgrade-assistant --ignore-failed-sources

To run the tool:

 bash
upgrade-assistant upgrade <path-to-project-or-solution>

Legacy Version for WCF Projects

If you're migrating WCF server-side projects, note that this requires a specific legacy version of the tool:

 bash
dotnet tool install upgrade-assistant -g --version 0.4.421302

The current version of the tool doesn't support WCF migrations. Only this older version does.

Comparing the Two Approaches

What Each Tool Handles Well

Legacy Upgrade Assistant Strengths

• Simple, straightforward migrations (.NET 6 → .NET Core, etc.)
• Console applications and class libraries
• Projects with standard dependencies
• Scenarios requiring predictable, reproducible results
• Environments without internet connectivity

Copilot App Modernization Strengths

• Complex codebases requiring contextual understanding
• Identifying non-obvious migration issues
• Learning from your corrections and applying patterns
• Integrated Git workflow with automatic commits
• Azure migration scenarios

What Neither Tool Handles Automatically

Regardless of which tool you choose, some migration scenarios require manual work:

• ASP.NET Web Forms: No direct migration path. Requires UI rewrite to Blazor or Razor Pages
• WCF Server-side with .svc files: Not supported by current tooling
• ASMX Web Services: Requires migration to modern web APIs
• Complex System.Web dependencies: HttpContext.Current patterns need refactoring
• Authentication systems: Forms Authentication and ASP.NET Membership require migration to ASP.NET Core Identity
• Third-party libraries without .NET support: May require replacement or alternative approaches
• Architectural refactoring: Neither tool provides guidance on modernization patterns

Practical Recommendations

For Individual Developers

If you're working on personal projects or exploring migration options, the legacy Upgrade Assistant via the CLI remains a solid choice for initial assessment. Enable it in Visual Studio settings for a familiar experience without subscription costs.

For Teams Already Using GitHub Copilot

If your organization already has Copilot Business or Enterprise subscriptions, the new modernization agent is worth exploring. The AI-powered approach can accelerate certain scenarios, and the automatic Git integration simplifies tracking changes.

For Enterprise Migrations

Large-scale migration projects typically require more than what any automated tool provides. Consider:

1. Assessment first: Use either tool's analysis capabilities to understand scope
2. Pilot project: Test the tools on a non-critical application before committing
3. Hybrid approach: Automated tools for mechanical transformations, human expertise for architectural decisions
4. Specialized help: Complex scenarios (WCF, Web Forms, large codebases) often benefit from experienced migration partners

Looking Ahead

Microsoft's shift to AI-powered tooling reflects broader trends in developer tools. The GitHub Copilot App Modernization agent will continue to evolve, and we can expect improvements in its capabilities over time.

For now, developers have options:

• The legacy Upgrade Assistant remains accessible for those who prefer it
• The new Copilot-based approach offers AI-powered assistance for those with subscriptions
• Both tools serve as starting points rather than complete solutions for complex migrations

The key is understanding what each tool can and can't do and planning your migration strategy accordingly.

Need help navigating your .NET modernization journey? GAPVelocity AI specializes in legacy application modernization, combining automated tooling with expert guidance to help organizations migrate from .NET Framework to modern .NET efficiently and reliably.