Recently, I came across a case where we need to upgrade some projects written in .Net Core 2.1 to the latest LTS version of .Net (8). There were many project files, 70+ in one solution, and we wanted to upgrade some of them. We decided to go try it with NET Upgrade Assistant

The .NET Upgrade Assistant is a command-line tool provided by Microsoft to simplify the process of upgrading .NET projects from older versions (e.g., .NET Framework, .NET Core 2.1) to newer versions (e.g., .NET 6, .NET 8).

This blog explains how it works, the options it provides, and when to use each option.

1. Installing the Upgrade Assistant

You can use .Net command-line tool to install the Upgrade Assistant.

dotnet tool install -g upgrade-assistant

2. Running the Upgrade Assistant

Basic usage:

upgrade-assistant upgrade <path-to-project-or-sln>

The tool is interactive and walks through the steps required to upgrade your project. Upgrade assistant prompts as

3. Upgrade steps

3.1. Upgrade project to a newer .NET version

• This step updates the <TargetFramework> in .csproj to the next supported .NET version (e.g., net6.0, net8.0).

• Select the In-pace Project upgrade option as shown below

3.2 Select target upgrade version

Upgrade Assistant will now ask for confirmation

After completion of the upgrade process, you will get a summary of the upgrade indicating successful, failed, and skipped counts.

3.3. Upgrade NuGet packages

After updating the framework, it is recommended to upgrade NuGet packages to ensure compatibility and security. It suggests and applies updated versions of NuGet dependencies compatible with your target framework.

Again, execute the upgrade command as

upgrade-assistant upgrade <path-to-project-or-sln>

This time, select Nuget upgrades

It will ask you different options as

Do you want to provide a config file with customization settings?

Select N

Do you want to convert classic projects to SDK-Style? [y/n] (n): y

This option converts classic .csproj format (verbose XML) to a simplified SDK-style format.

Say “Yes” unless you want to manually convert later.

Do you want to include web projects to SDK-style conversion (it is recommended to upgrade them separately)? [y/n] (n): y

Say “Yes” if you’re ready to convert web projects and handle associated changes in Startup.cs and Program.cs. Otherwise, defer and convert manually later.

Enable transitive pinning? [y/n] (y):

This option locks down transitive package versions using packages.lock.json for consistent builds.

Recommended for teams, CI/CD pipelines, or projects needing deterministic restores.

At this point, Upgrade Assistant is ready to upgrade NuGet packages

4. Best Practices for Upgrades

• Upgrade step by step: .NET Core 2.1 → .NET 6 → .NET 8

• Upgrade NuGet packages after updating the framework

• Test after each step

• Backup your projects before starting

• Use version control (Git) to track changes and roll back if needed

5. Common Scenarios and What to Choose

Case: Upgrading a class library from .NET Core 2.1 to 8
Option to choose: Accept all steps, including SDK-style and NuGet upgrades

Case: Upgrading a Web API with Startup.cs
Option to choose: Accept SDK-style, but be ready to manually adjust the Program.cs

Scenario: Projects with heavy custom MSBuild tasks
Option to choose: Consider reviewing csproj manually after upgrade

Scenario: CI/CD projects needing reproducible builds
Option to choose: Enable transitive pinning

6. Some important aspects to note.

• You can rerun the assistant multiple times, and it will pick up where you left off.

• The tool updates code incrementally and suggests changes, but you’re always in control.

• Always test and review changes before pushing to production.

Conclusion

Upgrading projects from older version of .Net has some breaking changes. With .NET Upgrade Assistant most of the upgrade work can be done with ease. We will need to make some code changes as per new .Net standards(middleware, dependency injection, routes, etc). After application is build successfully we will have to do a thorough testing in case more code changes are there.