从 ASP.NET Core 3.1 迁移到 .NET 6

2025-05-28

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

先决条件

带有 ASP.NET 和 Web 开发工作负载的 Visual Studio 2022。
.NET 6 SDK

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

如果依赖 global.json 文件以特定 .NET SDK 版本为目标，请将 version 属性更新为已安装的 .NET 6 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 迁移到 .NET 6 的应用可以不使用最小托管模型，且 ASP.NET Core 3.1 模板中使用的泛型主机也完全受支持。

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

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

更新 Razor 类库 (RCL)

迁移 Razor 类库（RCL），以利用 .NET 6 中作为 ASP.NET Core 的一部分引入的新 API 或功能。

更新面向组件的 RCL：

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

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

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

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

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

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

Blazor

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

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

更新 Docker 映像

对于使用 Docker 的应用，请更新DockerfileFROM 语句和脚本。使用包含 .NET 6 运行时中的 ASP.NET Core 的基本映像。请考虑 ASP.NET Core 3.1 和 .NET 6 之间的以下命令 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 时区。

在 .NET 5 或更高版本中，模型绑定将值与 UTC 时区一致地绑定 DateTime 。

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

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

`ComplexObjectModelBinderProvider` \ `ComplexObjectModelBinder` 取代 `ComplexTypeModelBinderProvider` \ `ComplexTypeModelBinder`

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

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

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

- 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

查看中断性变更

请参阅以下资源：

Identity：已更改 UI 的默认 Bootstrap 版本
从版本 3.1 迁移到 5.0 的重大更改。 ASP.NET Core 和 Entity Framework Core 也包含在列表中。
从 .NET 5 迁移到 .NET 6 的重大更改：包括 ASP.NET Core 和 Entity Framework Core。
公告 GitHub 存储库（aspnet/Announcements，6.0.0 标签）：包括中断性和非中断性信息。
公告 GitHub 存储库（aspnet/Announcements，5.0.0 标签）：包括中断性和非中断性信息。

通过