AspNetCore.Docs/aspnetcore/migration/30-to-31.md

title	author	description	ms.author	ms.custom	ms.date	uid
Migrate from ASP.NET Core 3.0 to 3.1	rick-anderson	Learn how to migrate an ASP.NET Core 3.0 project to ASP.NET Core 3.1.	wpickett	mvc	07/02/2020	migration/30-to-31

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

[!INCLUDE]

Visual Studio Code

[!INCLUDE]

Visual Studio for Mac

[!INCLUDE]

---

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:

• xref:security/samesite
• 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 xref:blazor/components/integration?view=aspnetcore-3.1&preserve-view=true.

ASP.NET Core Module (ANCM)

[!INCLUDE]