Migrate from ASP.NET Core 3.0 to 3.1

By Scott Addie

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


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 3.1 SDK version that's installed. For example:

  "sdk": {
-    "version": "3.0.101"
+    "version": "3.1.101"

Update the target framework

In the project file, update the Target Framework Moniker (TFM) to netcoreapp3.1:

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

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


Update package references

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

-    <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="3.0.0" />
-    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation" Version="3.0.0" Condition="'$(Configuration)' == 'Debug'" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="3.1.1" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation" Version="3.1.1" Condition="'$(Configuration)' == 'Debug'" />

Update Docker images

For apps using Docker, use a base image that includes ASP.NET Core 3.1. For example:

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

The SameSite attribute implementations for HTTP cookies changed between ASP.NET Core 3.0 and 3.1. For actions to be taken, see the following resources:

Review breaking changes

Review 3.0-to-3.1 breaking changes across .NET Core, ASP.NET Core, and Entity Framework Core at Breaking changes for migration from version 3.0 to 3.1.

Optional changes

The following changes are optional.

Use the Component Tag Helper

ASP.NET Core 3.1 introduces a Component Tag Helper. The Tag Helper can replace the RenderComponentAsync<TComponent> HTML helper method in a Blazor project. For example:

- @(await Html.RenderComponentAsync<Counter>(RenderMode.ServerPrerendered, new { IncrementAmount = 10 }))
+ <component type="typeof(Counter)" render-mode="ServerPrerendered" param-IncrementAmount="10" />

For more information, see Integrate ASP.NET Core Razor components into Razor Pages and MVC apps.