Recently .NET Upgrade Assistant has introduced some useful new features and a new Central Package Management (CPM) upgrade type.

.NET Upgrade Assistant helps you upgrade your solutions to newer versions of .NET. Whether you’re upgrading from .NET Framework to .NET 8 or just between .NET versions, .NET Upgrade Assistant can help you understand what changes are needed and will automate many of the changes for you. .NET Upgrade Assistant is available as a Visual Studio extension or as a command-line tool.

The newest version of Upgrade Assistant introduces a new type of upgrade to allow you to convert your whole solution or a selected set of projects to use Nuget Central Package Management (CPM).

Upgrading to use CPM in Visual Studio

To begin upgrading a project to CPM in Visual Studio with the Upgrade Assistant extension installed, right-click on the project node in the Solution Explorer and select Upgrade. You’ll notice a new upgrade project feature – Nuget Central Package Management (CPM).

If you select this option, the next screen will give you the option to also select any number of additional projects in your solution for upgrade to CPM, but in most cases, we suggest you upgrade all projects in your solution.

The next page offers some customization options. If you’d like to also convert the selected projects to SDK style you may check the box for that option. By default, web projects will not be converted to SDK style since there is no official tooling support for classic web projects if they are converted to SDK style as-is. It is recommended that you upgrade these web projects separately, but if you’d like to include them here there is an option to do so by checking the “include web projects to SDK conversion” box.

This page also offers Nuget Central Package Management settings. Transitive pinning is recommended and on by default. We also surface the suggested file path where all centralized package versions will be stored. If the suggested location is incorrect, you may pick a different location yourself. The last customization option is the ability to add a JSON configuration file to define these same selections.

When you are satisfied with your selections, click Upgrade to proceed with the upgrade to CPM.

Upgrading with CLI

The same CPM upgrade can also be done via the .NET Upgrade Assistant command line tool. Invoke the Upgrade Assistant CLI by navigating to your solution in Command Prompt and using the command:

upgrade-assistant upgrade

First you will select which project you would like to upgrade, but you will have the ability to select more later. Next you will select how you would like to upgrade your project. The new CPM upgrade option can be found under NuGet upgrades, listed as “NuGet central package management (CPM).”

Next you will select which project(s) in your solution you would like to upgrade to CPM. You may choose to upgrade all projects or select a subset of your projects. Press the Space Bar to select and Enter to accept the current selections.

You will now have the opportunity to provide a JSON file to define the run configurations. A sample run config file with all values defined is as follows:

{
  "upgrade": {
    "settings": {
      "cpm": {
        "convertProjectsToSdkStyle": false,
        "includeWebProjects": false,
        "useTransitivePinning": true,
        "rootPath": "somePath"
      }
    }
  }
}

Next you will be asked if you would like to also upgrade to SDK style.

If you select yes for this question, you will be asked another question about whether you would like to include web projects in this upgrade. It is worth noting again that we recommend that you upgrade these web projects separately. Finally, you will be asked if you would like transitive pinning enabled, which is recommended for most cases.

After all these selections, hit Enter. You will be asked if you want to proceed with the upgrade. Input ‘y’ and hit Enter to run the Upgrade Assistant tool with the current selections.

Understanding the File Changes

When you click Upgrade in Visual Studio or hit Enter to run the .NET CLI tool, projects with package references will be modified and your solution or selected projects will now be using NuGet Central Package Management.

If you take a look at the Git Changes for your project, you can see the file changes that were made by the tool.

You will notice that the version attributes in the .csproj file and the package.config assembly references have been removed. The tool now finds all PackageReferences across all targets imported by projects located in the repository. All package versions have been consolidated in Directory.packages.props.

Package Discovery

As a part of the recent improvements to Upgrade Assistant, we changed the way project dependencies are discovered and modified in all kinds of upgrades. Previously, upgrades modified NuGet package references, assembly references, and project references directly in the project file. Now, these are edited at locations where they are defined rather than editing the project file directly, i.e. if a PackageReference is defined in the explicitly imported target file or in one of the implicit imports like Directory.Build.props, Directory.Build.targets, or Directory.Packages.props we will modify it right there.

Improved Accessibility

Aside from updates to CPM support and package discovery, we have also improved the accessibility of our tool and its reports. Both the Visual Studio tool and the HTML report it generates have improved accessibility ratings and are even more compatible with screen readers and other assistive technologies.

Security related changes to supported Visual Studio versions

The minimum supported VS version of Upgrade Assistant is now 17.3 (previously 17.1). Due to changes in Visual Studio, we suggest versions below 17.3 be updated in order to remain secure. Because of this, Upgrade Assistant can no longer support Visual Studio versions below 17.3.

Feedback

Please give us your feedback or report any issues either by filing an issue directly in the .NET Upgrade Assistant repository, or via the Visual Studio feedback channel by choosing Help | Send Feedback in Visual Studio. Please mention “.NET Upgrade Assistant” in the title so it will get routed to our team quickly. We appreciate your input and want to build the best tools for you!