aspnetcore/migration/31-to-60.md
This article explains how to update an existing ASP.NET Core 3.1 project to ASP.NET Core in .NET 6. To upgrade from ASP.NET Core in .NET 5 to .NET 6, see xref:migration/50-to-60.
global.jsonIf you rely upon a global.json file to target a specific .NET SDK version, update the version property to the .NET 6 SDK version that's installed. For example:
{
"sdk": {
- "version": "3.1.200"
+ "version": "6.0.100"
}
}
<a name="tf"></a>
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>
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>
bin and obj foldersYou may need to delete the bin and obj folders. Run dotnet nuget locals --clear all to clear the NuGet package cache.
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 .NET 6 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 in .NET 6 templates, see Code samples migrated to the new minimal hosting model in ASP.NET Core in .NET 6 and Migrate from ASP.NET Core in .NET 5 to .NET 6
Migrate Razor class libraries (RCLs) to take advantage of new APIs or features that are introduced as part of ASP.NET Core in .NET 6.
To update a RCL that targets components:
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>
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>
To adopt all of the 5.0 features and 6.0 features for Blazor apps, we recommend the following process:
For apps using Docker, update your Dockerfile FROM statements and scripts. Use a base image that includes the ASP.NET Core in .NET 6 runtime. Consider the following docker pull command difference between ASP.NET Core 3.1 and .NET 6:
- 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).
DateTime values are model bound as UTC timesIn ASP.NET Core 3.1 or 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 .NET 5 or 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 \ ComplexTypeModelBinderTo add support for model binding C# 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:
- var complexModelBinderProvider = options.ModelBinderProviders.OfType<ComplexTypeModelBinderProvider>();
+ var complexModelBinderProvider = options.ModelBinderProviders.OfType<ComplexObjectModelBinderProvider>();
UseDatabaseErrorPage obsoleteThe 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:
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).
Use the articles in Breaking changes in .NET to find breaking changes that might apply when upgrading an app to a newer version of .NET.
For more information, see the following resources:
aspnet/Announcements, 6.0.0 label): Includes breaking and non-breaking information.aspnet/Announcements, 5.0.0 label): Includes breaking and non-breaking information.