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

title	author	description	ms.author	ms.custom	ms.date	no-loc	uid
Migrate from ASP.NET Core 3.1 to 5.0	scottaddie	Learn how to migrate an ASP.NET Core 3.1 project to ASP.NET Core 5.0.	scaddie	mvc	10/20/2020	appsettings.json ASP.NET Core Identity cookie Cookie Blazor Blazor Server Blazor WebAssembly Identity Let's Encrypt Razor SignalR	migration/31-to-50

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.

[!IMPORTANT] ASP.NET Core 5.0 is currently in preview.

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

{
  "sdk": {
-    "version": "3.1.200"
+    "version": "5.0.100-rc.2.20479.15"
  }
}

Update the target framework

If updating a Blazor WebAssembly project, skip to the Update Blazor WebAssembly projects section. For any other ASP.NET Core project type, update the project file's Target Framework Moniker (TFM) to net5.0:

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

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

</Project>

Update Blazor WebAssembly projects

For a Blazor WebAssembly project, including the Client project of a hosted Blazor solution, apply the following changes to the project file:

1. Update the SDK from Microsoft.NET.Sdk.Web to Microsoft.NET.Sdk.BlazorWebAssembly:

   - <Project Sdk="Microsoft.NET.Sdk.Web">
   + <Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
   

2. Update the following properties:

   <Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
   
     <PropertyGroup>
   -     <TargetFramework>netstandard2.1</TargetFramework>
   -     <RazorLangVersion>3.0</RazorLangVersion>
   +     <TargetFramework>net5.0</TargetFramework>
     </PropertyGroup>
   

3. Remove the package reference to Microsoft.AspNetCore.Components.WebAssembly.Build:

   <ItemGroup>
   -    <PackageReference Include="Microsoft.AspNetCore.Components.WebAssembly.Build" Version="3.2.1" PrivateAssets="all" />
   

Standalone Blazor WebAssembly app with Microsoft Accounts

For a standalone Blazor WebAssembly app registered in the Azure portal to use Azure Active Directory (AAD) for Microsoft Accounts:

• The app requires the openid and offline_access scopes:

  options.ProviderOptions.DefaultAccessTokenScopes.Add("openid");
  options.ProviderOptions.DefaultAccessTokenScopes.Add("offline_access");
  

• The platform configuration is set to Single-page application (SPA) in the Azure portal with the app's redirect URI.

For more information, see xref:blazor/security/webassembly/standalone-with-microsoft-accounts.

Standalone Blazor WebAssembly app with Azure Active Directory (AAD)

For a standalone Blazor WebAssembly app registered in the Azure portal to use Azure Active Directory (AAD):

• The app requires the https://graph.microsoft.com/User.Read scope:

  options.ProviderOptions.DefaultAccessTokenScopes
      .Add("https://graph.microsoft.com/User.Read");
  

• The platform configuration is set to Single-page application (SPA) in the Azure portal with the app's redirect URI.

For more information, see xref:blazor/security/webassembly/standalone-with-azure-active-directory.

Standalone Blazor app with Azure Active Directory (AAD) B2C

For a standalone Blazor WebAssembly app registered in the Azure portal to use Azure Active Directory (AAD) B2C:

• The app requires the openid and offline_access scopes:

  options.ProviderOptions.DefaultAccessTokenScopes.Add("openid");
  options.ProviderOptions.DefaultAccessTokenScopes.Add("offline_access");
  

• The platform configuration is set to Single-page application (SPA) in the Azure portal with the app's redirect URI.

For more information, see xref:blazor/security/webassembly/hosted-with-azure-active-directory-b2c.

[!NOTE] Update the Server project of a hosted Blazor solution as an ASP.NET Core app following the general guidance in this article.

Update package references

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

<ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="3.1.6" />
-    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="3.1.6" />
-    <PackageReference Include="System.Net.Http.Json" Version="3.2.1" />
+    <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="5.0.0-rc.2.*" />
+    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="5.0.0-rc.2.*" />
+    <PackageReference Include="System.Net.Http.Json" Version="5.0.0-rc.2.*" />
</ItemGroup>

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.

Model binding changes in ASP.NET Core MVC and Razor Pages

DateTime values are model bound as UTC times

In ASP.NET Core 3.1 and earlier, DateTime values were model-bound as local time, where the timezone was determined by the server. DateTime values bound from input formatting (JSON) and DateTimeOffset values were bound as UTC timezones.

In ASP.NET Core 5.0 and later, model binding consistently binds DateTime values with the UTC timezone.

To retain the previous behavior, remove the DateTimeModelBinderProvider in Startup.ConfigureServices:

services.AddControllersWithViews(options => 
    options.ModelBinderProviders.RemoveType<DateTimeModelBinderProvider>());

ComplexObjectModelBinderProvider \ ComplexObjectModelBinder replace ComplexTypeModelBinderProvider \ ComplexTypeModelBinder

To add support for model binding C# 9 record types, the xref:Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ComplexTypeModelBinderProvider is:

• Annotated as obsolete.
• No longer registered by default.

Apps that rely on the presence of the ComplexTypeModelBinderProvider in the ModelBinderProviders collection need to reference the new binder provider:

- var complexModelBinderProvider = options.ModelBinderProviders.OfType<ComplexTypeModelBinderProvider>();
+ var complexModelBinderProvider = options.ModelBinderProviders.OfType<ComplexObjectModelBinderProvider>();

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.