This article explains how to update an existing ASP.NET Core 3.1 project to ASP.NET Core 5.0. For instructions on how to migrate from ASP.NET Core 3.1 to ASP.NET Core 6.0, see <xref:migration/31-to-60>.
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:
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`:
The computation of route precedence changed in the ASP.NET Core 5.0.1 patch release. This might affect you if you've defined catch-all routes or routes with optional parameters.
### Old behavior
With the prior behavior in ASP.NET Core 5.0.0 or earlier, routes with lower precedence, such as `{*slug}`, are matched before routes with higher precedence, such as `/customer/{id}`.
### New behavior
The new behavior in ASP.NET Core 5.0.1 or later more closely matches the routing behavior defined in ASP.NET Core apps, where the framework computes and establishes the route precedence for each segment first and only uses the length of the route to break ties as a secondary criteria.
### Reason for change
The original behavior is considered a bug in the implementation because our goal is for the Blazor routing system to behave in the same way as the ASP.NET Core routing system for the subset of features supported by Blazor routing.
### Recommended action
Add the `PreferExactMatches` attribute to the `Router` component in the `App.razor` file to opt into the correct behavior:
*The guidance in this section applies to both Blazor hosting models. Sections following this section provide additional guidance specific to hosting models and app types. Apply the guidance from all relevant sections to your app.*
1. In `wwwroot/index.html` of a Blazor WebAssembly app or the `Pages/_Host.cshtml` of a Blazor Server app, add a `<link>` element to the `<head>` element for styles. In the following `<link>` element `href` attribute values, the placeholder `{ASSEMBLY NAME}` is the app's assembly name.
1. Include a new namespace in the app's `_Imports.razor` file for [component virtualization](xref:blazor/components/virtualization), <xref:Microsoft.AspNetCore.Components.Web.Virtualization?displayProperty=fullName>. The following `_Imports.razor` files show the default namespaces in apps generated from the Blazor project templates. The placeholder `{ASSEMBLY NAME}` is the app's assembly name.
1. In the `MainLayout` component (`Shared/MainLayout.razor`), surround the component's HTML markup with a `<div>` element that has a `class` attribute set to `page`:
1. The latest base `wwwroot/css/app.css` file of a Blazor WebAssembly app or `wwwroot/css/site.css` file of a Blazor Server app includes the following styles. Remove extra styles leaving the following styles and any that you've added to the app.
The following stylesheet only includes base styles and does **not** include custom styles added by the developer:
> The preceding example doesn't show the `@import` directive for Open Iconic icons (`open-iconic-bootstrap.css`), provided by the Blazor project template. [Open Iconic](https://github.com/iconic/open-iconic) was abandoned by its maintainers.
Follow the guidance in the preceding [Update Blazor WebAssembly and Blazor Server projects](#update-blazor-webassembly-and-blazor-server-projects) section.
1. Remove the package reference to [Microsoft.AspNetCore.Components.WebAssembly.Build](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Build):
Follow the guidance in the preceding [Update Blazor WebAssembly and Blazor Server projects](#update-blazor-webassembly-and-blazor-server-projects) and [Update Blazor WebAssembly projects](#update-blazor-webassembly-projects) sections.
Follow the guidance in the preceding [Update Blazor WebAssembly and Blazor Server projects](#update-blazor-webassembly-and-blazor-server-projects) and [Update Blazor WebAssembly projects](#update-blazor-webassembly-projects) sections.
### Standalone Blazor WebAssembly app with Azure Active Directory (AAD) B2C
Follow the guidance in the preceding [Update Blazor WebAssembly and Blazor Server projects](#update-blazor-webassembly-and-blazor-server-projects) and [Update Blazor WebAssembly projects](#update-blazor-webassembly-projects) sections.
Follow the guidance in the preceding [Update Blazor WebAssembly and Blazor Server projects](#update-blazor-webassembly-and-blazor-server-projects) and [Update Blazor WebAssembly projects](#update-blazor-webassembly-projects) sections.
The *`Client`* app registration of a hosted Blazor solution that uses AAD or AAD B2C for user authentication should use a **Single-page application** Azure Apps platform configuration.
In the Azure portal *`Client`* app registration **Authentication** blade:
1. Remove the **Web** platform configuration.
1. Add a **Single-page application** platform configuration with the app's redirect URI.
1. Disable **Implicit grant** for **Access tokens** and **ID tokens**.
Additionally, *`Server`* projects that authenticate users to client Blazor WebAssembly apps with Microsoft Entra ID (ME-ID) or B2C should adopt new Microsoft Identity v2.0 packages:
After migrating the app or solution to .NET 5, clean and rebuild the app or solution. If package incompatibilities exist between new package references and cached packages:
1. Clear NuGet package caches by executing the following [`dotnet nuget locals`](/dotnet/core/tools/dotnet-nuget-locals) command in a command shell:
```dotnetcli
dotnet nuget locals --clear all
```
1. Clean and rebuild the app or solution.
### Troubleshoot
Follow the *Troubleshoot* guidance at the end of the Blazor WebAssembly security topic that applies to your app:
Standalone Blazor WebAssembly apps:
* [General guidance for OIDC providers and the WebAssembly Authentication Library](xref:blazor/security/webassembly/standalone-with-authentication-library)
After upgrading a Blazor WebAssembly app that uses AAD for authentication, you may receive the following error on the login callback to the app after the user signs in with AAD:
If the project's `wwwroot/index.html` (Blazor WebAssembly) or `Pages/_Host.cshtml` (Blazor Server) contains a stylesheet `<link>` element for `scoped.styles.css` from an earlier 5.0 preview release, remove the `<link>` tag:
In the project file, update each [Microsoft.AspNetCore.*](https://www.nuget.org/packages?q=Microsoft.AspNetCore.*), [Microsoft.EntityFrameworkCore.*](https://www.nuget.org/packages?q=Microsoft.EntityFrameworkCore.*), [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:
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:
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).
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 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:
Apps that rely on the presence of the `ComplexTypeModelBinderProvider` in the `ModelBinderProviders` collection need to reference the new binder provider:
The ASP.NET Core 3.1 templates that include an option for individual user accounts generate a call to <xref:Microsoft.AspNetCore.Builder.DatabaseErrorPageExtensions.UseDatabaseErrorPage%2A>. `UseDatabaseErrorPage` is now obsolete and should be replaced with a combination of `AddDatabaseDeveloperPageExceptionFilter` and `UseMigrationsEndPoint`, as shown in the following code:
```diff
public void ConfigureServices(IServiceCollection services)
## Package reference changes affecting some NuGet packages
With the migration of some `Microsoft.Extensions.*` NuGet packages from the [dotnet/extensions](https://github.com/dotnet/extensions) repository to [dotnet/runtime](https://github.com/dotnet/runtime), as described in [Migrating dotnet/extensions content to dotnet/runtime and dotnet/aspnetcore (aspnet/Announcements #411)](https://github.com/aspnet/Announcements/issues/411), packaging changes are being applied to some of the migrated packages. These changes often result in namespace changes for .NET API.
The following wiki pages explain how to migrate Microsoft.Identity.Web from ASP.NET Core 3.1 to 5.0:
* [Microsoft.Identity.Web in web apps](https://github.com/AzureAD/microsoft-identity-web/wiki/web-apps)
* [Microsoft.Identity.Web in web APIs](https://github.com/AzureAD/microsoft-identity-web/wiki/web-apis)
The following tutorials also explain the migration:
* [An ASP.NET Core Web app signing-in users with the Microsoft identity platform in your organization](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC/1-1-MyOrg#option-2-create-the-sample-from-the-command-line). See **Option 2: Create the sample from the command line**.
* [Sign-in a user with the Microsoft Identity Platform in a WPF Desktop application and call an ASP.NET Core Web API](https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2/tree/master/1.%20Desktop%20app%20calls%20Web%20API#how-was-the-code-created). See **How was the code created**.
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.
