Критические изменения для перехода с версии 3.0 на 3.1Breaking changes for migration from version 3.0 to 3.1

Если вы выполняете миграцию с версии 3.0 на версию 3.1 .NET Core, ASP.NET Core или EF Core, критические изменения, перечисленные в этой статье, могут повлиять на работу приложения.If you're migrating from version 3.0 to version 3.1 of .NET Core, ASP.NET Core, or EF Core, the breaking changes listed in this article may affect your app.

ASP.NET CoreASP.NET Core

HTTP. Изменения SameSite в браузере влияют на проверку подлинностиHTTP: Browser SameSite changes impact authentication

Для некоторых браузеров, таких как Chrome и Firefox, были внесены критические изменения в реализации SameSite для файлов cookie.Some browsers, such as Chrome and Firefox, made breaking changes to their implementations of SameSite for cookies. Эти изменения негативно влияют на сценарии удаленной проверки подлинности, такие как OpenID Connect и WS-Federation, от которых нужно явно отказаться, отправив SameSite=None.The changes impact remote authentication scenarios, such as OpenID Connect and WS-Federation, which must opt out by sending SameSite=None. Однако SameSite=None нарушает работу других браузеров в iOS 12 и некоторых более старых версий.However, SameSite=None breaks on iOS 12 and some older versions of other browsers. Приложению требуется определить эти версии и опустить SameSite.The app needs to sniff these versions and omit SameSite.

Обсуждение этого вопроса см. на странице dotnet/aspnetcore#14996.For discussion on this issue, see dotnet/aspnetcore#14996.

Представленная версияVersion introduced

3.1 (предварительная версия 1)3.1 Preview 1

Старое поведениеOld behavior

SameSite является расширением проекта стандарта за 2016 год для файлов cookie в HTTP.SameSite is a 2016 draft standard extension to HTTP cookies. Этот атрибут предназначен для устранения подделки межсайтовых запросов (CSRF).It's intended to mitigate Cross-Site Request Forgery (CSRF). Изначально этот атрибут был спроектирован в виде функции, с которой серверы должны были явно соглашаться, добавляя новые параметры.This was originally designed as a feature the servers would opt into by adding the new parameters. В ASP.NET Core 2.0 была добавлена начальная поддержка для SameSite.ASP.NET Core 2.0 added initial support for SameSite.

Новое поведениеNew behavior

Компания Google предложила новый проект стандарта, не имеющий обратной совместимости.Google proposed a new draft standard that isn't backwards compatible. Этот стандарт изменяет режим по умолчанию на Lax и добавляет новую запись None для явного отказа. Lax подходит для файлов cookie большинства приложений, однако нарушает работу межсайтовых сценариев, таких как вход с использованием WS-Federation и OpenID Connect.The standard changes the default mode to Lax and adds a new entry None to opt out. Lax suffices for most app cookies; however, it breaks cross-site scenarios like OpenID Connect and WS-Federation login. Основную часть процедур входа OAuth это не затрагивает из-за различий в последовательностях обработки запросов.Most OAuth logins aren't affected because of differences in how the request flows. Новый параметр None вызывает проблемы совместимости для клиентов, в которых реализован предыдущий проект стандарта (например, iOS 12).The new None parameter causes compatibility problems with clients that implemented the prior draft standard (for example, iOS 12). Эти изменения будут включены в Chrome 80.Chrome 80 will include the changes. Сведения о сроках выпуска продукта Chrome см. в новостях по SameSite.See SameSite Updates for the Chrome product launch timeline.

Продукт ASP.NET Core 3.1 был обновлен, чтобы реализовать новое поведение SameSite.ASP.NET Core 3.1 has been updated to implement the new SameSite behavior. Это обновление переопределяет поведение SameSiteMode.None для выдачи SameSite=None и добавляет новое значение SameSiteMode.Unspecified, чтобы опустить атрибут SameSite.The update redefines the behavior of SameSiteMode.None to emit SameSite=None and adds a new value SameSiteMode.Unspecified to omit the SameSite attribute. Все API файлов cookie теперь по умолчанию используют Unspecified, хотя некоторые компоненты, использующие файлы cookie, задают более конкретные значения для соответствующих сценариев, таких как корреляция OpenID Connect и файлы cookie nonce.All cookie APIs now default to Unspecified, though some components that use cookies set values more specific to their scenarios such as the OpenID Connect correlation and nonce cookies.

Сведения о последних переменах в этой области см. в разделе HTTP. Некоторые значения по умолчанию параметра SameSite для файлов cookie изменены на None.For other recent changes in this area, see HTTP: Some cookie SameSite defaults changed to None. В ASP.NET Core 3.0 большинство значений по умолчанию изменились с SameSiteMode.Lax на SameSiteMode.None (однако по-прежнему используется более ранний стандарт).In ASP.NET Core 3.0, most defaults were changed from SameSiteMode.Lax to SameSiteMode.None (but still using the prior standard).

Причина измененияReason for change

Изменения в браузере и спецификации, описанные выше.Browser and specification changes as outlined in the preceding text.

Приложения, взаимодействующие с удаленными сайтами, например через стороннюю процедуру входа, должны:Apps that interact with remote sites, such as through third-party login, need to:

  • тестировать эти сценарии в нескольких браузерах;Test those scenarios on multiple browsers.
  • применить исправление определения браузеров в рамках политики файлов cookie, описанное в разделе Поддержка более старых браузеров.Apply the cookie policy browser sniffing mitigation discussed in Support older browsers.

Инструкции по тестированию и определению браузеров см. в следующем разделе:For testing and browser sniffing instructions, see the following section.

Определение того, затрагивают ли вас эти измененияDetermine if you're affected

Протестируйте свое веб-приложение с использованием версии клиента, которая может явно согласиться на новое поведение.Test your web app using a client version that can opt into the new behavior. В Chrome, Firefox и Microsoft Edge Chromium предусмотрены флаги функции явного согласия, которые можно использовать для тестирования.Chrome, Firefox, and Microsoft Edge Chromium all have new opt-in feature flags that can be used for testing. Убедитесь, что ваше приложение совместимо с более старыми версиями клиента после установки исправлений, что особенно актуально для Safari.Verify that your app is compatible with older client versions after you've applied the patches, especially Safari. Дополнительные сведения см. в разделе Поддержка более старых браузеров.For more information, see Support older browsers.

ХромChrome

Chrome 78 и более поздних версий дает неверные результаты тестирования.Chrome 78 and later yield misleading test results. Эти версии используют временные меры исправления и позволяют использовать файлы cookie, имеющие возраст менее двух минут.Those versions have a temporary mitigation in place and allow cookies less than two minutes old. При включении соответствующих флагов тестирования Chrome 76 и 77 дают более точные результаты.With the appropriate test flags enabled, Chrome 76 and 77 yield more accurate results. Чтобы проверить новое поведение, включите chrome://flags/#same-site-by-default-cookies.To test the new behavior, toggle chrome://flags/#same-site-by-default-cookies to enabled. Для Chrome 75 и более ранних версий новый параметр None вызывает ошибку.Chrome 75 and earlier are reported to fail with the new None setting. Дополнительные сведения см. в разделе Поддержка более старых браузеров.For more information, see Support older browsers.

Google не предоставляет более старые версии Chrome.Google doesn't make older Chrome versions available. Однако можно скачать более старые версии Chromium, которых достаточно для тестирования.You can, however, download older versions of Chromium, which will suffice for testing. Следуйте указаниям на странице скачивания Chromium.Follow the instructions at Download Chromium.

SafariSafari

В Safari 12 строго реализован предыдущий проект стандарта, поэтому этот браузер завершается со сбоем, если встречает новое значение None в файлах cookie.Safari 12 strictly implemented the prior draft and fails if it sees the new None value in cookies. Такой сценарий следует исключить с помощью кода определения браузеров, приведенного в разделе Поддержка более старых браузеров.This must be avoided via the browser sniffing code shown in Support older browsers. Обязательно проведите тестирование Safari 12 и 13, а также процедур входа на основе WebKit и механизмов ОС с использованием Библиотеки проверки подлинности Майкрософт (MSAL), Библиотеки проверки подлинности Active Directory (ADAL) или любой другой библиотеки.Ensure you test Safari 12 and 13 as well as WebKit-based, OS-style logins using Microsoft Authentication Library (MSAL), Active Directory Authentication Library (ADAL), or whichever library you're using. Эта проблема зависит от базовой версии ОС.The problem is dependent on the underlying OS version. Известно, что в OSX Mojave 10.14 и iOS 12 имеются проблемы совместимости с этим новым поведением.OSX Mojave 10.14 and iOS 12 are known to have compatibility problems with the new behavior. Обновление до OSX Catalina 10.15 или iOS 13 позволяет устранить их.Upgrading to OSX Catalina 10.15 or iOS 13 fixes the problem. Сейчас в Safari нет флага явного согласия для тестирования поведения, описанного в новой спецификации.Safari doesn't currently have an opt-in flag for testing the new specification behavior.

FirefoxFirefox

Поддержку нового стандарта для Firefox можно проверить в версии 68 и более поздних, указав явное согласие на странице about:config с помощью флага компонента network.cookie.sameSite.laxByDefault.Firefox support for the new standard can be tested on version 68 and later by opting in on the about:config page with the feature flag network.cookie.sameSite.laxByDefault. Сведения о проблемах совместимости для более ранних версий Firefox отсутствуют.No compatibility issues have been reported on older versions of Firefox.

Microsoft EdgeMicrosoft Edge

Хотя Microsoft Edge поддерживает старый стандарт SameSite, начиная с версии 44, в нем нет никаких проблем совместимости с новым стандартом.While Microsoft Edge supports the old SameSite standard, as of version 44 it didn't have any compatibility problems with the new standard.

Microsoft Edge ChromiumMicrosoft Edge Chromium

Используется флаг компонента edge://flags/#same-site-by-default-cookies.The feature flag is edge://flags/#same-site-by-default-cookies. При тестировании в Microsoft Chromium 78 никакие проблемы совместимости не наблюдались.No compatibility issues were observed when testing with Microsoft Edge Chromium 78.

ElectronElectron

Версии Electron включают в себя более старые версии Chromium.Versions of Electron include older versions of Chromium. Например, в Microsoft Teams используется версия Electron — Chromium 66, в которой реализовано старое поведение.For example, the version of Electron used by Microsoft Teams is Chromium 66, which exhibits the older behavior. Выполните собственное тестирование совместимости для версии Electron, используемой вашим продуктом.Perform your own compatibility testing with the version of Electron your product uses. Дополнительные сведения см. в разделе Поддержка более старых браузеров.For more information, see Support older browsers.

Поддержка более старых браузеровSupport older browsers

Стандарт SameSite за 2016 год предписывает обрабатывать неизвестные значения как значения SameSite=Strict.The 2016 SameSite standard mandated that unknown values be treated as SameSite=Strict values. Следовательно, все старые браузеры, поддерживающие оригинальный стандарт, могут прекращать работу, встретив свойство SameSite со значением None.Consequently, any older browsers that support the original standard may break when they see a SameSite property with a value of None. Если требуется поддерживать эти старые браузеры, веб-приложения должны реализовать определение браузеров.Web apps must implement browser sniffing if they intend to support these old browsers. ASP.NET Core не реализует определение браузеров, так как значения заголовков запросов User-Agent крайне непостоянны и меняются каждую неделю.ASP.NET Core doesn't implement browser sniffing for you because User-Agent request header values are highly unstable and change on a weekly basis. Вместо этого точка расширения в политике файлов cookie позволяет добавить логику, связанную с User-Agent.Instead, an extension point in the cookie policy allows you to add User-Agent-specific logic.

Добавьте в файл Startup.cs следующий код:In Startup.cs, add the following code:

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
}
Параметры явного отказаOpt-out switches

Параметр совместимости Microsoft.AspNetCore.SuppressSameSiteNone позволяет временно явно отказаться от нового поведения файлов cookie ASP.NET Core.The Microsoft.AspNetCore.SuppressSameSiteNone compatibility switch enables you to temporarily opt out of the new ASP.NET Core cookie behavior. Добавьте следующий код JSON в файл runtimeconfig.template.json в своем проекте:Add the following JSON to a runtimeconfig.template.json file in your project:

{
  "configProperties": {
    "Microsoft.AspNetCore.SuppressSameSiteNone": "true"
  }
}
Другие версииOther Versions

Подготавливаются к выпуску соответствующие исправления SameSite для следующих продуктов:Related SameSite patches are forthcoming for:

  • ASP.NET Core 2.1, 2.2 и 3.0ASP.NET Core 2.1, 2.2, and 3.0
  • Microsoft.Owin 4.1Microsoft.Owin 4.1
  • System.Web (для .NET Framework 4.7.2 и более поздних версий)System.Web (for .NET Framework 4.7.2 and later)

КатегорияCategory

ASP.NETASP.NET

Затронутые APIAffected APIs


Windows FormsWindows Forms

Удаленные элементы управленияRemoved controls

Начиная с .NET Core 3.1, некоторые элементы управления Windows Forms больше не доступны.Starting in .NET Core 3.1, some Windows Forms controls are no longer available.

Описание измененийChange description

Начиная с .NET Core 3.1, различные элементы управления Windows Forms больше не доступны.Starting with .NET Core 3.1, various Windows Forms controls are no longer available. В .NET Framework 2.0 они были заменены элементами управления с улучшенной структурой и поддержкой.Replacement controls that have better design and support were introduced in .NET Framework 2.0. Нерекомендуемые элементы управления были ранее удалены из панелей элементов конструктора, но по-прежнему были доступны для использования.The deprecated controls were previously removed from designer toolboxes but were still available to be used.

Следующие типы больше не доступны.The following types are no longer available:

Представленная версияVersion introduced

3.13.1

Каждый удаленный элемент управления имеет рекомендуемую замену.Each removed control has a recommended replacement control. См. таблицу ниже.Refer to the following table:

Удаленный элемент управления (API)Removed control (API) Рекомендуемая заменаRecommended replacement Связанные удаленные интерфейсы APIAssociated APIs that are removed
ContextMenuContextMenu ContextMenuStripContextMenuStrip
DataGridDataGrid DataGridViewDataGridView DataGridCell, DataGridRow, DataGridTableCollection, DataGridColumnCollection, DataGridTableStyle, DataGridColumnStyle, DataGridLineStyle, DataGridParentRowsLabel, DataGridParentRowsLabelStyle, DataGridBoolColumn, DataGridTextBox, GridColumnStylesCollection, GridTableStylesCollection, HitTestTypeDataGridCell, DataGridRow, DataGridTableCollection, DataGridColumnCollection, DataGridTableStyle, DataGridColumnStyle, DataGridLineStyle, DataGridParentRowsLabel, DataGridParentRowsLabelStyle, DataGridBoolColumn, DataGridTextBox, GridColumnStylesCollection, GridTableStylesCollection, HitTestType
MainMenuMainMenu MenuStripMenuStrip
МенюMenu ToolStripDropDown, ToolStripDropDownMenuToolStripDropDown, ToolStripDropDownMenu MenuItemCollectionMenuItemCollection
MenuItemMenuItem ToolStripMenuItemToolStripMenuItem
ToolBarToolBar ToolStripToolStrip ToolBarAppearanceToolBarAppearance
ToolBarButtonToolBarButton ToolStripButtonToolStripButton ToolBarButtonClickEventArgs, ToolBarButtonClickEventHandler, ToolBarButtonStyle, ToolBarTextAlignToolBarButtonClickEventArgs, ToolBarButtonClickEventHandler, ToolBarButtonStyle, ToolBarTextAlign

КатегорияCategory

Windows FormsWindows Forms

Затронутые APIAffected APIs


Событие CellFormatting не возникает при отображении подсказкиCellFormatting event not raised if tooltip is shown

DataGridView теперь отображает всплывающие подсказки для ошибок и текста в ячейке при наведении указателя мыши и при выборе с помощью клавиатуры.A DataGridView now shows a cell's text and error tooltips when hovered by a mouse and when selected via the keyboard. Если подсказка отображается, событие DataGridView.CellFormatting не возникает.If a tooltip is shown, the DataGridView.CellFormatting event is not raised.

Описание измененийChange description

До .NET Core 3.1 DataGridView, у которого для свойства ShowCellToolTips было задано значение true, отображал подсказку для ошибок и текста в ячейке при наведении указателя мыши на эту ячейку.Prior to .NET Core 3.1, a DataGridView that had the ShowCellToolTips property set to true showed a tooltip for a cell's text and errors when the cell was hovered by a mouse. Подсказки не отображались при выборе ячейки с помощью клавиатуры (например, с помощью клавиши TAB, сочетаний клавиш или клавиш со стрелками).Tooltips were not shown when a cell was selected via the keyboard (for example, by using the Tab key, shortcut keys, or arrow navigation). Если пользователь изменил ячейку, а затем, пока DataGridView находился в режиме редактирования, навел указатель на ячейку, для которой не задано свойство ToolTipText, возникало событие CellFormatting для форматирования текста ячейки, отображаемого в ней.If the user edited a cell, and then, while the DataGridView was still in edit mode, hovered over a cell that did not have the ToolTipText property set, a CellFormatting event was raised to format the cell's text for display in the cell.

Чтобы удовлетворить требованиям стандартов специальных возможностей, начиная с .NET Core 3.1, DataGridView, у которого для свойства ShowCellToolTips задано значение true, отображает подсказки для ошибок и текста ячейки не только при наведении указателя мыши, но и при выборе ячейки с помощью клавиатуры.To meet accessibility standards, starting in .NET Core 3.1, a DataGridView that has the ShowCellToolTips property set to true shows tooltips for a cell's text and errors not only when the cell is hovered, but also when it's selected via the keyboard. Как следствие этого изменения событие CellFormattingне возникает, когда указатель наводится на ячейки, для которых не задано свойство ToolTipText, пока DataGridView находится в режиме редактирования.As a consequence of this change, the CellFormatting event is not raised when cells that don't have the ToolTipText property set are hovered while the DataGridView is in edit mode. Событие не возникает, так как содержимое ячейки, на которую наведен указатель, выводится в виде подсказки, а не отображается в ячейке.The event is not raised because the content of the hovered cell is shown as a tooltip instead of being displayed in the cell.

Представленная версияVersion introduced

3.13.1

Выполните рефакторинг всего кода, зависящего от события CellFormatting, когда DataGridView находится в режиме редактирования.Refactor any code that depends on the CellFormatting event while the DataGridView is in edit mode.

КатегорияCategory

Windows FormsWindows Forms

Затронутые APIAffected APIs

ОтсутствуютNone