.NET Core 3.1 的中斷性變更

  • 發行項

如果您即將移轉至 .NET Core 或 ASP.NET Core 3.1 版，本文列出的中斷性變更可能影響您的應用程式。

ASP.NET Core

HTTP：瀏覽器 SameSite 變更會影響驗證

部分瀏覽器 (例如 Chrome 及 Firefox) 針對 SameSite 的 Cookie 實作進行中斷性變更。 變更內容會影響遠端驗證情節，例如 OpenID Connect 和 WS-Federation，二者皆必須透過傳送 SameSite=None 退出宣告。 不過，SameSite=None 會在 iOS 12 及其他瀏覽器的部分較舊版本上中斷。 應用程式必須探查這些版本，並忽略 SameSite。

如需此問題的討論，請參閱 dotnet/aspnetcore#14996。

導入的版本

3.1 預覽版 1

舊的行為

SameSite 是 HTTP Cookie 的 2016 草稿標準延伸模組。 其用意在於降低跨網站偽造要求 (CSRF) 的風險。 原初設計時，這項功能需伺服器新增參數才能加入。 ASP.NET Core 2.0 針對 SameSite 新增初始支援。

新的行為

Google 提議了不具回溯相容性的新版草稿標準。 這項標準會改變 Lax 的預設模式並增加新項目 None 來退出宣告。Lax 已可滿足多數應用程式 Cookie 的需求，但會使跨網站情節 (例如 OpenID Connect 和 WS-Federation 登入) 中斷。 由於要求流程的差異，多數 OAuth 登入不會受到影響。 針對實作之前草稿標準 (例如 iOS 12) 的用戶端，新的 None 參數會造成相容性問題。 Chrome 80 將包含變更內容。 請參閱 SameSite Updates 了解 Chrome 產品啟動時間表。

ASP.NET Core 3.1 已更新來實作新的 SameSite 行為。 更新內容重新定義了 SameSiteMode.None 的行為來發出 SameSite=None，並增加新的 SameSiteMode.Unspecified 值來忽略 SameSite 屬性。 現在所有 Cookie API 預設為 Unspecified，不過部分使用 Cookie 的元件會針對各自的情節設定專特的值，例如 OpenID Connect 相互關聯及 nonce Cookie。

如需此方面的其他近期變更內容，請參閱 HTTP：部分 Cookie SameSite 預設值變更為 None。 在 ASP.NET Core 3.0 中，多數預設值已從 SameSiteMode.Lax 變更為 SameSiteMode.None (但仍使用先前的標準)。

變更原因

基於前文所述的瀏覽器和規格變更。

與遠端站台互動的應用程式 (例如透過第三方登入者) 必須：

  • 在多個瀏覽器上測試這些情節。
  • 套用支援舊版瀏覽器一節中討論過的 Cookie 原則瀏覽器探查風險降低功能。

如需測試和瀏覽器探查指示，請參閱下列小節。

判斷自己是否受到影響

用可選擇加入新行為的用戶端版本測試您的 Web 應用程式。 Chrome、Firefox 和 Microsoft Edge Chromium 都有可用於測試的新版選擇加入功能旗標。 請於套用修補檔後使用舊版用戶端版本確認應用程式可相容，Safari 尤其需要確認。 如需詳細資訊，請參閱支援舊版瀏覽器。

Chrome

Chrome 78 和更新版本會產生誤導的測試結果。 這些版本已有暫時風險降低功能，能允許兩分鐘內的 Cookie 存在。 啟用適當的測試旗標後，Chrome 76 和 77 就能獲得更精準的結果。 若要測試新行為，請將 chrome://flags/#same-site-by-default-cookies 切換為啟用。 目前已知 Chrome 75 和更早的版本會在使用新的 None 設定時失敗。 如需詳細資訊，請參閱支援舊版瀏覽器。

Google 不提供較舊的 Chrome 版本。 不過，您可下載舊版 Chromium 以供測試。 請遵循下載 Chromium 中的指示。

Safari

Safari 12 嚴格實作先前的草稿，如果系統在 Cookie 中發現新的 None 值，則會失敗。 請務必透過支援舊版瀏覽器中示範的瀏覽器探查程式碼來防範。 務必使用 Microsoft 驗證程式庫 (MSAL)、Active Directory 驗證程式庫 (ADAL) 或任何您正在使用的程式庫測試 Safari 12 和 13，以及 Webkit 型的 OS 式登入。 問題相依於基礎 OS 版本。 目前已知 OSX Mojave 10.14 和 iOS 12 會與新行為發生相容性問題。 升級至 OSX Catalina 10.15 或 iOS 13 能修正這個問題。 目前 Safari 不針對測試新規格行為提供選擇加入旗標。

Firefox

Firefox 支援在 68 和更新版本中測試新標準，方法是在 about:config 分頁上選擇加入並搭配功能旗標 network.cookie.sameSite.laxByDefault。 目前舊版 Firefox 並沒有已知的相容性問題。

Microsoft Edge

雖然 Microsoft Edge 支援舊版 SameSite 標準，從 44 版開始也不再與新標準有任何相容性問題。

Microsoft Edge Chromium

功能旗標為 edge://flags/#same-site-by-default-cookies。 使用 Microsoft Edge Chromium 78 測試時未發現相容性問題。

Electron

Electron 的版本包括舊版 Chromium。 例如，Microsoft Teams 使用的 Electron 版本為展現舊版行為的 Chromium 66。 請用您產品使用的 Electron 版本執行自己的相容性測試。 如需詳細資訊，請參閱支援舊版瀏覽器。

支援舊版瀏覽器

2016 SameSite 標準強制將未知的值視為 SameSite=Strict 值。 因此，任何支援原始標準的舊版瀏覽器，都會在發現有 None 值的 SameSite 屬性時中斷。 如果 Web 應用程式欲支援這些舊版瀏覽器，則必須實作瀏覽器探查功能。 ASP.NET Core 不會為您實作瀏覽器探查功能，因為 User-Agent 要求標頭的值非常不穩定，每週都會改變。 反之，Cookie 原則中的擴充點可讓您新增 User-Agent 特定的邏輯。

在 Startup.cs 中，新增下列程式碼：

private void CheckSameSite(HttpContext httpContext, CookieOptions options)
{
    if (options.SameSite == SameSiteMode.None)
    {
        var userAgent = httpContext.Request.Headers["User-Agent"].ToString();
        // TODO: Use your User Agent library of choice here.
        if (/* UserAgent doesn't support new behavior */)
        {
            options.SameSite = SameSiteMode.Unspecified;
        }
    }
}

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<CookiePolicyOptions>(options =>
    {
        options.MinimumSameSitePolicy = SameSiteMode.Unspecified;
        options.OnAppendCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
        options.OnDeleteCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
    });
}

public void Configure(IApplicationBuilder app)
{
    // Before UseAuthentication or anything else that writes cookies.
    app.UseCookiePolicy();

    app.UseAuthentication();
    // code omitted for brevity
}
退出宣告參數

Microsoft.AspNetCore.SuppressSameSiteNone 相容性參數可讓您暫時退出新的 ASP.NET Core Cookie 行為。 在專案的 runtimeconfig.template.json 檔案中新增下列 JSON：

{
  "configProperties": {
    "Microsoft.AspNetCore.SuppressSameSiteNone": "true"
  }
}
其他版本

相關的 SameSite 修補檔即將為以下項目推出：

  • ASP.NET Core 2.1、2.2 和 3.0
  • Microsoft.Owin 4.1
  • System.Web (適用於 .NET Framework 4.7.2 和更新版本)

類別

ASP.NET

受影響的 API

部署

64 位元 Windows 上的 x86 主機路徑

MSBuild

只傳回最上層套件參考的設計階段組建

從 .NET Core SDKK 3.1.400 開始，RunResolvePackageDependencies 目標只會傳回最上層的套件參考。

導入的版本

.NET Core SDK 3.1.400

變更描述

在舊版 .NET Core SDK 中，RunResolvePackageDependencies 目標會建立下列 MSBuild 項目，其中包含 NuGet 資產檔案的資訊：

  • PackageDefinitions
  • PackageDependencies
  • TargetDefinitions
  • FileDefinitions
  • FileDependencies

Visual Studio 會用這項資料在方案總管中填入 [相依性] 節點。 不過，其資料量可能很大，且除非 [相依性] 節點展開，否則不需要這些資料。

從 .NET Core SDK 3.1.400 版開始，多數這類項目不會經預設產生。 系統只會傳回 Package 型別的項目。 如果 Visual Studio 需要項目來填入 [相依性] 節點，則會直接從資產檔案讀取資訊。

變更原因

之所以推出這項變更，是為了改善 Visual Studio 內的解決方案載入效能。 之前系統會載入所有的套件參考，意即載入許多大部分使用者永遠不會查看的參考。

如果您有相依於這些項目建立的 MSBuild 邏輯，請在專案檔中將 EmitLegacyAssetsFileItems 屬性設為 true。 這項設定能讓先前的行為 (也就是建立所有項目的行為) 繼續進行。

類別

MSBuild

受影響的 API

N/A

SDK

根資料夾中的工具資訊清單

Windows Forms

移除的控制項

從 .NET Core 3.1 開始，將不再提供部分 Windows Forms 控制項。

變更描述

從 .NET Core 3.1 開始，將不再提供多種 Windows Forms 控制項。 .NET Framework 2.0 已推出具備更好設計及支援的替代控制項。 退場的控制項先前已從設計工具的工具箱中移除，但仍可供使用。

系統不再提供下列型別：

導入的版本

3.1

每個移除的控制項都有建議的替代控制項。 如需詳細資訊，請參閱下表：

移除的控制項 (API) 建議的替代項目 移除的相關 API
ContextMenu ContextMenuStrip
DataGrid DataGridView DataGridCell、DataGridRow、DataGridTableCollection、DataGridColumnCollection、DataGridTableStyle、DataGridColumnStyle、DataGridLineStyle、DataGridParentRowsLabel、DataGridParentRowsLabelStyle、DataGridBoolColumn、DataGridTextBox、GridColumnStylesCollection、GridTableStylesCollection、HitTestType
MainMenu MenuStrip
功能表 ToolStripDropDown, ToolStripDropDownMenu MenuItemCollection
MenuItem ToolStripMenuItem
ToolBar ToolStrip ToolBarAppearance
ToolBarButton ToolStripButton ToolBarButtonClickEventArgs、ToolBarButtonClickEventHandler、ToolBarButtonStyle、ToolBarTextAlign

類別

Windows Forms

受影響的 API

如果顯示工具提示，則不會引發 CellFormatting 事件

現在只要將滑鼠懸停其上，或透過鍵盤選取，DataGridView 就會顯示儲存格的文字和錯誤工具提示。 顯示工具提示即代表未引發 DataGridView.CellFormatting 事件。

變更描述

在 .NET Core 3.1 以前，只要將滑鼠懸停在儲存格上，將 ShowCellToolTips 屬性設為 true 的 DataGridView 就會針對儲存格的文字和錯誤顯示工具提示。 用鍵盤選取 (例如使用 Tab 鍵、快速鍵或箭頭瀏覽) 的儲存格不會顯示工具提示。 如果使用者編輯儲存格，且 DataGridView 仍處於編輯模式，則將滑鼠懸停在未設定 ToolTipText 屬性的儲存格上，會引發 CellFormatting 事件來設定儲存格內文字顯示的格式。

為符合協助工具標準，從 .NET Core 3.1 開始，將 ShowCellToolTips 屬性設為 true 的 DataGridView 會針對儲存格的文字和錯誤顯示工具提示；這不僅會發生在滑鼠懸停於儲存格時，透過鍵盤選取也會發生。 由於這項變更，當 DataGridView 處於編輯模式時，若將滑鼠懸停在未設定 ToolTipText 屬性的儲存格上，則不會再引發 CellFormatting 事件。 之所以不會引發事件，是因為所懸停儲存格的內容已顯示為工具提示，而非顯示於儲存格中。

導入的版本

3.1

重構 DataGridView 處於編輯模式時任何相依於 CellFormatting 事件的程式碼。

類別

Windows Forms

受影響的 API

無

另請參閱