從 ASP.NET Core 2.1 移轉至 2.2

發行項
01/28/2023

作者：Scott Addie

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

必要條件

具有ASP.NET 和 Web 開發工作負載的Visual Studio 2019
.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 。在專案檔中，使用 <TargetFramework>netcoreapp2.2 更新節點的內部文字：

<TargetFramework>netcoreapp2.2</TargetFramework>

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

<TargetFramework>net461</TargetFramework>

採用 IIS 進程內裝載模型

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

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

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

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

更新自訂web.config檔案

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

在 <handlers> 新增 ASP.NET Core Module () name="aspNetCore" 的專案中，將 modules 屬性值從 AspNetCoreModule 變更為 AspNetCoreModuleV2 。
在元素中 <aspNetCore> ，將主控模型屬性新增 (hostingModel="InProcess") 。

如需詳細資訊和範例web.config檔案，請參閱ASP.NET Core Module (適用于 IIS 的 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

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

中繼套件參考應該類似下列 <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 。設計套件，將其 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.

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

如果您的解決方案依賴檔案 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 態

如果在類別的CreateWebHostBuilder 方法Program 中呼叫 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
        });

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

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

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

更新相容性版本

將中的 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`

FROM變更Dockerfile中的行，以在上表的 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檔案

更新套件參考

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

更新啟動設定

更新組 Kestrel 態

更新相容性版本

更新 CORS 原則

更新 Docker 映射

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

更新記錄程式碼

ASP.NET Core模組 (ANCM)

其他資源

其他資源

其他資源

從 ASP.NET Core 2.1 移轉至 2.2

必要條件

更新 Target Framework Moniker (TFM)

採用 IIS 進程內裝載模型

更新自訂web.config檔案

更新套件參考

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

更新啟動設定

更新組 Kestrel 態

更新相容性版本

更新 CORS 原則

更新 Docker 映射

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

更新記錄程式碼

ASP.NET Core模組 (ANCM)

其他資源

其他資源

其他資源

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