通过

.NET Core 3.1 中的重大变化

如果要迁移到 .NET Core 版本 3.1 或 ASP.NET Core，本文中列出的重大更改可能会影响你的应用。

ASP.NET Core

HTTP：浏览器的 SameSite 更改会影响身份验证

某些浏览器（如 Chrome 和 Firefox）对其 Cookie 的实现 SameSite 进行了重大更改。 这些更改会影响远程身份验证方案，例如 OpenID Connect 和 WS 联合身份验证，必须通过发送 SameSite=None来选择退出。 但是，SameSite=None 在 iOS 12 和某些较旧版本的其他浏览器中无法正常工作。 应用需要检测这些版本并省略 SameSite。

有关此问题的讨论，请参阅 dotnet/aspnetcore#14996。

引入的版本

3.1 预览版 1

旧行为

SameSite 是 2016 年 HTTP Cookie 的草稿标准扩展。 它旨在减少跨站点请求伪造 (CSRF)。 这最初设计为服务器通过添加新参数选择加入的功能。 ASP.NET Core 2.0 添加了对 SameSite 的初步支持。

新行为

谷歌提出了一个新的草案标准，不向后兼容。 标准将默认模式更改为 Lax 并添加新条目 None 以选择退出。Lax 适合大多数应用的 Cookie，但是，它会中断跨站点场景，如 OpenID Connect 和 WS-Federation 登录。 由于请求的流动方式存在差异，因此大多数 OAuth 登录名不会受到影响。 新 None 参数会导致实现先前草稿标准的客户端（例如 iOS 12）的兼容性问题。 Chrome 80 将包括更改。 关于 Chrome 产品发布时间线，请参阅 SameSite 更新。

ASP.NET Core 3.1 已更新以实现新 SameSite 行为。 更新重新定义了SameSiteMode.None的行为，使其发出SameSite=None，并添加了一个新值SameSiteMode.Unspecified以省略SameSite属性。 现在，所有 Cookie API 都默认为 Unspecified，但某些使用 Cookie 的组件设置了更特定于其方案的值，例如 OpenID Connect 相关性和 nonce Cookie。

有关此区域中的其他最近更改，请参阅 HTTP：某些 Cookie SameSite 默认值更改为“无”。 在 ASP.NET Core 3.0 中，大多数默认值已从 SameSiteMode.LaxSameSiteMode.None 更改为（但仍使用以前的标准）。

更改原因

浏览器和规范的变更如前文所述。

与远程站点交互的应用（例如通过第三方登录）需要：

  • 在多个浏览器中测试这些方案。
  • 应用支持旧版浏览器中讨论的 Cookie 策略浏览器探查缓解措施。

有关测试和浏览器嗅探说明，请参阅以下部分。

确定你是否受到影响

使用可以选择加入新行为的客户端版本测试 Web 应用。 Chrome、Firefox 和 Microsoft Edge Chromium 都具备可用于测试的新可选特性标志。 应用修补程序（尤其是 Safari）后，验证应用是否与较旧的客户端版本兼容。 有关详细信息，请参阅 支持较旧的浏览器。

铬

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 当前没有用于测试新规范行为的选择加入标志。

火狐浏览器

您可以通过在about:config页面上选择启用功能标志network.cookie.sameSite.laxByDefault，在 Firefox 版本 68 及更高版本中测试对新标准的支持。 在旧版 Firefox 上未报告任何兼容性问题。

Microsoft Edge

虽然 Microsoft Edge 支持旧 SameSite 标准，但从版本 44 起，它与新标准没有任何兼容性问题。

Microsoft Edge Chromium

功能标志为 edge://flags/#same-site-by-default-cookies. 使用 Microsoft Edge Chromium 78 进行测试时，不会发现兼容性问题。

电子

Electron 的版本包括较旧版本的 Chromium。 例如，Microsoft Teams 使用的 Electron 版本为 Chromium 66，它显示了较旧的行为。 请对产品使用的 Electron 版本进行自己的兼容性测试。 有关详细信息，请参阅 支持较旧的浏览器。

支持较旧的浏览器

2016 SameSite 年标准要求将未知值视为 SameSite=Strict 值。 因此，任何支持原始标准的旧版浏览器都可能在检测到 SameSite 属性具有 None 值时中断。 如果 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 行为。 将以下 JSON 添加到项目中 runtimeconfig.template.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 SDK 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

无

SDK

根文件夹中的工具清单

Windows 窗体

已删除的控件

从 .NET Core 3.1 开始，某些 Windows 窗体控件不再可用。

更改描述

从 .NET Core 3.1 开始，各种 Windows 窗体控件不再可用。 .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
主菜单 MenuStrip
菜单 ToolStripDropDown、ToolStripDropDownMenu 菜单项集合
MenuItem ToolStripMenuItem
ToolBar ToolStrip 工具栏外观
工具栏按钮 ToolStripButton ToolBarButtonClickEventArgs、ToolBarButtonClickEventHandler、ToolBarButtonStyle、ToolBarTextAlign

类别

Windows 窗体

受影响的 API

如果显示工具提示，则不引发 CellFormatting 事件

现在，当鼠标悬停和通过键盘选择时，DataGridView 将显示单元格的文本和错误工具提示。 如果显示了工具提示，则不会触发 DataGridView.CellFormatting 事件。

更改描述

在 .NET Core 3.1 之前，当鼠标悬停在单元格上时，如果 DataGridView 属性被设置为 ShowCellToolTips，那么 true 会显示该单元格文本的工具提示和错误信息。 当通过键盘选择单元格时，不会显示工具提示（例如，通过使用 Tab 键、快捷键或箭头导航）。 如果用户编辑了一个单元格，然后，当 DataGridView 仍处于编辑模式时，将鼠标悬停在未 ToolTipText 设置属性的单元格上，则会引发一个 CellFormatting 事件来设置单元格的文本的格式，以便在单元格中显示。

为满足辅助功能标准，自 .NET Core 3.1 起，将 DataGridView 属性设置为 ShowCellToolTips 的 true 不仅在鼠标悬停在单元格上时会显示单元格文本和错误的工具提示，而且在通过键盘选择单元格时也会显示。 由于这一变更，如果鼠标在 CellFormatting 处于编辑模式时悬停在未设置 属性的单元格上，不会引发 ToolTipText 事件DataGridView。 不引发该事件的原因是鼠标悬停的单元格的内容显示为工具提示，而不是显示在单元格中。

引入的版本

3.1

重构任何依赖于 CellFormatting 事件的代码，而此时 DataGridView 正处于编辑模式。

类别

Windows 窗体

受影响的 API

没有

另请参阅

  • Last updated on