從 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"
  }
}

更新目標 Framework

將專案檔的目標 Framework Moniker (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 搭配新的最小主控模型，請參閱使用啟動搭配新的最小主控模型。

若要使用 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 的應用程式，請更新 DockerfileFROM 陳述式和指令碼。 使用包含 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 值是以模型繫結為本地時間，其中時區是由伺服器決定。 繫結自輸入格式設定 (JSON) 的 DateTime 值和 DateTimeOffset 值已繫結為 UTC 時區。

在 ASP.NET Core 5.0 和更新版本中，模型繫結會一致地繫結 DateTime 值與 UTC 時區。

若要保留先前的行為，請移除 Startup.ConfigureServices 中的 DateTimeModelBinderProvider：

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

ComplexObjectModelBinderProvider \ ComplexObjectModelBinder 取代 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();
    }

如需詳細資訊，請參閱 Obsoleting DatabaseErrorPage 中介軟體 (dotnet/aspnetcore #24987)。

ASP.NET Core 模組 (ANCM)

如果在安裝 Visual Studio 時，ASP.NET Core 模組 (ANCM) 不是選取的元件，或者如果系統上已安裝舊版的 ANCM，請下載最新的 .NET Core 裝載套件組合安裝程式 (直接下載)，並執行安裝程式。 如需詳細資訊，請參閱裝載組合套件。

應用程式名稱變更

在 .NET 6 中，WebApplicationBuilder 會將內容根路徑正規化，使其以 DirectorySeparatorChar 結尾。 大部分從 HostBuilder 或 WebHostBuilder 移轉的應用程式都不會有相同的應用程式名稱，因為這些應用程式並未正規化。 如需詳細資訊，請參閱 SetApplicationName

檢閱中斷性變更

請參閱下列資源：