Edit

Upgrade to a new .NET version

  • Article

New .NET versions are released each year. Many developers start the upgrade process as soon as the new version is available, while others wait until the version they are using is no longer supported. The upgrade process has multiple aspects to consider.

Common reasons to upgrade to a new .NET version:

  • The currently used .NET version is no longer supported
  • The new version supports a new operating system
  • The new version has an important API, performance, or security feature

Upgrade development environment

To upgrade to a new .NET version, the .NET SDK is the primary component to install. It includes an updated .NET CLI, build system, and runtime version.

The .NET website offers installers and archives that you can download and use on any supported operating system and architecture.

Some operating systems have a package manager that you can also use to install a new .NET version, which you might prefer.

Visual Studio installs new .NET SDK versions automatically. For Visual Studio users, it's sufficient to upgrade to a newer Visual Studio version.

Upgrade source code

The only required change to upgrade an app is updating the TargetFramework property in a project file to the newer .NET version.

Here's how to do it:

  • Open the project file (the *.csproj, *.vbproj, or *.fsproj file).
  • Change the <TargetFramework> property value from, for example, net6.0 to net8.0.
  • The same pattern applies for the <TargetFrameworks> property if it is being used.

The Upgrade Assistant can make these changes automatically.

The next step is to build the project (or solution) with the new SDK. If additional changes are needed, the SDK will provide warnings and errors that guide you.

You might need to run dotnet workload restore to restore workloads with the new SDK version.

More resources:

Update continuous integration (CI)

CI pipelines follow a similar update process as project files and Dockerfiles. Typically, you can update CI pipelines by changing only version values.

Update hosting environment

There are many patterns that are used for hosting applications. If the hosting environment includes the .NET runtime, then the new version of the .NET runtime needs to be installed. On Linux, dependencies need to be installed, however, they typically don't change across .NET versions.

For containers, FROM statements need to be changed to include new version numbers.

The following Dockerfile example demonstrates pulling an ASP.NET Core 8.0 image.

FROM mcr.microsoft.com/dotnet/aspnet:8.0

In a cloud service like Azure App Service, a configuration change is needed.