Migrate from ASP.NET Core 3.1 to 5.0

By Scott Addie

This article explains how to update an existing ASP.NET Core 3.1 project to ASP.NET Core 5.0.


ASP.NET Core 5.0 is currently in preview.


Update .NET Core SDK version in global.json

If you rely upon a global.json file to target a specific .NET Core SDK version, update the version property to the .NET 5.0 SDK version that's installed. For example:

  "sdk": {
-    "version": "3.1.200"
+    "version": "5.0.100-preview.6.20318.15"

Update the target framework

In the project file, update the Target Framework Moniker (TFM) to net5.0:

<Project Sdk="Microsoft.NET.Sdk.Web">

-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net5.0</TargetFramework>


Update package references

In the project file, update each Microsoft.AspNetCore.* and Microsoft.Extensions.* package reference's Version attribute to 5.0.0 or later. For example:

-    <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="3.1.2" />
-    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="3.1.2" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="5.0.0-preview.6.20312.15" />
+    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="5.0.0-preview.6.20305.6" />

Update Docker images

For apps using Docker, update your Dockerfile FROM statements and scripts. Use a base image that includes the ASP.NET Core 5.0 runtime. Consider the following docker pull command difference between ASP.NET Core 3.1 and 5.0:

- docker pull mcr.microsoft.com/dotnet/core/aspnet:3.1
+ docker pull mcr.microsoft.com/dotnet/aspnet:5.0

As part of the move to ".NET" as the product name, the Docker images moved from the mcr.microsoft.com/dotnet/core repositories to mcr.microsoft.com/dotnet. For more information, see dotnet/dotnet-docker#1939.

Review breaking changes

For breaking changes from .NET Core 3.1 to .NET 5.0, see Breaking changes for migration from version 3.1 to 5.0. ASP.NET Core and Entity Framework Core are also included in the list.