從 ASP.NET Core 2.1 移轉到 2.2

發行項
11/06/2024

作者：Scott Addie

本文說明如何將現有的 ASP.NET Core 2.1 專案更新為 ASP.NET Core 2.2。

必要條件

Visual Studio 2019 和 ASP.NET 與 Web 開發工作負載
.NET Core SDK 2.2 或更新版本

警告

如果您使用 Visual Studio 2017，請參閱 dotnet/sdk 問題 #3124 \(英文\)，以取得未使用 Visual Studio 的 .NET Core SDK 版本相關資訊。

更新 Target Framework Moniker (TFM)

以 .NET Core 為目標的專案應該使用版本大於或等於 .NET Core 2.2 的 TFM。在專案檔中，使用 netcoreapp2.2 更新 <TargetFramework> 節點的內部文字：

<TargetFramework>netcoreapp2.2</TargetFramework>

以 .NET Framework 為目標的專案可能會繼續使用版本大於或等於 .NET Framework 4.6.1 的 TFM：

<TargetFramework>net461</TargetFramework>

採用 IIS 內含式裝載模型

若要採用 IIS 的內含式裝載模型，請在專案檔中將值為 InProcess 的 <AspNetCoreHostingModel> 屬性新增至 <PropertyGroup>：

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

以 .NET Framework 為目標的 ASP.NET Core 應用程式不支援內含式裝載模型。

如需詳細資訊，請參閱適用於 IIS 的 ASP.NET Core 模組 (ANCM)。

更新自訂 web.config 檔案

對於使用專案根目錄中自訂 web.config 檔案，以產生其所發佈 web.config 檔案的專案：

在新增 ASP.NET Core 模組 (name="aspNetCore") 的 <handlers> 項目中，將 modules 屬性值從 AspNetCoreModule 變更為 AspNetCoreModuleV2。
在 <aspNetCore> 元素中，新增裝載模型屬性 (hostingModel="InProcess")。

如需詳細資訊和範例 web.config 檔案，請參閱 IIS 的 ASP.NET Core 模組 (ANCM)。

更新套件參考

如果以 .NET Core 為目標，請移除專案檔中的中繼套件參考 Version 屬性。包含 Version 屬性會產生下列警告：

A PackageReference to 'Microsoft.AspNetCore.App' specified a Version of `2.2.0`. Specifying the version of this package is not recommended. For more information, see https://aka.ms/sdkimplicitrefs

如需詳細資訊，請參閱 ASP.NET Core 的 Microsoft.AspNetCore.App 中繼套件。

中繼套件參考應該類似下列 <PackageReference /> 節點：

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

如果以 .NET Framework 為目標，請將每個套件參考的 Version 屬性更新為 2.2.0 或更新版本。以下是以 .NET Framework 為目標的典型 ASP.NET Core 2.2 專案中的套件參考：

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.CookiePolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.HttpsPolicy" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.2.0" />
</ItemGroup>

如果參考 Microsoft.AspNetCore.Razor.Design 套件，請將其 Version 屬性更新為 2.2.0 或更新版本。無法這樣做會產生下列錯誤：

Detected package downgrade: Microsoft.AspNetCore.Razor.Design from 2.2.0 to 2.1.2. Reference the package directly from the project to select a different version.

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

如果您的解決方案依賴 global.json 檔案而以特定的 .NET Core SDK 版本為目標，請將其 version 屬性更新為您電腦上安裝的 2.2 版：

{
  "sdk": {
    "version": "2.2.100"
  }
}

更新啟動設定

如果使用 Visual Studio Code，請更新專案的啟動設定檔 (.vscode/launch.json)。 program 路徑應該參考新的 TFM：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${workspaceFolder}/bin/Debug/netcoreapp2.2/test-app.dll",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
            "internalConsoleOptions": "openOnSessionStart",
            "launchBrowser": {
                "enabled": true,
                "args": "${auto-detect-url}",
                "windows": {
                    "command": "cmd.exe",
                    "args": "/C start ${auto-detect-url}"
                },
                "osx": {
                    "command": "open"
                },
                "linux": {
                    "command": "xdg-open"
                }
            },
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            },
            "sourceFileMap": {
                "/Views": "${workspaceFolder}/Views"
            }
        },
        {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach",
            "processId": "${command:pickProcess}"
        }
    ]
}

更新 Kestrel 設定

如果應用程式藉由在 Program 類別的 CreateWebHostBuilder 方法中呼叫 CreateDefaultBuilder 來呼叫 UseKestrel，請呼叫 ConfigureKestrel 來設定 Kestrel 伺服器，而不是 UseKestrel，以便避免與 IIS 內含式裝載模型發生衝突：

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        });

如果應用程式未呼叫 CreateDefaultBuilder，並在 Program 類別中手動建置主機，請在呼叫 ConfigureKestrel 之前呼叫 UseKestrel：

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseKestrel()
        .UseIISIntegration()
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        })
        .Build();

    host.Run();
}

如需詳細資訊，請參閱 ASP.NET Core 中的 Kestrel Web 伺服器。

更新相容性版本

將 Startup.ConfigureServices 中的相容性版本更新為 Version_2_2：

services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

更新 CORS 原則

在 ASP.NET Core 2.2 中，如果原則允許任何來源並允許認證，則 CORS 中介軟體會以萬用字元來源 (*) 回應。指定萬用字元來源 (*) 時不支援認證，且瀏覽器將不允許 CORS 要求。如需詳細資訊，包括更正用戶端問題的選項，請參閱 MDN Web 文件。

若要在伺服器上更正此問題，請採取下列其中一個動作：

將 CORS 原則修改為不再允許認證。也就是說，在設定原則時，請移除對 AllowCredentials 的呼叫。
如果需要認證，CORS 要求才能成功，請修改原則以指定允許的主機。例如，使用 builder.WithOrigins("https://api.example1.com", "https://example2.com") 而不是使用 AllowAnyOrigin。

更新 Docker 映像

下表顯示 Docker 映像標籤變更：

2.1	2.2
`microsoft/dotnet:2.1-aspnetcore-runtime`	`mcr.microsoft.com/dotnet/core/aspnet:2.2`
`microsoft/dotnet:2.1-sdk`	`mcr.microsoft.com/dotnet/core/sdk:2.2`

變更 Dockerfile 中的 FROM 行，以使用上表資料行 2.2 中的新映像標籤。

使用 IIS 內含式裝載時，在 Visual Studio 中手動建置

Visual Studio 的在瀏覽器要求上自動建置體驗不會與 IIS 內含式裝載模型搭配運作。使用內含式裝載時，您必須手動重建專案。規劃在 Visual Studio 的未來版本改善此體驗。

更新記錄程式碼

建議的記錄設定程式碼未從 2.1 變更為 2.2，但 2.1 中仍運作的一些 1.x 編碼模式再也無法在 2.2 中運作。

如果您的應用程式在 Startup 類別中執行記錄提供者初始化、篩選和組態載入，請將該程式碼移至 Program.Main：

提供者初始化：

1.x 範例：

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole();
}

2.2 範例：


public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConsole();
        })
        // ...
}

篩選：

1.x 範例：

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(LogLevel.Information);
    // or
    loggerFactory.AddConsole((category, level) => 
        category == "A" || level == LogLevel.Critical);
}

2.2 範例：

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConsole()
                   .AddFilter<ConsoleLoggerProvider>
                       (category: null, level: LogLevel.Information)
                   // or
                   .AddFilter<ConsoleLoggerProvider>
                       ((category, level) => category == "A" ||
                           level == LogLevel.Critical)
            );
        })
        // ...
}

組態載入：

1.x 範例：

public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration);
}

2.2 範例：

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
        })
        // ...
}

如需詳細資訊，請參閱 .NET Core 與 ASP.NET Core 中的記錄

ASP.NET Core 模組 (ANCM)

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

共用方式為

從 ASP.NET Core 2.1 移轉到 2.2

必要條件

更新 Target Framework Moniker (TFM)

採用 IIS 內含式裝載模型

更新自訂 web.config 檔案

更新套件參考

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

更新啟動設定

更新 Kestrel 設定

更新相容性版本

更新 CORS 原則

更新 Docker 映像

使用 IIS 內含式裝載時，在 Visual Studio 中手動建置

更新記錄程式碼

ASP.NET Core 模組 (ANCM)

其他資源

其他資源