從 ASP.NET Core 3.1 移轉至 .NET 6

本文說明如何將現有的 ASP.NET Core 3.1 專案更新為 .NET 6 中的 ASP.NET Core。若要從 .NET 5 中的 ASP.NET Core 升級至 .NET 6，請參閱從 .NET 5 中的 ASP.NET Core 移轉至 .NET 6。

必要條件

Visual Studio 2022 和 ASP.NET 與 Web 開發工作負載。
.NET 6 SDK

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

如果您依賴 global.json 檔案來指定一個特定的 .NET SDK 版本，請將 version 屬性更新為您所安裝的 .NET 6 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 移轉至 .NET 6 的應用程式不需要使用最小裝載模型。使用 Startup 和 ASP.NET Core 3.1 範本所使用的泛型主機是完全支援的。

若要使用 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 陳述式和指令碼。使用包含 ASP.NET Core 運行環境的 .NET 6 基礎映像。請考慮 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 值會模型系結為本地時間，其中時區是由伺服器決定。繫結自輸入格式設定 (JSON) 的 DateTime 數值和 DateTimeOffset 數值已繫結為 UTC 時區。

在 .NET 5 或更新版本中，模型系結會一致地系結 DateTime 與 UTC 時區的值。

若要保留先前的行為，請移除 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();
    }

如需詳細資訊，請參閱 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

重大突破性變更

使用 .NET 中的重大變更中的文章，尋找將應用程式升級至較新版本的 .NET 時可能套用的重大變更。

如需詳細資訊，請參閱下列資源：

公告 GitHub 存放庫（aspnet/Announcements， 6.0.0 label）：包含中斷和非中斷資訊。
公告 GitHub 存放庫（aspnet/Announcements， 5.0.0 label）：包含中斷和非中斷資訊。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-08-28