Edit

Migrate from ASP.NET Core 3.1 to 6.0

  • Article

This article explains how to update an existing ASP.NET Core 3.1 project to ASP.NET Core 6.0. To upgrade from ASP.NET Core 5.0 to 6.0, see Migrate from ASP.NET Core 5.0 to 6.0.

Prerequisites

Update .NET SDK version in global.json

If you rely upon a global.json file to target a specific .NET SDK version, update the version property to the .NET 6.0 SDK version that's installed. For example:

{
  "sdk": {
-    "version": "3.1.200"
+    "version": "6.0.100"
  }
}

Update the target framework

Update the project file's Target Framework Moniker (TFM) to net6.0:

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

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

</Project>

Update package references

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

<ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.JsonPatch" Version="3.1.6" />
-    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" 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="6.0.0" />
+    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="6.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" Version="6.0.0" />
+    <PackageReference Include="System.Net.Http.Json" Version="6.0.0" />
</ItemGroup>

Delete bin and obj folders

You may need to delete the bin and obj folders. Run dotnet nuget locals --clear all to clear the NuGet package cache.

Minimal hosting model

The ASP.NET Core templates generate code using the new minimal hosting model. The minimal hosting model unifies Startup.cs and Program.cs into a single Program.cs file. ConfigureServices and Configure are no longer used. Apps migrating from ASP.NET Core 3.1 to 6.0 don't need to use the minimal hosting model, using Startup and the Generic Host used by the ASP.NET Core 3.1 templates is fully supported.

To use Startup with the new minimal hosting model, see Use Startup with the new minimal hosting model.

To migrate to the new minimal hosting model using the following pattern used by the ASP.NET Core 6.0 templates, see Code samples migrated to the new minimal hosting model in ASP.NET Core 6.0 and Migrate from ASP.NET Core 5.0 to 6.0

Update Razor class libraries (RCLs)

Migrate Razor class libraries (RCLs) to take advantage of new APIs or features that are introduced as part of ASP.NET Core 6.0.

To update a RCL that targets components:

  1. Update the following properties in the project file:

    <Project Sdk="Microsoft.NET.Sdk.Razor">
  <PropertyGroup>
-     <TargetFramework>netstandard2.0</TargetFramework>
-     <RazorLangVersion>3.0</RazorLangVersion>
+     <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  2. Update other packages to their latest versions. The latest versions can be found at NuGet.org.

To update an RCL targeting MVC, update the following properties in the project file:

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

  <PropertyGroup>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net6.0</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

Blazor

To adopt all of the 5.0 features and 6.0 features for Blazor apps, we recommend the following process:

  • Create a new 6.0 Blazor project from one of the Blazor project templates. For more information, see Tooling for ASP.NET Core Blazor.
  • Move the app's components and code to the 6.0 app making modifications to adopt the new 5.0 and 6.0 features.

Update Docker images

For apps using Docker, update your Dockerfile FROM statements and scripts. Use a base image that includes the ASP.NET Core 6.0 runtime. Consider the following docker pull command difference between ASP.NET Core 3.1 and 6.0:

- docker pull mcr.microsoft.com/dotnet/core/aspnet:3.1
+ docker pull mcr.microsoft.com/dotnet/aspnet:6.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 .NET 5.0 - Docker Repo Name Change (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 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>();

UseDatabaseErrorPage obsolete

The ASP.NET Core 3.1 templates that include an option for individual user accounts generate a call to UseDatabaseErrorPage. UseDatabaseErrorPage is now obsolete and should be replaced with a combination of AddDatabaseDeveloperPageExceptionFilter and UseMigrationsEndPoint, as shown in the following code:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(
            Configuration.GetConnectionString("DefaultConnection")));
+   services.AddDatabaseDeveloperPageExceptionFilter();
    services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
        .AddEntityFrameworkStores<ApplicationDbContext>();
    services.AddRazorPages();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
+       app.UseMigrationsEndPoint();
-       app.UseDatabaseErrorPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

For more information, see Obsoleting DatabaseErrorPage middleware (dotnet/aspnetcore #24987).

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.

Application name change

In .NET 6, WebApplicationBuilder normalizes the content root path to end with a DirectorySeparatorChar. Most apps migrating from HostBuilder or WebHostBuilder won't have the same app name because they aren't normalized. For more information, see SetApplicationName

Review breaking changes

See the following resources: