200 lines
8.0 KiB
Markdown
200 lines
8.0 KiB
Markdown
---
|
|
title: Migrate from ASP.NET Core 3.1 to 5.0
|
|
author: scottaddie
|
|
description: Learn how to migrate an ASP.NET Core 3.1 project to ASP.NET Core 5.0.
|
|
ms.author: scaddie
|
|
ms.custom: mvc
|
|
ms.date: 10/20/2020
|
|
no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
|
|
uid: migration/31-to-50
|
|
---
|
|
# Migrate from ASP.NET Core 3.1 to 5.0
|
|
|
|
By [Scott Addie](https://github.com/scottaddie)
|
|
|
|
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](#tab/visual-studio)
|
|
|
|
[!INCLUDE[](~/includes/net-core-prereqs-vs-5.0.md)]
|
|
|
|
# [Visual Studio Code](#tab/visual-studio-code)
|
|
|
|
[!INCLUDE[](~/includes/net-core-prereqs-vsc-5.0.md)]
|
|
|
|
# [Visual Studio for Mac](#tab/visual-studio-mac)
|
|
|
|
[!INCLUDE[](~/includes/net-core-prereqs-mac-5.0.md)]
|
|
|
|
---
|
|
|
|
## Update .NET Core SDK version in global.json
|
|
|
|
If you rely upon a [global.json](/dotnet/core/tools/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:
|
|
|
|
```diff
|
|
{
|
|
"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](#update-blazor-webassembly-projects) section. For any other ASP.NET Core project type, update the project file's [Target Framework Moniker (TFM)](/dotnet/standard/frameworks) to `net5.0`:
|
|
|
|
```diff
|
|
<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`:
|
|
|
|
```diff
|
|
- <Project Sdk="Microsoft.NET.Sdk.Web">
|
|
+ <Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
|
|
```
|
|
|
|
1. Update the following properties:
|
|
|
|
```diff
|
|
<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">
|
|
|
|
<PropertyGroup>
|
|
- <TargetFramework>netstandard2.1</TargetFramework>
|
|
- <RazorLangVersion>3.0</RazorLangVersion>
|
|
+ <TargetFramework>net5.0</TargetFramework>
|
|
</PropertyGroup>
|
|
```
|
|
|
|
1. Remove the package reference to [Microsoft.AspNetCore.Components.WebAssembly.Build](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Build):
|
|
|
|
```diff
|
|
<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:
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
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.*](https://www.nuget.org/packages?q=Microsoft.AspNetCore.*), [Microsoft.Extensions.*](https://www.nuget.org/packages?q=Microsoft.Extensions.*), and [System.Net.Http.Json](https://www.nuget.org/packages/System.Net.Http.Json) package reference's `Version` attribute to 5.0.0 or later. For example:
|
|
|
|
```diff
|
|
<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:
|
|
|
|
```diff
|
|
- 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](https://github.com/dotnet/dotnet-docker/issues/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`:
|
|
|
|
```csharp
|
|
services.AddControllersWithViews(options =>
|
|
options.ModelBinderProviders.RemoveType<DateTimeModelBinderProvider>());
|
|
```
|
|
|
|
### ComplexObjectModelBinderProvider \ ComplexObjectModelBinder replace ComplexTypeModelBinderProvider \ ComplexTypeModelBinder
|
|
|
|
To add support for model binding [C# 9 record types](/dotnet/csharp/whats-new/csharp-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:
|
|
|
|
```diff
|
|
- 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](/dotnet/core/compatibility/3.1-5.0). ASP.NET Core and Entity Framework Core are also included in the list.
|