从 ASP.NET Core 3.1 迁移到 6.0

  • 项目

本文介绍如何将现有 ASP.NET Core 3.1 项目更新为 ASP.NET Core 6.0。 要从 ASP.NET Core 5.0 升级到 6.0，请参阅从 ASP.NET Core 5.0 迁移到 6.0。

先决条件

更新 global.json 中的 .NET SDK 版本

如果依靠 global.json 文件来定向于特定 .NET SDK 版本，请将 version 属性更新为已安装的 .NET 6.0 SDK 版本。 例如：

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

更新目标框架

将项目文件的目标框架名字对象 (TFM) 更新为 net6.0：

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

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

</Project>

更新包引用

在项目文件中，将每个 Microsoft.AspNetCore.*、Microsoft.EntityFrameworkCore.*、Microsoft.Extensions.* 和 System.Net.Http.Json 包引用的 Version 属性更新为 6.0.0 或更高版本。 例如：

<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 和 obj 文件夹

可能需要删除 bin 和 obj 文件夹。 运行 dotnet nuget locals --clear all 以清除 NuGet 包缓存。

最小托管模型

ASP.NET Core 模板使用新的最小托管模型来生成代码。 最小托管模型将 Startup.cs 和 Program.cs 合并到一个 Program.cs 文件中。 ConfigureServices 和 Configure 不再使用。 从 ASP.NET Core 3.1 迁移到 6.0 的应用不需要使用最小托管模型，而是使用 Startup 并且完全支持 ASP.NET Core 3.1 模板使用的通用主机。

要将 Startup 与新的最小托管模型一起使用，请参阅将 Startup 与新的最小托管模型一起使用。

若要使用由 ASP.NET Core 6.0 模板使用的以下模式迁移到新的最小托管模型，请参阅在 ASP.NET Core 6.0 中迁移到新的最小托管模型的代码示例和从 ASP.NET Core 5.0 迁移到 6.0

更新 Razor 类库 (RCL)

迁移 Razor 类库 (RCL)，以利用 ASP.NET Core 6.0 中引入的新 API 或功能。

更新面向组件的 RCL：

  1. 更新项目文件中的以下属性：

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

  2. 将其他包更新到最新版本。 可在 NuGet.org 中找到最新版本。

若要更新面向 MVC 的 RCL，请更新项目文件中的以下属性：

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

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

Blazor

要为 Blazor 应用采用所有 5.0 功能 和 6.0 功能，建议采用以下过程：

  • 通过一个 Blazor 项目模板创建新的 6.0 Blazor 项目。 有关详细信息，请参阅用于 ASP.NET Core Blazor 的工具。
  • 将应用的组件和代码移动到 6.0 应用，进行修改以采用新的 5.0 和 6.0 功能。

更新 Docker 映像

对于使用 Docker 的应用，请更新 Dockerfile FROM 语句和脚本。 使用包含 ASP.NET Core 6.0 运行时的基础映像。 请考虑 ASP.NET Core 3.1 和 6.0 之间的以下 docker pull 命令差异：

- docker pull mcr.microsoft.com/dotnet/core/aspnet:3.1
+ docker pull mcr.microsoft.com/dotnet/aspnet:6.0

在迁移到“.NET”作为产品名称的过程中，Docker 映像将从 mcr.microsoft.com/dotnet/core 存储库移动到 mcr.microsoft.com/dotnet。 有关详细信息，请参阅 .NET 5.0 - Docker 存储库名称更改 (dotnet/dotnet-docker #1939)。

ASP.NET Core MVC 和 Razor Pages 中的模型绑定更改

DateTime 值作为 UTC 时间进行模型绑定

在 ASP.NET Core 3.1 及更低版本中，DateTime 值作为本地时间进行模型绑定，其中时区由服务器决定。 DateTime 值绑定自输入格式 (JSON) 并且 DateTimeOffset 值绑定作为 UTC 时区。

在 ASP.NET Core 5.0 及更高版本中，模型绑定将 DateTime 值与 UTC 时区一致地绑定在一起。

若要保留之前的行为，请删除 Startup.ConfigureServices 中的 DateTimeModelBinderProvider：

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

ComplexObjectModelBinderProvider \ ComplexObjectModelBinder replace ComplexTypeModelBinderProvider \ ComplexTypeModelBinder

若要添加对模型绑定 C# 9 记录类型的支持，ComplexTypeModelBinderProvider 为：

  • 注释为已过时。
  • 默认情况下不再注册。

依赖于 ModelBinderProviders 集合中存在的 ComplexTypeModelBinderProvider 的应用需要引用新的绑定器提供程序：

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

UseDatabaseErrorPage 已过时

包含用于单个用户帐户的选项的 ASP.NET Core 3.1 模板会生成对 UseDatabaseErrorPage 的调用。 UseDatabaseErrorPage 现已过时，应替换为以下代码中所示的 AddDatabaseDeveloperPageExceptionFilter 和 UseMigrationsEndPoint 的组合：

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();
    }

有关详细信息，请参阅不再使用 DatabaseErrorPage 中间件 (dotnet/aspnetcore #24987)。

ASP.NET Core 模块 (ANCM)

如果在安装 Visual Studio 时未选择 ASP.NET Core 模块 (ANCM) 组件，或者系统上安装了 ANCM 的早期版本，请下载最新的 .NET Core 托管捆绑包安装程序（直接下载）并运行该安装程序。 有关详细信息，请参阅托管捆绑包。

应用程序名称更改

在 .NET 6 中，WebApplicationBuilder 会将内容根路径规范化以 DirectorySeparatorChar 结尾。 大多数从HostBuilder或WebHostBuilder迁移的应用不会共享相同的应用名称，因为它们没有规范化。 有关详细信息，请参阅SetApplicationName

查看中断性变更

请参阅以下资源：