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.

Prerequisites

Visual Studio

• Visual Studio 2019 16.4 or later with the ASP.NET and web development workload
• .NET Core 3.1 SDK

Visual Studio Code

• Visual Studio Code
• C# for Visual Studio Code (latest version)
• .NET Core 3.1 SDK

The Visual Studio Code instructions use the .NET CLI for ASP.NET Core development functions such as project creation. You can follow these instructions on any platform (macOS, Linux, or Windows) and with any code editor. Minor changes may be required if you use something other than Visual Studio Code. For more information on installing Visual Studio Code on macOS, see Visual Studio Code on macOS.

Visual Studio for Mac

• Visual Studio for Mac version 8.4 or later
• .NET Core 3.1 SDK

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">

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

</Project>

Update package references

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

<ItemGroup>
-    <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'" />
</ItemGroup>

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/aspnet:3.1

React to SameSite cookie changes

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:

• Work with SameSite cookies in ASP.NET Core
• aspnet/Announcements#390
• Upcoming SameSite cookie changes in ASP.NET and ASP.NET Core

Publish with Visual Studio

In the .pubxml file update the TargetFramework to 3.1:

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

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 Prerender and integrate ASP.NET Core Razor components.

ASP.NET Core Module (ANCM)

If the ASP.NET Core Module (ANCM) wasn't a selected component when Visual Studio was installed or if a prior version of the ANCM was installed on the system, download the latest .NET Core Hosting Bundle Installer (direct download) and run the installer. For more information, see Hosting Bundle.