Поделиться через

Разрушающие изменения в .NET Core 3.0

При миграции на .NET Core версии 3.0, ASP.NET Core или EF Core критические изменения, перечисленные в этой статье, могут повлиять на ваше приложение.

ASP.NET Core

Удалены устаревшие API в областях борьбы с фальсификацией, CORS, диагностики, MVC и маршрутизации

Удалены устаревшие члены и параметры совместимости в ASP.NET Core 2.2.

Введённая версия

3.0

Причина изменения

Улучшение поверхности API с течением времени.

При работе с .NET Core 2.2 следуйте рекомендациям в устаревших сообщениях сборки для перехода на новые API.

Категория

ASP.NET Core

Затронутые API

Следующие типы и члены были обозначены как устаревшие для ASP.NET Core 2.1 и 2.2:

Типы

  • Microsoft.AspNetCore.Diagnostics.Views.WelcomePage
  • Microsoft.AspNetCore.DiagnosticsViewPage.Views.AttributeValue
  • Microsoft.AspNetCore.DiagnosticsViewPage.Views.BaseView
  • Microsoft.AspNetCore.DiagnosticsViewPage.Views.HelperResult
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.ProblemDetails21Wrapper
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.ValidationProblemDetails21Wrapper
  • Microsoft.AspNetCore.Mvc.Razor.Compilation.ViewsFeatureProvider
  • Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageArgumentBinder
  • Microsoft.AspNetCore.Routing.IRouteValuesAddressMetadata
  • Microsoft.AspNetCore.Routing.RouteValuesAddressMetadata

Конструкторы

  • Microsoft.AspNetCore.Cors.Infrastructure.CorsService(IOptions{CorsOptions})
  • Microsoft.AspNetCore.Routing.Tree.TreeRouteBuilder(ILoggerFactory,UrlEncoder,ObjectPool{UriBuildingContext},IInlineConstraintResolver)
  • Microsoft.AspNetCore.Mvc.Formatters.OutputFormatterCanWriteContext
  • Microsoft.AspNetCore.Mvc.ApiExplorer.DefaultApiDescriptionProvider(IOptions{MvcOptions},IInlineConstraintResolver,IModelMetadataProvider)
  • Microsoft.AspNetCore.Mvc.ApiExplorer.DefaultApiDescriptionProvider(IOptions{MvcOptions},IInlineConstraintResolver,IModelMetadataProvider,IActionResultTypeMapper)
  • Microsoft.AspNetCore.Mvc.Formatters.FormatFilter(IOptions{MvcOptions})
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ArrayModelBinder`1(IModelBinder)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ByteArrayModelBinder
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.CollectionModelBinder'1(IModelBinder)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ComplexTypeModelBinder(IDictionary'2)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.DictionaryModelBinder`2(IModelBinder,IModelBinder)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.DoubleModelBinder(System.Globalization.NumberStyles)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FloatModelBinder(System.Globalization.NumberStyles)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FormCollectionModelBinder
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FormFileModelBinder
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.HeaderModelBinder
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.KeyValuePairModelBinder`2(IModelBinder,IModelBinder)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder(System.Type)
  • Microsoft.AspNetCore.Mvc.ModelBinding.ModelAttributes(IEnumerable{System.Object})
  • Microsoft.AspNetCore.Mvc.ModelBinding.ModelAttributes(IEnumerable{System.Object},IEnumerable{System.Object})
  • Microsoft.AspNetCore.Mvc.ModelBinding.ModelBinderFactory(IModelMetadataProvider,IOptions{MvcOptions})
  • Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder(IModelMetadataProvider,IModelBinderFactory,IObjectModelValidator)
  • Microsoft.AspNetCore.Mvc.Routing.KnownRouteValueConstraint()
  • Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter
  • Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter(System.Boolean)
  • Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter(MvcOptions)
  • Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter
  • Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter(System.Boolean)
  • Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter(MvcOptions)
  • Microsoft.AspNetCore.Mvc.TagHelpers.ImageTagHelperper(IHostingEnvironment,IMemoryCache,HtmlEncoder,IUrlHelperFactory)
  • Microsoft.AspNetCore.Mvc.TagHelpers.LinkTagHelper(IHostingEnvironment,IMemoryCache,HtmlEncoder,JavaScriptEncoder,IUrlHelperFactory)
  • Microsoft.AspNetCore.Mvc.TagHelpers.ScriptTagHelper(IHostingEnvironment,IMemoryCache,HtmlEncoder,JavaScriptEncoder,IUrlHelperFactory)
  • Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.RazorPageAdapter(RazorPageBase)

Свойства

  • Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookieDomain
  • Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookieName
  • Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookiePath
  • Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.RequireSsl
  • Microsoft.AspNetCore.Mvc.ApiBehaviorOptions.AllowInferringBindingSourceForCollectionTypesAsFromQuery
  • Microsoft.AspNetCore.Mvc.ApiBehaviorOptions.SuppressUseValidationProblemDetailsForInvalidModelStateResponses
  • Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.CookieName
  • Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.Domain
  • Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.Path
  • Microsoft.AspNetCore.Mvc.DataAnnotations.MvcDataAnnotationsLocalizationOptions.AllowDataAnnotationsLocalizationForEnumDisplayAttributes
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.MvcXmlOptions.AllowRfc7807CompliantProblemDetailsFormat
  • Microsoft.AspNetCore.Mvc.MvcOptions.AllowBindingHeaderValuesToNonStringModelTypes
  • Microsoft.AspNetCore.Mvc.MvcOptions.AllowCombiningAuthorizeFilters
  • Microsoft.AspNetCore.Mvc.MvcOptions.AllowShortCircuitingValidationWhenNoValidatorsArePresent
  • Microsoft.AspNetCore.Mvc.MvcOptions.AllowValidatingTopLevelNodes
  • Microsoft.AspNetCore.Mvc.MvcOptions.InputFormatterExceptionPolicy
  • Microsoft.AspNetCore.Mvc.MvcOptions.SuppressBindingUndefinedValueToEnumType
  • Microsoft.AspNetCore.Mvc.MvcViewOptions.AllowRenderingMaxLengthAttribute
  • Microsoft.AspNetCore.Mvc.MvcViewOptions.SuppressTempDataAttributePrefix
  • Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowAreas
  • Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowDefaultHandlingForOptionsRequests
  • Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowMappingHeadRequestsToGetHandler

Методы

Удалены API-интерфейсы Pubternal

Для лучшего поддержания публичной поверхности API ASP.NET Core, большинство типов в пространствах имен *.Internal (которые называются API-интерфейсами "pubternal") стали действительно внутренними. Элементы в этих пространствах имен никогда не предполагалось поддерживать в качестве общедоступных API-интерфейсов. Эти API-интерфейсы могли выходить из строя при незначительных обновлениях, и это случалось часто. Любой код, который зависит от этих API-интерфейсов, перестанет работать при обновлении до ASP.NET Core 3.0.

Подробную информацию см. на страницах dotnet/aspnetcore#4932 и dotnet/aspnetcore#11312.

Введённая версия

3.0

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

Затронутые API-интерфейсы помечаются модификатором доступа public и существуют в пространствах имен *.Internal.

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

Затронутые API-интерфейсы помечаются модификатором доступа internal и больше не могут использоваться в коде за пределами этой сборки.

Причина изменения

Рекомендации для этих API-интерфейсов "pubternal" заключались в следующем:

  • Они могут измениться без предварительного уведомления.
  • На них не распространяются политики .NET по контролю критических изменений.

Оставление API public (даже в пространствах имен *.Internal) вызывало путаницу у пользователей.

Прекратите использовать API-интерфейсы "pubternal". Если вы хотите узнать, какие API-интерфейсы лучше использовать вместо них, откройте запрос в репозитории dotnet/aspnetcore.

Для примера давайте рассмотрим приведенный ниже код, который буферизует HTTP-запросы в проекте ASP.NET Core 2.2. Методы расширения EnableRewind относятся к пространству имен Microsoft.AspNetCore.Http.Internal.

HttpContext.Request.EnableRewind();

В проекте ASP.NET Core 3.0 замените вызов EnableRewind вызовом метода расширения EnableBuffering. Теперь функция буферизации запросов работает так же, как раньше. Но теперь EnableBuffering вызывает API internal.

HttpContext.Request.EnableBuffering();

Категория

ASP.NET Core

Затронутые API

Все API-интерфейсы в пространствах имен Microsoft.AspNetCore.* и Microsoft.Extensions.*, в имени пространства имен которых есть сегмент Internal. Например:

  • Microsoft.AspNetCore.Authentication.Internal
  • Microsoft.AspNetCore.Builder.Internal
  • Microsoft.AspNetCore.DataProtection.Cng.Internal
  • Microsoft.AspNetCore.DataProtection.Internal
  • Microsoft.AspNetCore.Hosting.Internal
  • Microsoft.AspNetCore.Http.Internal
  • Microsoft.AspNetCore.Mvc.Core.Infrastructure
  • Microsoft.AspNetCore.Mvc.Core.Internal
  • Microsoft.AspNetCore.Mvc.Cors.Internal
  • Microsoft.AspNetCore.Mvc.DataAnnotations.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Json.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.Internal
  • Microsoft.AspNetCore.Mvc.Internal
  • Microsoft.AspNetCore.Mvc.ModelBinding.Internal
  • Microsoft.AspNetCore.Mvc.Razor.Internal
  • Microsoft.AspNetCore.Mvc.RazorPages.Internal
  • Microsoft.AspNetCore.Mvc.TagHelpers.Internal
  • Microsoft.AspNetCore.Mvc.ViewFeatures.Internal
  • Microsoft.AspNetCore.Rewrite.Internal
  • Microsoft.AspNetCore.Routing.Internal
  • Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal
  • Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http
  • Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Infrastructure
  • Microsoft.AspNetCore.Server.Kestrel.Https.Internal

Проверка подлинности: Google+ устарел и заменен

Google начал завершать вход Google+ для приложений с 28 января 2019 года.

Описание изменения

Платформы ASP.NET 4.x и ASP.NET Core использовали API для входа, предоставленные Google+, для проверки подлинности пользователей с учетной записью Google в веб-приложениях. Это изменение затронет такие пакеты NuGet, как Microsoft.AspNetCore.Authentication.Google для ASP.NET Core и Microsoft.Owin.Security.Google для Microsoft.Owin с ASP.NET Web Forms и MVC.

В API-интерфейсах, которые Google предоставил в качестве замены, используется другой источник данных и другой формат. Ниже описаны методы и решения, которые позволят учесть эти структурные изменения. Приложения должны проверять, соответствуют ли данные требованиям. Например, имена, адреса электронной почты, ссылки на профили и фотографии профилей могут предоставлять слегка иные значения, чем раньше.

Введённая версия

все версии Это изменение является внешним по отношению к ASP.NET Core.

Использование Owin с ASP.NET Web Forms и MVC

Для Microsoft.Owin 3.1.0 и более поздних версий временное устранение рисков описано в последствиях завершения работы Google+. Приложения должны завершить тестирование с учетом мер по смягчению для проверки изменений в формате данных. Планируется выпуск версии Microsoft.Owin 4.0.1 с исправлением. Все приложения, которые используют любую из предыдущих версий, нужно обновить до версии 4.0.1.

ASP.NET Core 1.x

Устранение рисков, описанное в инструкции для Owin с ASP.NET Web Forms и MVC, можно адаптировать для ASP.NET Core 1. x. Исправления пакетов NuGet не планируются, так как версия 1.x уже достигла завершения жизненного цикла.

ASP.NET Core 2.x

Для Microsoft.AspNetCore.Authentication.Google версии 2.x замените существующий вызов AddGoogle в Startup.ConfigureServices следующим кодом:

.AddGoogle(o =>
{
    o.ClientId = Configuration["Authentication:Google:ClientId"];
    o.ClientSecret = Configuration["Authentication:Google:ClientSecret"];
    o.UserInformationEndpoint = "https://www.googleapis.com/oauth2/v2/userinfo";
    o.ClaimActions.Clear();
    o.ClaimActions.MapJsonKey(ClaimTypes.NameIdentifier, "id");
    o.ClaimActions.MapJsonKey(ClaimTypes.Name, "name");
    o.ClaimActions.MapJsonKey(ClaimTypes.GivenName, "given_name");
    o.ClaimActions.MapJsonKey(ClaimTypes.Surname, "family_name");
    o.ClaimActions.MapJsonKey("urn:google:profile", "link");
    o.ClaimActions.MapJsonKey(ClaimTypes.Email, "email");
});

В февральские обновления 2.1 и 2.2 описанное выше изменение конфигурации включено как новый вариант по умолчанию. Обновления для ASP.NET Core 2.0 не планируются, так как эта версия достигла завершения жизненного цикла.

ASP.NET Core 3.0

Метод устранения рисков, предложенный для ASP.NET Core 2.x, также можно использовать и для ASP.NET Core 3.0. В будущих предварительных версиях для 3.0 пакет Microsoft.AspNetCore.Authentication.Google может быть удален. Вместо этого пользователи будут перенаправлены на Microsoft.AspNetCore.Authentication.OpenIdConnect. В следующем примере кода показано, как заменить AddGoogle на AddOpenIdConnect в Startup.ConfigureServices. Эту замену можно использовать для ASP.NET Core 2.0 и более поздних версий, а также адаптировать для ASP.NET Core 1.x по необходимости.

.AddOpenIdConnect("Google", o =>
{
    o.ClientId = Configuration["Authentication:Google:ClientId"];
    o.ClientSecret = Configuration["Authentication:Google:ClientSecret"];
    o.Authority = "https://accounts.google.com";
    o.ResponseType = OpenIdConnectResponseType.Code;
    o.CallbackPath = "/signin-google"; // Or register the default "/signin-oidc"
    o.Scope.Add("email");
});
JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();

Категория

ASP.NET Core

Затронутые API

Microsoft.AspNetCore.Authentication.Google

Аутентификация: удалено свойство HttpContext.Authentication

Устаревшее свойство Authentication в HttpContext было удалено.

Описание изменения

В рамках dotnet/aspnetcore#6504 устаревшее свойство Authentication в HttpContext было удалено. Свойство Authentication не рекомендуется к использованию, начиная с версии 2.0. Были опубликованы инструкции по переносу кода с использованием этого устаревшего свойства в новые API замены. Оставшиеся неиспользуемые классы и API, связанные со старым стеком проверки подлинности ASP.NET Core 1.x, были удалены в фиксации dotnet/aspnetcore@d7a7c65.

Обсуждение этого вопроса см. на странице dotnet/aspnetcore#6533.

Введённая версия

3.0

Причина изменения

ASP.NET Core API 1.0 были заменены методами расширения в Microsoft.AspNetCore.Authentication.AuthenticationHttpContextExtensions.

См. руководство по переносу.

Категория

ASP.NET Core

Затронутые API

Проверка подлинности: типы Newtonsoft.Json заменены

В ASP.NET Core 3.0 типы Newtonsoft.Json, которые использовались в API проверки подлинности, заменены на типы System.Text.Json. Базовое использование пакетов проверки подлинности остается неизменным, за исключением следующих случаев:

  • классы, производные от поставщиков OAuth, например от aspnet-contrib;
  • расширенные реализации манипуляций с утверждениями.

Подробную информацию см. на странице dotnet/aspnetcore#7105. Обсуждение этого вопроса см. на странице dotnet/aspnetcore#7289.

Введённая версия

3.0

Для производных реализаций OAuth наиболее распространенным изменением является замена JObject.ParseJsonDocument.Parse в переопределении, как показано в CreateTicketAsyncdotnet/aspnetcore#7105. JsonDocument реализует IDisposable.

В следующем списке перечислены известные изменения:

Категория

ASP.NET Core

Затронутые API

Проверка подлинности: изменена подпись OAuthHandler ExchangeCodeAsync

В ASP.NET Core 3.0 сигнатура OAuthHandler.ExchangeCodeAsync была изменена с:

protected virtual System.Threading.Tasks.Task<Microsoft.AspNetCore.Authentication.OAuth.OAuthTokenResponse> ExchangeCodeAsync(string code, string redirectUri) { throw null; }

Кому:

protected virtual System.Threading.Tasks.Task<Microsoft.AspNetCore.Authentication.OAuth.OAuthTokenResponse> ExchangeCodeAsync(Microsoft.AspNetCore.Authentication.OAuth.OAuthCodeExchangeContext context) { throw null; }

Введённая версия

3.0

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

Строки code и redirectUri передавались как отдельные аргументы.

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

Code и RedirectUri являются свойствами OAuthCodeExchangeContext, которые можно задать с помощью конструктора OAuthCodeExchangeContext. Новый тип OAuthCodeExchangeContext — это единственный аргумент, передаваемый в OAuthHandler.ExchangeCodeAsync.

Причина изменения

Это изменение позволяет предоставлять дополнительные параметры без нарушения работы. Создавать новые перегрузки ExchangeCodeAsync не нужно.

Создайте OAuthCodeExchangeContext с соответствующими значениями code и redirectUri. Необходимо указать экземпляр AuthenticationProperties. Этот единичный OAuthCodeExchangeContext экземпляр можно передать в OAuthHandler.ExchangeCodeAsync вместо нескольких аргументов.

Категория

ASP.NET Core

Затронутые API

OAuthHandler<TOptions>.ExchangeCodeAsync(String, String)

Авторизация: перегрузка AddAuthorization перемещена в другую сборку

Основные методы AddAuthorization, ранее находившиеся в Microsoft.AspNetCore.Authorization, были переименованы в AddAuthorizationCore. Старые методы AddAuthorization по-прежнему существуют, но теперь находятся в сборке Microsoft.AspNetCore.Authorization.Policy. Это не должно повлиять на приложения, использующие оба метода. Обратите внимание, что Microsoft.AspNetCore.Authorization.Policy теперь поставляется в общей платформе, а не автономный пакет, как описано в общей платформе: сборки удалены из Microsoft.AspNetCore.App.

Введённая версия

3.0

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

Методы AddAuthorization существовали в Microsoft.AspNetCore.Authorization.

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

Методы AddAuthorization существуют в Microsoft.AspNetCore.Authorization.Policy. AddAuthorizationCore — это новое имя старых методов.

Причина изменения

AddAuthorization — это лучшее имя метода для добавления всех общих служб, требуемых для авторизации.

Добавьте ссылку на Microsoft.AspNetCore.Authorization.Policy или используйте вместо этого AddAuthorizationCore.

Категория

ASP.NET Core

Затронутые API

Microsoft.Extensions.DependencyInjection.AuthorizationServiceCollectionExtensions.AddAuthorization(IServiceCollection, Action<AuthorizationOptions>)

Авторизация: IAllowAnonymous удален из AuthorizationFilterContext.Filters

Начиная с ASP.NET Core 3.0, MVC не добавляет AllowAnonymousFilters для атрибутов [AllowAnonymous], обнаруженных на контроллерах и методах действий. Это изменение локально адресовано для производных AuthorizeAttribute, но является критическим изменением для реализаций IAsyncAuthorizationFilter и IAuthorizationFilter. Такие реализации, заключенные в атрибут [TypeFilter], представляют собой популярный и поддерживаемый способ обеспечения строго типизированной авторизации на основе атрибутов, когда требуется настройка или внедрение зависимостей.

Введённая версия

3.0

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

IAllowAnonymous отображался в коллекции AuthorizationFilterContext.Filters. Тестирование наличия интерфейса было правильным способом для переопределения или отключения фильтра в отдельных методах контроллера.

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

IAllowAnonymous больше не отображается в коллекции AuthorizationFilterContext.Filters. Реализации IAsyncAuthorizationFilter, зависящие от прежнего поведения, обычно приводят к периодическим ответам HTTP "401: не санкционировано" или HTTP "403: запрещено".

Причина изменения

В ASP.NET Core 3.0 введена новая стратегия маршрутизации конечных точек.

Поиск метаданных конечной точки для IAllowAnonymous. Например:

var endpoint = context.HttpContext.GetEndpoint();
if (endpoint?.Metadata?.GetMetadata<IAllowAnonymous>() != null)
{
}

Пример этой техники можно увидеть в этом методе HasAllowAnonymous.

Категория

ASP.NET Core

Затронутые API

нет

Авторизация: реализации IAuthorizationPolicyProvider требуют нового метода

В ASP.NET Core 3.0 в GetFallbackPolicyAsync был добавлен новый метод IAuthorizationPolicyProvider. Эта резервная политика используется промежуточным программным обеспечением для авторизации, если политика не указана.

Подробную информацию см. на странице dotnet/aspnetcore#9759.

Введённая версия

3.0

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

Реализации IAuthorizationPolicyProvider не требовали наличие метода GetFallbackPolicyAsync.

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

Реализации IAuthorizationPolicyProvider требуют метод GetFallbackPolicyAsync.

Причина изменения

Необходим новый метод для использования нового AuthorizationMiddleware, когда политика не указана.

Добавьте метод GetFallbackPolicyAsync в реализации IAuthorizationPolicyProvider.

Категория

ASP.NET Core

Затронутые API

Microsoft.AspNetCore.Authorization.IAuthorizationPolicyProvider

Кэширование: удалено свойство CompactOnMemoryPressure

В версии ASP.NET Core 3.0 удалены устаревшие API MemoryCacheOptions.

Описание изменения

Это изменение является продолжением aspnet/Caching#221. Обсуждение этого вопроса см. на странице dotnet/extensions#1062.

Введённая версия

3.0

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

Свойство MemoryCacheOptions.CompactOnMemoryPressure было доступно.

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

Свойство MemoryCacheOptions.CompactOnMemoryPressure было удалено.

Причина изменения

Автоматическое сжатие кэша приводило к возникновению проблем. Чтобы не допустить непредвиденное поведение, сжимайте кэш только при необходимости.

Чтобы сжать кэш, выполните приведение с понижением к MemoryCache и вызовите Compact при необходимости.

Категория

ASP.NET Core

Затронутые API

MemoryCacheOptions.CompactOnMemoryPressure

Кэширование: Microsoft.Extensions.Caching.SqlServer использует новый пакет SqlClient

Пакет Microsoft.Extensions.Caching.SqlServer будет использовать новый пакет Microsoft.Data.SqlClient вместо пакета System.Data.SqlClient. Это изменение может привести к незначительным ломающим изменениям в поведении. Для получения дополнительной информации см. введение в новый Microsoft.Data.SqlClient.

Введённая версия

3.0

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

Пакет Microsoft.Extensions.Caching.SqlServer использовал пакет System.Data.SqlClient.

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

Microsoft.Extensions.Caching.SqlServer теперь использует пакет Microsoft.Data.SqlClient.

Причина изменения

Microsoft.Data.SqlClient — это новый пакет, созданный на основе System.Data.SqlClient. Отныне все работы над новыми функциями будут проводиться здесь.

Клиентам не нужно беспокоиться об этом изменении, нарушающем обратную совместимость, если только они не использовали типы, которые возвращаются пакетом Microsoft.Extensions.Caching.SqlServer, и не приводили их к типам System.Data.SqlClient. Например, при приведении DbConnection к старому типу SqlConnection, нужно будет изменить приведение на новый тип Microsoft.Data.SqlClient.SqlConnection.

Категория

ASP.NET Core

Затронутые API

нет

Кэширование: типы ResponseCaching из "pubternal" изменились на внутренние

В ASP.NET Core 3.0 типы pubternal в ResponseCaching были изменены на internal.

Кроме того, реализации по умолчанию IResponseCachingPolicyProvider и IResponseCachingKeyProvider больше не добавляются в службы в рамках метода AddResponseCaching.

Описание изменения

В ASP.NET Core типы pubternal объявляются как public, но они находятся в пространстве имен с суффиксом .Internal. Хотя эти типы являются общедоступными, для них отсутствует политика поддержки и они подвержены разрушающим изменениям. К сожалению, довольно часто эти типы использовались случайно, что приводило к критическим изменениям в таких проектах и ограничивало возможности, связанные с обслуживанием платформы.

Введённая версия

3.0

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

Эти типы были видны всем пользователям, но не поддерживаемыми.

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

Теперь эти типы являются internal.

Причина изменения

Область internal лучше соответствует неподдерживаемой политике.

Копируйте типы, используемые приложением или библиотекой.

Категория

ASP.NET Core

Затронутые API

Защита данных: DataProtection.Blobs использует новые API хранилища Azure

Azure.Extensions.AspNetCore.DataProtection.Blobs зависит от библиотек службы хранилища Azure. Эти библиотеки переименовали свои сборки, пакеты и пространства имен. Начиная с ASP.NET Core 3.0, Azure.Extensions.AspNetCore.DataProtection.Blobs использует новые API и пакеты с префиксом Azure.Storage..

Если у вас возникли вопросы об API службы хранилища Azure, см. страницу https://github.com/Azure/azure-storage-net. Обсуждение этого вопроса см. на странице dotnet/aspnetcore#19570.

Введённая версия

3.0

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

Пакет ссылался на пакет WindowsAzure.Storage NuGet. Пакет ссылается на пакет Microsoft.Azure.Storage.Blob NuGet.

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

Пакет ссылается на пакет Azure.Storage.Blob NuGet.

Причина изменения

Это изменение позволяет Azure.Extensions.AspNetCore.DataProtection.Blobs переходить к рекомендуемым пакетам службы хранилища Azure.

Если вам по-прежнему нужно использовать старые API службы хранилища Azure с ASP.NET Core 3.0, добавьте прямую зависимость в пакет WindowsAzure.Storage или Microsoft.Azure.Storage. Этот пакет можно установить вместе с новыми API Azure.Storage.

Во многих случаях обновление сводится лишь к изменению инструкций using для использования новых пространств имен.

- using Microsoft.WindowsAzure.Storage;
- using Microsoft.WindowsAzure.Storage.Blob;
- using Microsoft.Azure.Storage;
- using Microsoft.Azure.Storage.Blob;
+ using Azure.Storage;
+ using Azure.Storage.Blobs;

Категория

ASP.NET Core

Затронутые API

нет

Хостинг: AspNetCoreModule V1 был удален из Windows Hosting Bundle

Начиная с ASP.NET Core 3.0, пакет для размещения на Windows не будет содержать AspNetCoreModule (ANCM) версии 1.

ANCM версии 2 обеспечивает обратную совместимость с ANCM OutOfProcess и рекомендуется для использования с приложениями ASP.NET Core 3.0.

Обсуждение этого вопроса см. на странице dotnet/aspnetcore#7095.

Введённая версия

3.0

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

ANCM версии 1 входит в состав пакета размещения Windows.

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

ANCM версии 1 не входит в комплект пакета размещения для Windows.

Причина изменения

ANCM версии 2 обеспечивает обратную совместимость с ANCM OutOfProcess и рекомендуется для использования с приложениями ASP.NET Core 3.0.

Используйте ANCM версии 2 с приложениями ASP.NET Core 3.0.

Если требуется ANCM V1, его можно установить с помощью пакета размещения для Windows ASP.NET Core версий 2.1 или 2.2.

Это изменение приведет к нарушению работы приложений ASP.NET Core 3.0, которые:

  • Явно указано использование ANCM версия 1 с <AspNetCoreModuleName>AspNetCoreModule</AspNetCoreModuleName>.
  • Имейте пользовательский файл web.config с <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />.

Категория

ASP.NET Core

Затронутые API

нет

Хостинг: Универсальный хост ограничивает внедрение конструктора Startup

Единственные типы, которые поддерживает универсальный хост для внедрения через конструктор класса Startup, — это IHostEnvironment, IWebHostEnvironment и IConfiguration. Это не влияет на приложения, которые используют WebHost.

Описание изменения

До версии ASP.NET Core 3.0 инъекцию конструктора можно было использовать для произвольных типов в конструкторе класса Startup. Начиная с ASP.NET Core 3.0 веб-стек переведен на универсальную библиотеку узлов. Эти изменения можно увидеть в файле Program.cs следующих шаблонов:

ASP.NET Core 2.x:

https://github.com/dotnet/aspnetcore/blob/5cb615fcbe8559e49042e93394008077e30454c0/src/Templating/src/Microsoft.DotNet.Web.ProjectTemplates/content/EmptyWeb-CSharp/Program.cs#L20-L22

ASP.NET Core 3.0:

https://github.com/dotnet/aspnetcore/blob/b1ca2c1155da3920f0df5108b9fedbe82efaa11c/src/ProjectTemplates/Web.ProjectTemplates/content/EmptyWeb-CSharp/Program.cs#L19-L24

Host использует один контейнер внедрения зависимостей (DI) для сборки приложения. WebHost использует два контейнера: один для узла и один для приложения. В результате конструктор Startup теперь не поддерживает внедрение пользовательского сервиса. Можно внедрять только IHostEnvironment, IWebHostEnvironment или IConfiguration. Это изменение предотвращает проблемы DI, такие как повторное создание singleton-сервиса.

Введённая версия

3.0

Причина изменения

Это изменение является следствием перевода веб-стека на общую хост-библиотеку.

Внедряйте службы в сигнатуру метода Startup.Configure. Например:

public void Configure(IApplicationBuilder app, IOptions<MyOptions> options)

Категория

ASP.NET Core

Затронутые API

нет

Хостинг: включено перенаправление HTTPS для внешних приложений IIS

В ASP.NET Core Module (ANCM) версии 13.0.19218.0 для размещения с помощью IIS вне процесса можно реализовать существующую функцию перенаправления HTTPS для приложений ASP.NET Core 3.0 и 2.2.

Обсуждение этого вопроса см. на странице dotnet/AspNetCore#15243.

Введённая версия

3.0

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

В шаблоне проекта ASP.NET Core 2.1 впервые представлена поддержка методов HTTPS промежуточного слоя, таких как UseHttpsRedirection и UseHsts. Для включения перенаправления HTTPS требовалось добавить конфигурацию, поскольку приложения, находящиеся в разработке, не используют порт по умолчанию 443. Протокол HSTS активен только в том случае, если запрос уже использует протокол HTTPS. По умолчанию localhost пропускается.

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

В ASP.NET Core 3.0 усовершенствован сценарий IIS HTTPS. Благодаря этому усовершенствованию приложение может обнаруживать порты HTTPS сервера и сделать так, что UseHttpsRedirection будет работать по умолчанию. Внутрипроцессный компонент выполнял обнаружение порта с помощью функции IServerAddresses, которая влияет только на приложения ASP.NET Core 3.0, поскольку внутрипроцессная библиотека имеет версию платформы. Внепроцессный компонент был изменен — теперь он автоматически добавляет переменную среды ASPNETCORE_HTTPS_PORT. Это изменение повлияло на приложения ASP.NET Core 2.2 и 3.0, поскольку внепроцессный компонент используется совместно глобально. Данное изменение не затрагивает приложения ASP.NET Core 2.1, так как они по умолчанию используют более раннюю версию ANCM.

Предыдущее поведение было изменено в ASP.NET Core 3.0.1 и 3.1.0 Preview 3 с целью отмены изменений в работе ASP.NET Core 2.x. Эти изменения влияют только на приложения, находящиеся вне процесса IIS.

Как описано выше, установка ASP.NET Core 3.0.0 имела побочный результат — активацию UseHttpsRedirection промежуточного слоя в приложениях ASP.NET Core 2.x. В ANCM в ASP.NET Core 3.0.1 и 3.1.0 Preview 3 было внесено соответствующее изменение, поэтому их установка больше не влияет на работу приложений ASP.NET Core 2.x. Переменная среды ASPNETCORE_HTTPS_PORT, которая заполнялась ANCM в ASP.NET Core 3.0.0, была изменена на ASPNETCORE_ANCM_HTTPS_PORT в ASP.NET Core 3.0.1 и 3.1.0 Preview 3. В этих выпусках также был обновлен компонент UseHttpsRedirection для понимания новых и старых переменных. Обновление для ASP.NET Core 2.x не предусмотрено. В результате система возвращается к предыдущему поведению, при котором функция отключена по умолчанию.

Причина изменения

Улучшена функциональность ASP.NET Core 3.0.

Если все клиенты должны использовать протокол HTTPS, никаких действий не требуется. Чтобы разрешить некоторым клиентам использовать протокол HTTP, выполните одно из следующих действий.

  • Удалите вызовы UseHttpsRedirection и UseHsts из метода Startup.Configure проекта и разверните приложение повторно.

  • В файле web.config задайте для переменной среды ASPNETCORE_HTTPS_PORT пустую строку. Это изменение можно выполнить непосредственно на сервере без повторного развертывания приложения. Например:

    <aspNetCore processPath="dotnet" arguments=".\WebApplication3.dll" stdoutLogEnabled="false" stdoutLogFile="\\?\%home%\LogFiles\stdout" >
    <environmentVariables>
    <environmentVariable name="ASPNETCORE_HTTPS_PORT" value="" />
    </environmentVariables>
</aspNetCore>

UseHttpsRedirection все еще может быть:

  • Активировать вручную в ASP.NET Core 2.x, задав для переменной среды ASPNETCORE_HTTPS_PORT соответствующий номер порта (в большинстве рабочих сценариев это порт 443).
  • Отключается в ASP.NET Core 3.x путем задания ASPNETCORE_ANCM_HTTPS_PORT с пустым строковым значением. Это значение задается таким же образом, как и в предыдущем примере ASPNETCORE_HTTPS_PORT.

На компьютеры, на которых выполняются приложения ASP.NET Core 3.0.0, следует установить среду выполнения ASP.NET Core 3.0.1, прежде чем устанавливать ASP.NET Core 3.1.0 Preview 3 ANCM. Это гарантирует, что UseHttpsRedirection будет работать правильно для приложений ASP.NET Core 3.0.

Поскольку компонент ANCM является глобальным, он развертывается в службе приложений Azure по отдельному расписанию, отличному от времени выполнения. ANCM был развернут в Azure с этими изменениями после развертывания ASP.NET Core 3.0.1 и 3.1.0.

Категория

ASP.NET Core

Затронутые API

HttpsPolicyBuilderExtensions.UseHttpsRedirection(IApplicationBuilder)

Размещение: типы IHostingEnvironment и IApplicationLifetime помечены как устаревшие и замененные

Введены новые типы для замены типов IHostingEnvironment и IApplicationLifetime.

Введённая версия

3.0

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

Имелись два разных типа IHostingEnvironment и IApplicationLifetime из Microsoft.Extensions.Hosting и Microsoft.AspNetCore.Hosting.

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

Старые типы помечены как устаревшие и заменены новыми типами.

Причина изменения

Когда Microsoft.Extensions.Hosting был введен в ASP.NET Core 2.1, несколько типов, например IHostingEnvironment и IApplicationLifetime, были скопированы из Microsoft.AspNetCore.Hosting. Некоторые изменения в ASP.NET Core 3.0 привели к том, что в приложения одновременно включаются пространства имен Microsoft.Extensions.Hosting и Microsoft.AspNetCore.Hosting. Любое использование этих дублирующихся типов приводило к ошибке компилятора "двусмысленная ссылка" при использовании обоих пространств имен.

Замените любые использования старых типов новыми типами, как показано ниже:

Устаревшие типы (предупреждение):

Новые типы:

Новые методы расширения IHostEnvironmentIsDevelopment и IsProduction относятся к пространству имен Microsoft.Extensions.Hosting. Возможно, потребуется добавить в проект это пространство имен.

Категория

ASP.NET Core

Затронутые API

Размещение: ObjectPoolProvider удален из зависимостей WebHostBuilder

В ходе оптимизации ASP.NET Core ObjectPoolProvider был удален из основного набора зависимостей. Отдельные компоненты, зависящие от ObjectPoolProvider, теперь добавляют его самостоятельно.

Обсуждение этого вопроса см. на странице dotnet/aspnetcore#5944.

Введённая версия

3.0

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

WebHostBuilder предоставляет ObjectPoolProvider по умолчанию в контейнере DI.

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

WebHostBuilder не предоставляет ObjectPoolProvider по умолчанию в контейнере DI.

Причина изменения

Это изменение было внесено, чтобы сделать ASP.NET Core более ориентированным на модель оплаты за использование.

Если компонент требует ObjectPoolProvider, его необходимо добавить в зависимости с помощью IServiceCollection.

Категория

ASP.NET Core

Затронутые API

нет

HTTP: удалена расширяемость DefaultHttpContext

В рамках повышения производительности ASP.NET Core 3.0 расширяемость DefaultHttpContext была удалена. Теперь класс sealed. Подробную информацию см. на странице dotnet/aspnetcore#6504.

Если модульные тесты используют Mock<DefaultHttpContext>, используйте вместо этого Mock<HttpContext> или new DefaultHttpContext().

Обсуждение этого вопроса см. на странице dotnet/aspnetcore#6534.

Введённая версия

3.0

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

Классы могут быть производными от DefaultHttpContext.

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

Классы не могут быть производными от DefaultHttpContext.

Причина изменения

Изначально была предоставлена расширяемость, позволяющая выполнять группировку HttpContext, но это внесло ненужные сложности и препятствовало другим оптимизациям.

Если вы используете Mock<DefaultHttpContext> в модульных тестах, используйте вместо этого Mock<HttpContext>.

Категория

ASP.NET Core

Затронутые API

Microsoft.AspNetCore.Http.DefaultHttpContext

HTTP: константы HeaderNames изменены на статические доступные только для чтения

Начиная с ASP.NET Core 3.0 (предварительная версия 5), поля в Microsoft.Net.Http.Headers.HeaderNames изменились с const на static readonly.

Обсуждение этого вопроса см. на странице dotnet/aspnetcore#9514.

Введённая версия

3.0

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

Эти поля раньше были const.

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

Теперь эти поля являются static readonly.

Причина изменения

Изменение:

  • предотвращает встраивание значений между границами сборки, что позволяет корректировать значения по мере необходимости.
  • обеспечивает более быстрые проверки равенства ссылок.

Выполните перекомпиляцию для версии 3.0. Исходный код, использующий эти поля следующими способами, больше не поддерживает эту возможность:

  • как аргумент атрибута;
  • как case в операторе switch;
  • при определении другого const.

Чтобы обойти критическое изменение, переключитесь на использование самостоятельно определенных констант имен заголовков или строковых литералов.

Категория

ASP.NET Core

Затронутые API

Microsoft.Net.Http.Headers.HeaderNames

HTTP: изменения в структуре тела ответа

Инфраструктура, поддерживающая тело ответа HTTP, изменена. Если вы используете HttpResponse напрямую, вам не нужно вносить никаких изменений в код. Читайте дальше, если вы оборачиваете или заменяете HttpResponse.Body или обращаетесь к HttpContext.Features.

Введённая версия

3.0

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

С текстом ответа HTTP связаны три API:

  • IHttpResponseFeature.Body
  • IHttpSendFileFeature.SendFileAsync
  • IHttpBufferingFeature.DisableResponseBuffering

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

Если вы заменяете HttpResponse.Body, то это заменяет весь IHttpResponseBodyFeature, создавая оболочку вокруг вашего потока с помощью StreamResponseBodyFeature для предоставления реализаций по умолчанию для всех ожидаемых интерфейсов API. Возврат к исходному потоку отменяет это изменение.

Причина изменения

Мотивация заключается в том, чтобы объединить API тела ответа в единый новый интерфейс функции.

Используйте IHttpResponseBodyFeature том, где ранее использовали IHttpResponseFeature.Body, IHttpSendFileFeature или IHttpBufferingFeature.

Категория

ASP.NET Core

Затронутые API

SameSite — это параметр для файлов cookie, который помогает предотвращать некоторые атаки с подделкой межсайтовых запросов. Когда этот параметр изначально появился, в разных интерфейсах API ASP.NET Core использовались несогласованные значения по умолчанию. Это приводило к путанице в результатах. Начиная с версии ASP.NET Core 3.0, значения по умолчанию стали более согласованными. Эту функцию необходимо включать отдельно для каждого компонента.

Введённая версия

3.0

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

В похожих интерфейсах API ASP.NET Core использовались разные значения по умолчанию параметра SameSiteMode. Примером несогласованности могут служить методы HttpResponse.Cookies.Append(String, String) и HttpResponse.Cookies.Append(String, String, CookieOptions) со значениями по умолчанию SameSiteMode.None и SameSiteMode.Laxсоответственно.

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

Во всех затронутых интерфейсах API по умолчанию используется значение SameSiteMode.None.

Причина изменения

Значение по умолчанию было изменено, чтобы сделать функцию SameSite настраиваемой пользователем.

Для каждого компонента, который отправляет файлы cookie, нужно решить, подходит ли SameSite для его сценариев. Проверьте использование затронутых интерфейсов API и при необходимости перенастройте параметр SameSite.

Категория

ASP.NET Core

Затронутые API

HTTP: синхронные операции ввода-вывода отключены на всех серверах

Начиная с ASP.NET Core 3,0, синхронные операции сервера по умолчанию отключены.

Описание изменения

Параметр AllowSynchronousIO включает или отключает на каждом сервере синхронные API ввода-вывода, например HttpRequest.Body.Read, HttpResponse.Body.Write и Stream.Flush. Эти API-интерфейсы долго были причиной нехватки потоков и зависания приложений. Начиная с ASP.NET Core 3.0 предварительной версии 3, синхронные операции сервера по умолчанию отключены.

Затрагиваемые службы:

  • Пустельга
  • HttpSys
  • IIS (в процессе)
  • Тестовый сервер

Можно ожидать ошибки, аналогичные следующим:

  • Synchronous operations are disallowed. Call ReadAsync or set AllowSynchronousIO to true instead.
  • Synchronous operations are disallowed. Call WriteAsync or set AllowSynchronousIO to true instead.
  • Synchronous operations are disallowed. Call FlushAsync or set AllowSynchronousIO to true instead.

Каждый сервер имеет параметр AllowSynchronousIO, который управляет этим поведением, и по умолчанию для всех из них используется значение false.

В качестве временной меры можно переопределять данное поведение для каждого запроса. Например:

var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();
if (syncIOFeature != null)
{
    syncIOFeature.AllowSynchronousIO = true;
}

Если у вас возникают проблемы с TextWriter или другим потоком, который вызывает синхронный API в Dispose, обращайтесь вместо него к новому API-интерфейсу DisposeAsync.

Обсуждение этого вопроса см. на странице dotnet/aspnetcore#7644.

Введённая версия

3.0

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

По умолчанию были разрешены HttpRequest.Body.Read, HttpResponse.Body.Write и Stream.Flush.

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

Эти синхронные API запрещены по умолчанию:

Можно ожидать ошибки, аналогичные следующим:

  • Synchronous operations are disallowed. Call ReadAsync or set AllowSynchronousIO to true instead.
  • Synchronous operations are disallowed. Call WriteAsync or set AllowSynchronousIO to true instead.
  • Synchronous operations are disallowed. Call FlushAsync or set AllowSynchronousIO to true instead.

Причина изменения

Эти синхронные API-интерфейсы долго были причиной нехватки потоков и зависания приложений. Начиная с ASP.NET Core 3.0 предварительной версии 3, синхронные операции сервера по умолчанию отключены.

Используйте асинхронные версии этих методов. В качестве временной меры можно переопределять данное поведение для каждого запроса.

var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();
if (syncIOFeature != null)
{
    syncIOFeature.AllowSynchronousIO = true;
}

Категория

ASP.NET Core

Затронутые API

Идентификация: удалена перегрузка метода AddDefaultUI

Начиная с ASP.NET Core 3.0, перегрузка метода IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder,UIFramework) больше не существует.

Введённая версия

3.0

Причина изменения

Это изменение было результатом внедрения функции статических веб-ресурсов.

Вызывайте IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder) вместо перегрузки, принимающей два аргумента. Если вы используете Bootstrap 3, добавьте следующую строку в элемент <PropertyGroup> в файле проекта:

<IdentityUIFrameworkVersion>Bootstrap3</IdentityUIFrameworkVersion>

Категория

ASP.NET Core

Затронутые API

IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder,UIFramework)

Идентификация: изменена версия Bootstrap пользовательского интерфейса по умолчанию

Начиная с ASP.NET Core 3.0, пользовательский интерфейс удостоверений по умолчанию использует Bootstrap версии 4.

Введённая версия

3.0

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

Вызов метода services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(); был таким же, как и services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap3);.

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

Вызов метода services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(); такой же, как и services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap4);.

Причина изменения

Bootstrap 4 был выпущен в период выхода ASP.NET Core 3.0.

Это изменение затронет вас, если вы используете пользовательский интерфейс удостоверений по умолчанию и добавили его в Startup.ConfigureServices, как показано в следующем примере:

services.AddDefaultIdentity<IdentityUser>().AddDefaultUI();

Выполните одно из следующих действий:

  • перенесите приложение для использования Bootstrap 4, следуя инструкциям по переносу;

  • обновите Startup.ConfigureServices для принудительного использования Bootstrap 3. Например:

    services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap3);

Категория

ASP.NET Core

Затронутые API

нет

Удостоверение: SignInAsync вызывает исключение для неаутентифицированного удостоверения.

По умолчанию SignInAsync выбрасывает исключение для субъектов и идентичностей, в которых IsAuthenticated является false.

Введённая версия

3.0

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

SignInAsync принимает все субъекты и удостоверения, включая удостоверения, в которых IsAuthenticated является false.

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

По умолчанию SignInAsync выбрасывает исключение для субъектов и идентичностей, в которых IsAuthenticated является false. Есть новый флаг, который подавляет это поведение, но поведение по умолчанию изменилось.

Причина изменения

Старое поведение было проблематичным, потому что по умолчанию эти принципалы отклонялись [Authorize] / RequireAuthenticatedUser().

В ASP.NET Core 3.0 (предварительная версия 6) есть флаг RequireAuthenticatedSignIn в AuthenticationOptions, который является true по умолчанию. Установите для этого флага значение false, чтобы восстановить старое поведение.

Категория

ASP.NET Core

Затронутые API

нет

Идентификация: конструктор SignInManager принимает новый параметр

Начиная с ASP.NET Core 3.0 в конструктор IUserConfirmation<TUser> был добавлен новый параметр SignInManager. Подробную информацию см. на странице dotnet/aspnetcore#8356.

Введённая версия

3.0

Причина изменения

Мотивом изменения было добавление поддержки для новых потоков электронной почты и подтверждений в системе идентификации.

При ручном конструировании SignInManager предоставьте реализацию IUserConfirmation или возьмите ее из контейнера внедрения зависимостей.

Категория

ASP.NET Core

Затронутые API

SignInManager<TUser>

Идентификация: пользовательский интерфейс использует функцию статических веб-активов

В ASP.NET Core 3.0 была введена функция статических веб-ресурсов, и ее использует пользовательский интерфейс Identity.

Описание изменения

В результате внедрения функции статических веб-ресурсов в Identity UI.

  • Выбор платформы осуществляется с помощью свойства IdentityUIFrameworkVersion в файле проекта.
  • Bootstrap 4 является фреймворком интерфейса пользователя по умолчанию для Identity UI. Bootstrap 3 достигла конца жизненного цикла, и мы рекомендуем перейти на поддерживаемую версию.

Введённая версия

3.0

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

Инфраструктурой пользовательского интерфейса по умолчанию для пользовательского интерфейса удостоверений была Bootstrap 3. Настройка платформы пользовательского интерфейса может быть выполнена с использованием параметра в вызове метода AddDefaultUI в Startup.ConfigureServices.

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

Фреймворком пользовательского интерфейса по умолчанию для UI удостоверений является Bootstrap 4. Платформа пользовательского интерфейса должна настраиваться в файле проекта, а не в вызове метода AddDefaultUI.

Причина изменения

Для внедрения возможности статических веб-ресурсов потребовалось перенести конфигурацию платформы пользовательского интерфейса в MSBuild. Решение о том, какая платформа будет внедрена, является решением времени сборки, а не среды выполнения.

Проверьте пользовательский интерфейс сайта, чтобы убедиться, что новые компоненты Bootstrap 4 совместимы. При необходимости используйте свойство MSBuild IdentityUIFrameworkVersion, чтобы вернуться к Bootstrap 3. Добавьте свойство в элемент <PropertyGroup> в файле проекта:

<IdentityUIFrameworkVersion>Bootstrap3</IdentityUIFrameworkVersion>

Категория

ASP.NET Core

Затронутые API

IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder, UIFramework)

Kestrel: адаптеры подключения удалены

В рамках переноса API "pubternal" в public концепция IConnectionAdapter была удалена из Kestrel. Адаптеры подключений заменяются соответствующим ПО промежуточного слоя, которое похоже на ПО промежуточного слоя HTTP в конвейере ASP.NET Core, но для подключений более низкого уровня. Запись соединений и HTTPS перемещены из адаптеров соединений в промежуточное программное обеспечение для соединений. Эти методы расширения должны и дальше работать без проблем, но детали реализации изменились.

Подробную информацию см. на странице dotnet/aspnetcore#11412. Обсуждение этого вопроса см. на странице dotnet/aspnetcore#11475.

Введённая версия

3.0

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

Компоненты расширяемости Kestrel были созданы с помощью IConnectionAdapter.

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

Компоненты расширяемости Kestrel созданы как промежуточное ПО.

Причина изменения

Это изменение предназначено для обеспечения более гибкой архитектуры расширяемости.

Преобразуйте любые реализации IConnectionAdapter, чтобы использовать новый паттерн middleware, как показано в dotnet/aspnetcore#11412.

Категория

ASP.NET Core

Затронутые API

Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter

Удалена не содержащая данных сборка HTTPS в Kestrel

Сборка Microsoft.AspNetCore.Server.Kestrel.Https была удалена.

Введённая версия

3.0

Причина изменения

В ASP.NET Core 2.1 содержимое Microsoft.AspNetCore.Server.Kestrel.Https перемещено в Microsoft.AspNetCore.Server.Kestrel.Core. Это изменение было выполнено незаметно с помощью атрибутов [TypeForwardedTo].

  • Библиотеки, ссылающиеся на Microsoft.AspNetCore.Server.Kestrel.Https 2.0, должны обновить все зависимости ASP.NET Core до версии 2.1 и выше. В противном случае они могут прерывать работу при загрузке в приложение ASP.NET Core 3.0.
  • Приложения и библиотеки, предназначенные для ASP.NET Core версии 2.1 и выше, должны удалять все прямые ссылки на пакет Microsoft.AspNetCore.Server.Kestrel.Https NuGet.

Категория

ASP.NET Core

Затронутые API

нет

Kestrel: трейлерные заголовки запроса перемещены в новую коллекцию

В предыдущих версиях Kestrel поблочные трейлеры стандарта HTTP/1.1 добавлялись в коллекцию заголовков запроса, когда завершалось чтение текста запроса. Такое поведение вызывало проблемы, связанные с неоднозначностью между заголовками и трейлерами. Было принято решение перенести трейлеры в новую коллекцию.

Трейлеры запросов HTTP/2 были ранее недоступны в ASP.NET Core 2.2, но теперь также включены в эту новую коллекцию, начиная с ASP.NET Core 3.0.

Для доступа к этим трейлерам добавлены новые методы расширения запроса.

Трейлеры HTTP/1.1 теперь становятся доступны, когда завершится считывание текста запроса.

Трейлеры HTTP/2 становятся доступны, когда они получены от клиента. Клиент не будет отправлять трейлеры, пока весь текст запроса не передан по крайней мере в буфер сервера. Возможно, потребуется прочитать весь текст запроса, чтобы освободить место в буфере. Трейлеры всегда доступны, если тело запроса прочитано до конца. Трейлеры обозначают конец основного текста.

Введённая версия

3.0

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

Заголовки трейлеров запроса будут добавлены в коллекцию HttpRequest.Headers.

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

Заголовки трейлеров запроса отсутствуют в коллекции HttpRequest.Headers. Примените к HttpRequest следующие методы расширения, чтобы получить их:

  • GetDeclaredTrailers() получает заголовок запроса Trailer, который содержит список трейлеров, ожидаемых после текста запроса;
  • SupportsTrailers() указывает, поддерживает ли запрос получение трейлерных заголовков.
  • CheckTrailersAvailable() определяет, поддерживает ли запрос трейлеры и доступны ли они для чтения;
  • GetTrailer(string trailerName) получает запрошенный дополнительный заголовок из ответа.

Причина изменения

Трейлеры являются ключевой функцией в таких сценариях, как gRPC. Объединение заголовков трейлеров с основными заголовками вызывало путаницу у пользователей.

Для доступа к трейлерам используйте специальные методы расширения в HttpRequest.

Категория

ASP.NET Core

Затронутые API

HttpRequest.Headers

Kestrel: абстракции транспорта удалены и стали общедоступными

В рамках перехода от программного интерфейса типа "pubternal" API транспортного уровня Kestrel предоставляются в виде общедоступного интерфейса в библиотеке Microsoft.AspNetCore.Connections.Abstractions.

Введённая версия

3.0

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

  • Абстракции, связанные с транспортировкой, были доступны в библиотеке Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.
  • Свойство ListenOptions.NoDelay было доступно.

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

  • Интерфейс IConnectionListener появился в библиотеке Microsoft.AspNetCore.Connections.Abstractions, предоставляя наиболее используемые функции из библиотеки ...Transport.Abstractions.
  • Теперь NoDelay можно использовать в параметрах транспорта (LibuvTransportOptions и SocketTransportOptions).
  • SchedulingMode больше недоступен.

Причина изменения

ASP.NET Core 3.0 отказался от использования "pubternal" API.

Категория

ASP.NET Core

Затронутые API

нет

Локализация: ResourceManagerWithCultureStringLocalizer и WithCulture помечены как устаревшие

Класс ResourceManagerWithCultureStringLocalizer и член-интерфейс WithCulture часто становились причиной путаницы для пользователей при локализации, особенно при создании собственной реализации IStringLocalizer. Эти элементы создают у пользователей ощущение, что экземпляр IStringLocalizer создается отдельно для каждого языка и каждого ресурса. На самом деле экземпляры должны существовать только для каждого отдельного ресурса. Искомый язык определяется CultureInfo.CurrentUICulture во время выполнения. Чтобы устранить источник путаницы, API были помечены как устаревшие в ASP.NET Core 3.0. Эти API будут удалены в будущем выпуске.

Контекст этого вопроса см. на странице dotnet/aspnetcore#3324. Обсуждение этого вопроса см. на странице dotnet/aspnetcore#7756.

Введённая версия

3.0

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

Методы не имели отметки Obsolete.

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

Методы получили отметку Obsolete.

Причина изменения

Эти API представляли нерекомендованный вариант использования. Они создавали путаницу в отношении структуры локализации.

Основная рекомендация: использовать вместо них ResourceManagerStringLocalizer. Пусть культура задаётся с помощью CurrentCulture. Если это невозможно, создайте и примените копию ResourceManagerWithCultureStringLocalizer.

Категория

ASP.NET Core

Затронутые API

  • Microsoft.Extensions.Localization.ResourceManagerWithCultureStringLocalizer
  • Microsoft.Extensions.Localization.ResourceManagerStringLocalizer.WithCulture

Ведение журнала: класс DebugLogger сделан внутренним

До версии ASP.NET Core 3.0 модификатор доступа DebugLogger имел атрибут public. В ASP.NET Core 3.0 модификатор доступа изменен на internal.

Введённая версия

3.0

Причина изменения

Изменение реализуется с такой целью:

  • Обеспечить согласованность с другими реализациями логгеров, такими как ConsoleLogger.
  • уменьшение объёма интерфейса API.

Используйте метод расширения AddDebugILoggingBuilder, чтобы включить ведение журналов отладки. DebugLoggerProvider также имеет атрибут public на тот случай, если потребуется зарегистрировать службу вручную.

Категория

ASP.NET Core

Затронутые API

Microsoft.Extensions.Logging.Debug.DebugLogger

MVC: Асинхронный суффикс, обрезанный из имен действий контроллера

В системе адресации dotnet/aspnetcore#4849 ASP.NET Core MVC по умолчанию обрезает суффиксы Async в именах действий. Начиная с ASP.NET Core 3,0, это изменение влияет на процессы маршрутизации и создания ссылок.

Введённая версия

3.0

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

Рассмотрим следующий контроллер ASP.NET Core MVC:

public class ProductController : Controller
{
    public async IActionResult ListAsync()
    {
        var model = await DbContext.Products.ToListAsync();
        return View(model);
    }
}

Действие маршрутизируется через Product/ListAsync. Для создания ссылки необходимо указать суффикс Async. Например:

<a asp-controller="Product" asp-action="ListAsync">List</a>

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

В ASP.NET Core 3,0 это действие маршрутизируется через Product/List. В коде создания ссылок следует опускать суффикс Async. Например:

<a asp-controller="Product" asp-action="List">List</a>

Это изменение не влияет на имена, указанные с атрибутом [ActionName]. Это поведение можно отключить, присвоив свойству MvcOptions.SuppressAsyncSuffixInActionNames значение false в Startup.ConfigureServices:

services.AddMvc(options =>
{
   options.SuppressAsyncSuffixInActionNames = false;
});

Причина изменения

По соглашению асинхронные методы .NET получают суффиксы Async. Но если метод определяет действие MVC, нежелательно использовать суффикс Async.

Если приложение зависит от того, сохранит ли действие MVC суффикс имени Async, выберите один из следующих способов устранения рисков:

  • примените атрибут [ActionName], чтобы сохранить исходное имя;
  • полностью отключите переименование, задав для MvcOptions.SuppressAsyncSuffixInActionNames значение false в Startup.ConfigureServices:
services.AddMvc(options =>
{
   options.SuppressAsyncSuffixInActionNames = false;
});

Категория

ASP.NET Core

Затронутые API

нет

MVC: JsonResult перемещен в Microsoft.AspNetCore.Mvc.Core

JsonResult перемещен в сборку Microsoft.AspNetCore.Mvc.Core. Этот тип используется для определения в Microsoft.AspNetCore.Mvc.Formatters.Json. Чтобы устранить эту ошибку для большинства пользователей, атрибут уровня сборки [TypeForwardedTo] добавлен в Microsoft.AspNetCore.Mvc.Formatters.Json. В приложениях, использующих сторонние библиотеки, могут возникать проблемы.

Введённая версия

3.0 Предварительный просмотр 6

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

Сборка приложения, использующего библиотеку на основе версии 2.2, проходит успешно.

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

Приложение, использующее библиотеку на основе версии 2.2 не может выполнить компиляцию. Указана ошибка, содержащая вариацию следующего текста:

The type 'JsonResult' exists in both 'Microsoft.AspNetCore.Mvc.Core, Version=3.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60' and 'Microsoft.AspNetCore.Mvc.Formatters.Json, Version=2.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'

Пример такой проблемы см. в разделе dotnet/aspnetcore#7220.

Причина изменения

Изменения на уровне платформы в структуре ASP.NET Core, как описано в разделе aspnet/Announcements#325.

Библиотекам, скомпилированным против Microsoft.AspNetCore.Mvc.Formatters.Json версии 2.2, возможно потребуется повторная компиляция, чтобы устранить проблему для всех потребителей. Если проблема возникла, обратитесь к автору библиотеки. Запросите перекомпиляцию библиотеки для платформы ASP.NET Core 3.0.

Категория

ASP.NET Core

Затронутые API

Microsoft.AspNetCore.Mvc.JsonResult

MVC: средство предварительной компиляции не рекомендуется

В ASP.NET Core 1.1 был введен пакет Microsoft.AspNetCore.Mvc.Razor.ViewCompilation (средство предварительной компиляции MVC), чтобы организовать поддержку компиляции файлов Razor во время публикации (файлы .cshtml). В ASP.NET Core 2.1 добавлен пакет SDK для Razor, который расширил возможности этого средства предварительной компиляции. Этот пакет SDK для Razor добавил поддержку компиляции файлов Razor во время сборки и публикации. Пакет SDK проверяет правильность файлов .cshtml во время сборки, что снижает время запуска приложения. Пакет SDK для Razor включен по умолчанию, и для его использования не требуется никаких действий.

В ASP.NET Core 3.0 было удалено средство предварительной компиляции MVC, сохранившееся с эпохи ASP.NET Core версии 1.1. Более ранние версии пакетов будут по-прежнему получать важные исправления ошибок и безопасности в выпусках исправлений.

Введённая версия

3.0

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

Для предварительной компиляции представлений Razor MVC использовался пакет Microsoft.AspNetCore.Mvc.Razor.ViewCompilation.

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

Пакет SDK для Razor имеет встроенную поддержку этой возможности. Пакет Microsoft.AspNetCore.Mvc.Razor.ViewCompilation более не обновляется.

Причина изменения

Пакет SDK для Razor дает больше возможностей и проверяет правильность файлов .cshtml во время сборки. Благодаря этому пакет SDK снижает время запуска приложения.

Если вы используете ASP.NET Core версии 2.1 или более поздней версии, обновите систему для применения встроенной поддержки предварительной компиляции в пакете SDK для Razor. Если ошибки или отсутствующие компоненты препятствуют миграции на пакет SDK для Razor, сообщите о проблеме в dotnet/aspnetcore.

Категория

ASP.NET Core

Затронутые API

нет

MVC: типы "Pubternal" изменились на внутренние типы

В ASP.NET Core 3.0 все типы pubternal (MVC) теперь стали public в поддерживаемом пространстве имен либо internal, если это более уместно.

Описание изменения

В ASP.NET Core типы pubternal объявляются как public, но находятся в пространстве имен с суффиксом .Internal. Хотя формально это типы public, для них отсутствует политика поддержки и они подвержены критическим изменениям. К сожалению, довольно часто эти типы использовались случайно, что приводило к критическим изменениям в таких проектах и ограничивало возможности, связанные с обслуживанием платформы.

Введённая версия

3.0

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

Некоторые типы в MVC имели тип public, но существовали в пространстве имен .Internal. Для таких типов отсутствовала политика поддержки и они подвергались серьезным изменениям.

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

Все такие типы теперь стали public в поддерживаемом пространстве имен, либо помечены как internal.

Причина изменения

Нередко типы "pubternal" использовались по ошибке, что приводило к нарушению совместимости в этих проектах и ограничивало возможность поддерживать фреймворк.

Если вы используете типы, которые действительно стали public и перемещены в новое поддерживаемое пространство имен, обновите ссылки так, чтобы они соответствовали новым пространствам имен.

Если вы используете типы, которые стали internal, вам нужно будет найти альтернативу. Типы, ранее обозначенные как "pubternal", никогда не предназначались для публичного использования. Если в этих пространствах имен есть типы, которые критически важны для ваших приложений, сообщите об этой проблеме в dotnet/aspnetcore. Мы готовы рассмотреть возможность преобразовать эти типы в public.

Категория

ASP.NET Core

Затронутые API

Это изменение включает типы в следующих пространствах имен:

  • Microsoft.AspNetCore.Mvc.Cors.Internal
  • Microsoft.AspNetCore.Mvc.DataAnnotations.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Json.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.Internal
  • Microsoft.AspNetCore.Mvc.Internal
  • Microsoft.AspNetCore.Mvc.ModelBinding.Internal
  • Microsoft.AspNetCore.Mvc.Razor.Internal
  • Microsoft.AspNetCore.Mvc.RazorPages.Internal
  • Microsoft.AspNetCore.Mvc.TagHelpers.Internal
  • Microsoft.AspNetCore.Mvc.ViewFeatures.Internal

MVC: удалена оболочка совместимости для веб-API

Начиная с пакета SDK для .NET Core 3.0, пакет Microsoft.AspNetCore.Mvc.WebApiCompatShim недоступен.

Описание изменения

Пакет Microsoft.AspNetCore.Mvc.WebApiCompatShim (WebApiCompatShim) обеспечивает в ASP.NET Core частичную совместимость с веб-API 2 для ASP.NET 4.x, чтобы упростить миграцию существующих реализаций веб-API на ASP.NET Core. Но при этом приложения, которые используют WebApiCompatShim, не могут воспользоваться функциями API из последних выпусков ASP.NET Core. Сюда относятся, среди прочего, улучшенное создание спецификаций Open API, стандартизованная обработка ошибок и создание клиентского кода. Чтобы уделить больше внимания развитию API в версии 3.0, WebApiCompatShim удален. Существующие приложения, которые используют WebApiCompatShim, необходимо перевести на новую модель [ApiController].

Введённая версия

3.0

Причина изменения

Оболочка совместимости веб-API была инструментом для миграции. Она ограничивает доступ пользователей к новым функциям, добавляемым в ASP.NET Core.

Перестаньте использовать shim и переходите сразу к аналогичным функциям в ASP.NET Core.

Категория

ASP.NET Core

Затронутые API

Microsoft.AspNetCore.Mvc.WebApiCompatShim

Razor: API RazorTemplateEngine был удалён

RazorTemplateEngine API был удален и заменён на Microsoft.AspNetCore.Razor.Language.RazorProjectEngine.

Обсуждение этого вопроса см. на странице GitHub dotnet/aspnetcore#25215.

Введённая версия

3.0

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

Для синтаксического анализа и создания кода для файлов Razor можно создать и использовать обработчик шаблонов.

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

Можно создать RazorProjectEngine и предоставить сведения того же типа, что и RazorTemplateEngine для анализа и создания кода для файлов Razor. RazorProjectEngine также предоставляет дополнительные уровни конфигурации.

Причина изменения

RazorTemplateEngine был слишком тесно связан с существующими реализациями. Эта тесная связь приводит к дополнительным вопросам при попытке правильной настройки конвейера анализа и формирования Razor.

Используйте RazorProjectEngine вместо RazorTemplateEngine. Рассмотрим следующие примеры.

Создание и настройка RazorProjectEngine
RazorProjectEngine projectEngine =
    RazorProjectEngine.Create(RazorConfiguration.Default,
        RazorProjectFileSystem.Create(@"C:\source\repos\ConsoleApp4\ConsoleApp4"),
        builder =>
        {
            builder.ConfigureClass((document, classNode) =>
            {
                classNode.ClassName = "MyClassName";

                // Can also configure other aspects of the class here.
            });

            // More configuration can go here
        });
Создание кода для файла Razor
RazorProjectItem item = projectEngine.FileSystem.GetItem(
    @"C:\source\repos\ConsoleApp4\ConsoleApp4\Example.cshtml",
    FileKinds.Legacy);
RazorCodeDocument output = projectEngine.Process(item);

// Things available
RazorSyntaxTree syntaxTree = output.GetSyntaxTree();
DocumentIntermediateNode intermediateDocument =
    output.GetDocumentIntermediateNode();
RazorCSharpDocument csharpDocument = output.GetCSharpDocument();

Категория

ASP.NET Core

Затронутые API

  • RazorTemplateEngine
  • RazorTemplateEngineOptions

Razor: компиляция среды выполнения перемещена в пакет

Компиляция во время выполнения представлений Razor и Razor Pages перемещена в отдельный пакет.

Введённая версия

3.0

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

Компиляция во время выполнения не требует дополнительных пакетов.

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

Функциональные возможности перенесены в пакет Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

Следующие API ранее были доступны в Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions для поддержки компиляции во время выполнения. Теперь эти API доступны через Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.MvcRazorRuntimeCompilationOptions.

  • RazorViewEngineOptions.FileProviders изменено на MvcRazorRuntimeCompilationOptions.FileProviders.
  • RazorViewEngineOptions.AdditionalCompilationReferences изменено на MvcRazorRuntimeCompilationOptions.AdditionalReferencePaths.

Кроме того, Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions.AllowRecompilingViewsOnFileChange теперь не используется. Повторная компиляция с учетом изменения файлов включена по умолчанию с использованием ссылки на пакет Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

Причина изменения

Это изменение было необходимо для удаления зависимости общей инфраструктуры ASP.NET Core от Roslyn.

Для приложений, требующих компиляции или перекомпиляции файлов Razor во время выполнения, требуются следующие действия:

  1. добавьте ссылку на пакет Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation;

  2. обновите метод Startup.ConfigureServices в проекте, чтобы включить вызов AddRazorRuntimeCompilation. Например:

    services.AddMvc()
    .AddRazorRuntimeCompilation();

Категория

ASP.NET Core

Затронутые API

Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions

Состояние сеанса: устаревшие API удалены

Удалены устаревшие API для настройки файлов cookie сеанса. Подробную информацию см. на странице aspnet/Announcements#257.

Введённая версия

3.0

Причина изменения

Это изменение обеспечивает согласованность между API для настройки функций, использующих файлы cookie.

Перенесите использование удаленных API в их новые замены. Рассмотрим следующий пример в Startup.ConfigureServices:

public void ConfigureServices(ServiceCollection services)
{
    services.AddSession(options =>
    {
        // Removed obsolete APIs
        options.CookieName = "SessionCookie";
        options.CookieDomain = "contoso.com";
        options.CookiePath = "/";
        options.CookieHttpOnly = true;
        options.CookieSecure = CookieSecurePolicy.Always;

        // new API
        options.Cookie.Name = "SessionCookie";
        options.Cookie.Domain = "contoso.com";
        options.Cookie.Path = "/";
        options.Cookie.HttpOnly = true;
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    });
}

Категория

ASP.NET Core

Затронутые API

Общая платформа: сборки удалены из Microsoft.AspNetCore.App

Начиная с ASP.NET Core версии 3.0 общая платформа ASP.NET Core (Microsoft.AspNetCore.App) содержит только сборки, которые полностью разработаны, поддерживаются и обслуживаются корпорацией Майкрософт.

Описание изменения

Думайте об изменении как о переопределении границ для платформы ASP.NET Core. Общий фреймворк будет собираемой из исходников любым человеком через GitHub и будет продолжать предлагать существующие преимущества общих фреймворков .NET Core для ваших приложений. К таким преимуществам относятся меньший размер развертывания, централизованная установка исправлений и сокращенное время запуска.

В рамках этого обновления в Microsoft.AspNetCore.App добавлены несколько критических изменений.

Введённая версия

3.0

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

Проекты ссылались на Microsoft.AspNetCore.App через элемент <PackageReference> в файле проекта.

Кроме того, в Microsoft.AspNetCore.App содержались следующие вложенные компоненты:

  • Json.NET (Newtonsoft.Json);
  • Entity Framework Core (сборки с префиксом Microsoft.EntityFrameworkCore.);
  • Roslyn (Microsoft.CodeAnalysis).

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

Ссылка на Microsoft.AspNetCore.App теперь не требует наличия элемента <PackageReference> в файле проекта. Пакет SDK для .NET Core поддерживает новый элемент с именем <FrameworkReference>, который заменяет собой <PackageReference>.

Подробную информацию см. на странице dotnet/aspnetcore#3612.

Entity Framework Core поставляется в формате пакетов NuGet. Это обновление приводит модель поставки в соответствие со схемой, принятой для всех остальных библиотек доступа к данным в .NET. Теперь в Entity Framework Core доступен самый простой способ продолжать разработку инноваций, пользуясь поддержкой любых платформ .NET. Несмотря на отделение от общей платформы Entity Framework Core остается библиотекой, разработанной, поддерживаемой и обслуживаемой корпорацией Майкрософт. На нее по-прежнему распространяется политика поддержки .NET Core.

Json.NET и Entity Framework Core будут и дальше работать с ASP.NET Core. Но теперь они не будут входить в состав общей платформы.

Дополнительные сведения см. в статье о перспективах для JSON в .NET Core 3.0. Также обратите внимание на то, что из общей платформы удален большой список двоичных файлов.

Причина изменения

Это изменение упрощает использование Microsoft.AspNetCore.App и сокращает дублирование функций между пакетами NuGet и общими платформами.

Дополнительные сведения о том, что подтолкнуло нас к этим изменениям, см. в этой записи блога.

Начиная с ASP.NET Core 3.0 в проектах больше не нужно использовать сборки из Microsoft.AspNetCore.App как пакеты NuGet. Чтобы упростить нацеливание и использование общей платформы ASP.NET Core, многие пакеты NuGet, подготовленные с момента выхода ASP.NET Core 1.0, больше не выпускаются. API-интерфейсы, которые предоставлялись в этих пакетах, по-прежнему доступны для приложений, используя ссылку <FrameworkReference> на Microsoft.AspNetCore.App. Сюда относятся, например, довольно популярные API Kestrel, MVC и Razor.

Это изменение не затрагивает двоичные файлы, которые указываются через Microsoft.AspNetCore.App в ASP.NET Core 2.x. Несколько важных исключений:

  • Библиотеки Microsoft.Extensions, которые по-прежнему нацелены на .NET Standard, доступны в виде пакетов NuGet (см. https://github.com/dotnet/extensions).
  • API-интерфейсы, которые выпускаются командой разработчиков ASP.NET Core и не входят в Microsoft.AspNetCore.App. Например, следующие компоненты доступны в виде пакетов NuGet:
    • Entity Framework Core (платформа для работы с базами данных)
    • API-интерфейсы, которые обеспечивают интеграцию с решениями сторонних разработчиков;
    • Экспериментальные функции
    • API-интерфейсы с зависимостями, которые не позволяют выполнить требования для включения в общую платформу.
  • Расширения MVC, которые сохраняют поддержку Json.NET. API-интерфейс предоставляется в виде пакета NuGet для поддержки работы с Json.NET и MVC. Подробнее см. в руководстве по миграции на ASP.NET Core.
  • Клиент SignalR для .NET будет и далее поддерживать .NET Standard и предоставляться в формате пакета NuGet. Он нужен для многих сред выполнения .NET, включая Xamarin и UWP.

Подробные сведения см. в объявлении о прекращении выпуска пакетов для сборок общей платформы начиная с версии 3.0. Обсуждение этого вопроса см. на странице dotnet/aspnetcore#3757.

Категория

ASP.NET Core

Затронутые API

Общая платформа: удалена Microsoft.AspNetCore.All

Начиная с ASP.NET Core 3.0, метапакет Microsoft.AspNetCore.All и соответствующая общая платформа Microsoft.AspNetCore.All больше не создаются. Этот пакет доступен в ASP.NET Core 2.2 и по-прежнему будет принимать обновления для обслуживания в ASP.NET Core 2.1.

Введённая версия

3.0

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

Приложения могут использовать метапакет Microsoft.AspNetCore.All для нацеливания на общий фреймворк Microsoft.AspNetCore.All в .NET Core.

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

.NET Core 3.0 не содержит общую платформу Microsoft.AspNetCore.All.

Причина изменения

Метапакет Microsoft.AspNetCore.All включал большое количество внешних зависимостей.

Перенесите проект для использования платформы Microsoft.AspNetCore.App. Компоненты, которые ранее были доступны в Microsoft.AspNetCore.All, по-прежнему будут доступными в NuGet. Теперь эти компоненты развертываются вместе с приложением, а не включаются в общую платформу.

Категория

ASP.NET Core

Затронутые API

нет

SignalR: HandshakeProtocol.SuccessHandshakeData заменён

Поле HandshakeProtocol.SuccessHandshakeData было удалено и заменено вспомогательным методом, который создает ответ об успешном рукопожатии с учетом определенного IHubProtocol.

Введённая версия

3.0

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

HandshakeProtocol.SuccessHandshakeData являлось полем public static ReadOnlyMemory<byte>.

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

HandshakeProtocol.SuccessHandshakeData заменено методом staticGetSuccessfulHandshake(IHubProtocol protocol), который возвращает ReadOnlyMemory<byte> на основе указанного протокола.

Причина изменения

Дополнительные поля были добавлены в ответ рукопожатия, которые не являются константами и изменяются в зависимости от выбранного протокола.

Нет. Этот тип не предназначен для использования в пользовательском коде. Это public, поэтому он может быть общим для сервера SignalR и клиента. Он также может использоваться клиентами SignalR пользователя, написанными на .NET. Это изменение не влияет на пользователей SignalR.

Категория

ASP.NET Core

Затронутые API

HandshakeProtocol.SuccessHandshakeData

SignalR: методы ResetSendPing и ResetTimeout удалены из HubConnection

Методы ResetSendPing и ResetTimeout были удалены из API HubConnection в SignalR. Эти методы изначально предназначались только для внутреннего использования, но стали общедоступными в ASP.NET Core 2.2. Эти методы не будут доступны начиная с выпуска ASP.NET Core 3.0 (предварительная версия 4). Обсуждение этого вопроса см. на странице dotnet/aspnetcore#8543.

Введённая версия

3.0

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

API были доступны.

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

API удалены.

Причина изменения

Эти методы изначально предназначались только для внутреннего использования, но стали общедоступными в ASP.NET Core 2.2.

Не используйте эти методы.

Категория

ASP.NET Core

Затронутые API

SignalR: был изменён конструктор HubConnectionContext

Конструкторы HubConnectionContext SignalR были изменены, чтобы принимать тип настроек вместо нескольких отдельных параметров, с целью облегчить добавление настроек в будущем. Это изменение заменяет два конструктора одним конструктором, принимающим тип параметров.

Введённая версия

3.0

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

HubConnectionContext имеет два конструктора:

public HubConnectionContext(ConnectionContext connectionContext, TimeSpan keepAliveInterval, ILoggerFactory loggerFactory);
public HubConnectionContext(ConnectionContext connectionContext, TimeSpan keepAliveInterval, ILoggerFactory loggerFactory, TimeSpan clientTimeoutInterval);

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

Два конструктора были удалены и заменены одним конструктором:

public HubConnectionContext(ConnectionContext connectionContext, HubConnectionContextOptions contextOptions, ILoggerFactory loggerFactory)

Причина изменения

Новый конструктор использует новый объект параметров. Следовательно, функции HubConnectionContext можно расширить в будущем, не создавая дополнительные конструкторы и не внося критические изменения.

Вместо использования следующего конструктора:

HubConnectionContext connectionContext = new HubConnectionContext(
    connectionContext,
    keepAliveInterval: TimeSpan.FromSeconds(15),
    loggerFactory,
    clientTimeoutInterval: TimeSpan.FromSeconds(15));

Используйте следующий конструктор:

HubConnectionContextOptions contextOptions = new HubConnectionContextOptions()
{
    KeepAliveInterval = TimeSpan.FromSeconds(15),
    ClientTimeoutInterval = TimeSpan.FromSeconds(15)
};
HubConnectionContext connectionContext = new HubConnectionContext(connectionContext, contextOptions, loggerFactory);

Категория

ASP.NET Core

Затронутые API

SignalR: изменено имя клиентского пакета JavaScript

В ASP.NET Core 3.0 (предварительная версия 7) имя клиентского пакета JavaScript для SignalR изменилось с @aspnet/signalr на @microsoft/signalr. Изменение имени отражает тот факт, что SignalR используется не только в приложениях ASP.NET Core благодаря поддержке Службы Azure SignalR.

Чтобы отреагировать на это изменение, измените ссылки в файлах package.JSON, а также инструкциях require и import ECMAScript. Это переименование не повлияет на API.

Обсуждение этого вопроса см. на странице dotnet/aspnetcore#11637.

Введённая версия

3.0

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

Пакет клиента назывался @aspnet/signalr.

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

Пакет клиента называется @microsoft/signalr.

Причина изменения

Изменение имени отражает тот факт, что SignalR используется не только в приложениях ASP.NET Core благодаря поддержке Службы Azure SignalR.

Переключитесь на новый пакет @microsoft/signalr.

Категория

ASP.NET Core

Затронутые API

нет

SignalR: методы UseSignalR и UseConnections помечены как устаревшие

Методы UseConnections и UseSignalR, а также классы ConnectionsRouteBuilder и HubRouteBuilder обозначены как устаревшие в ASP.NET Core 3.0.

Введённая версия

3.0

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

Маршрутизация концентратора SignalR была настроена с помощью UseSignalR или UseConnections.

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

Старый способ настройки маршрутизации считается устаревшим и был заменен маршрутизацией конечных точек.

Причина изменения

ПО промежуточного слоя перемещается в новую систему маршрутизации конечных точек. Старый способ добавления ПО промежуточного слоя считается устаревшим.

Замените UseSignalR на UseEndpoints:

Старый код:

app.UseSignalR(routes =>
{
    routes.MapHub<SomeHub>("/path");
});

Новый код:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHub<SomeHub>("/path");
});

Категория

ASP.NET Core

Затронутые API

SpAs: SpaServices и NodeServices помечены как устаревшие

Содержимое указанных ниже пакетов NuGet стало полностью ненужным, начиная с версии ASP.NET Core 2.1. В результате следующие пакеты отмечены как устаревшие:

По той же причине следующие модули npm отмечены как нерекомендуемые:

Все указанные выше пакеты и модули npm будут удалены в версии .NET 5.

Введённая версия

3.0

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

Нерекомендуемые пакеты и модули NPM предназначались для интеграции ASP.NET Core с разными платформами одностраничных приложений (SPA). К ним относятся Angular, React и React с Redux.

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

В пакете NuGet Microsoft.AspNetCore.SpaServices.Extensions реализован новый механизм интеграции. Этот пакет остается основой для шаблонов проектов Angular и React, начиная с ASP.NET Core 2.1.

Причина изменения

ASP.NET Core поддерживает интеграцию с несколькими платформами одностраничных приложений (SPA), включая Angular, React и React с Redux. Изначально интеграция с этими платформами устанавливалась с помощью специальных компонентов ASP.NET Core, которые обрабатывали такие сценарии, как предварительная визуализация на стороне сервера и интеграция с пакетом Webpack. Но отраслевые стандарты постепенно изменились. Каждый из фреймворков SPA выпустил свой собственный стандартный интерфейс командной строки. Например, Angular CLI и create-react-app.

При выпуске ASP.NET Core 2.1 в мае 2018 года наши разработчики внесли обновления в соответствии с этим изменением стандартов. Мы предоставили новый и более простой способ для интеграции с цепочками инструментов разных платформ SPA. Новый механизм интеграции реализован в пакете Microsoft.AspNetCore.SpaServices.Extensions и стал основой для шаблонов проектов Angular и React, начиная с ASP.NET Core 2.1.

Чтобы не оставалось сомнений, что старые специальные компоненты ASP.NET Core стали не нужны и их использование не рекомендуется, внесены следующие изменения:

  • механизм интеграции, существовавший до версии 2.1, отмечен как устаревший;
  • вспомогательные пакеты npm отмечены как нерекомендуемые.

Если вы применяете эти пакеты, обновите приложения, чтобы они использовали следующие функции:

  • В пакете Microsoft.AspNetCore.SpaServices.Extensions.
  • предоставленные той платформой SPA, которую вы используете.

Чтобы поддерживать такие функции, как предварительная визуализация на стороне сервера и горячая перезагрузка модулей, изучите документацию по соответствующей платформе SPA. Функциональность Microsoft.AspNetCore.SpaServices.Extensionsне считается устаревшей и будет поддерживаться в дальнейшем.

Категория

ASP.NET Core

Затронутые API

SPAs: SpaServices и NodeServices больше не полагаются на журналирование в консоль

Microsoft.AspNetCore.SpaServices и Microsoft.AspNetCore.NodeServices больше не отображают журналы консоли, если ведение журналов не настроено.

Введённая версия

3.0

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

Microsoft.AspNetCore.SpaServices и Microsoft.AspNetCore.NodeServices использовались для автоматического создания средства для ведения журналов консоли в тех случаях, если ведение журналов не было настроено.

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

Microsoft.AspNetCore.SpaServices и Microsoft.AspNetCore.NodeServices больше не отображают журналы консоли, если ведение журналов не настроено.

Причина изменения

Необходимость в согласованной реализации ведения журналов с другими пакетами ASP.NET Core.

Если требуется прежнее поведение, добавьте services.AddLogging(builder => builder.AddConsole()) к методу Setup.ConfigureServices, чтобы настроить логирование в консоль.

Категория

ASP.NET Core

Затронутые API

нет

Целевая платформа: прекращена поддержка .NET Framework

Начиная с ASP.NET Core 3.0, .NET Framework больше не поддерживается как целевая платформа.

Описание изменения

.NET Framework 4.8 — это последняя основная версия .NET Framework. Новые приложения ASP.NET Core следует создавать на основе .NET Core. Начиная с выпуска .NET Core 3.0 вы можете считать ASP.NET Core 3.0 частью .NET Core.

Клиенты, использующие ASP.NET Core совместно с .NET Framework, могут и дальше получать полноценную поддержку, используя выпуск 2.1 LTS. Поддержка и обслуживание для выпуска 2.1 сохранится по меньшей мере до 21 августа 2021 г. Эта дата наступает через три года после объявления выпуска LTS в соответствии с политикой поддержки .NET. Поддержка пакетов ASP.NET Core 2.1 на платформе .NET Framework будет продолжаться неограниченное время, аналогично политике обслуживания для других платформ ASP.NET на основе пакетов.

Дополнительные сведения о переносе кода из .NET Core в .NET Framework см. в этой статье.

Это изменение не коснется пакетов Microsoft.Extensions (сюда относятся ведение журнала, внедрение зависимостей и конфигурация) и Entity Framework Core. Они будут продолжать поддерживать .NET Standard.

Дополнительные сведения о том, что привело нас в этим изменениям, см. в исходной записи блога.

Введённая версия

3.0

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

Приложения ASP.NET Core могли работать на основе .NET Core или .NET Framework.

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

Приложения ASP.NET Core версии будут выполняться только в .NET Core.

Выполните одно из следующих действий:

  • Сохраните приложение в ASP.NET Core 2.1.
  • Перенесите приложения и все его зависимости на .NET Core.

Категория

ASP.NET Core

Затронутые API

нет

Основные библиотеки .NET

Интерфейсы API, сообщающие версию, теперь сообщают версию продукта, а не файла

Многие интерфейсы API, которые возвращают версию в .NET Core, теперь возвращают версию продукта, а не файла.

Описание изменения

В .NET Core 2.2 и предыдущих версиях такие методы, как Environment.Version, RuntimeInformation.FrameworkDescription и диалоговое окно свойств файла для сборок .NET Core, сообщают версию файла. Начиная с версии .NET Core 3.0, они сообщают версию продукта.

На приведенном ниже рисунке показана разница в сведениях о версии для сборки System.Runtime.dll для .NET Core 2.2 (слева) и .NET Core 3.0 (справа), отображаемых в диалоговом окне свойств файла в проводнике.

Разница в сведениях о версии продукта

Введённая версия

3.0

Нет. Это изменение должно сделать определение версии интуитивно понятным.

Категория

Основные библиотеки .NET

Затронутые API

Пользовательские экземпляры EncoderFallbackBuffer не поддерживают рекурсивный откат

Пользовательские экземпляры EncoderFallbackBuffer не поддерживают рекурсивный возврат. В результате реализации EncoderFallbackBuffer.GetNextChar() должна быть создана последовательность символов, которая преобразуется в целевую кодировку. В противном случае возникает исключение.

Описание изменения

При перекодировании символов в байты среда выполнения обнаруживает некорректные или непреобразуемые последовательности UTF-16 и передает эти символы методу EncoderFallbackBuffer.Fallback. Метод Fallback определяет, какие символы следует заменить в исходных непреобразуемых данных, и эти символы удаляются путем вызова EncoderFallbackBuffer.GetNextChar в цикле.

Затем среда выполнения пытается перекодировать эти символы подстановки в целевую кодировку. Если это удалось выполнить, среда выполнения продолжит перекодировку с того места, где она остановилась на исходной входной строке.

Ранее пользовательские реализации EncoderFallbackBuffer.GetNextChar() могли возвращать последовательности символов, которые нельзя преобразовать в целевую кодировку. Если подставляемые символы не могут быть перекодированы в целевую кодировку, во время выполнения снова вызывается метод EncoderFallbackBuffer.Fallback с символами подстановки, ожидая, что метод EncoderFallbackBuffer.GetNextChar() вернет новую последовательность символов подстановки. Этот процесс продолжится до тех пор, пока среда выполнения не обнаружит правильно сформированную и преобразуемую замену или пока не будет достигнуто максимальное число рекурсий.

Начиная с версии .NET Core 3.0, пользовательские реализации EncoderFallbackBuffer.GetNextChar() должны возвращать последовательности символов, преобразуемые в целевую кодировку. Если замещаемые символы нельзя перекодировать в целевую кодировку, создается исключение ArgumentException. Среда выполнения больше не будет выполнять рекурсивные вызовы к экземпляру EncoderFallbackBuffer.

Такой подход применяется только в том случае, если выполнены все следующие три условия:

  • Среда выполнения обнаруживает последовательность UTF-16, которая была неправильно сформирована или не подлежит преобразованию в целевую кодировку.
  • Задана пользовательская EncoderFallback.
  • Пользовательская реализация EncoderFallback пытается заменить новую неправильно сформированную или непреобразуемую последовательность UTF-16.

Введённая версия

3.0

В большинстве случаев от разработчиков не требуется никаких действий.

Если приложение использует пользовательский класс EncoderFallback и EncoderFallbackBuffer, убедитесь, что реализация EncoderFallbackBuffer.Fallback заполняет буфер отката правильно сформированными данными UTF-16, которые можно сразу же преобразовать в целевую кодировку, когда среда выполнения впервые вызывает метод Fallback.

Категория

Основные библиотеки .NET

Затронутые API

Изменено поведение форматирования и разбора данных с плавающей запятой

Поведение форматирования и анализа при наличии плавающей запятой (с помощью типов Double и Single) теперь совместимо со стандартами IEEE. Благодаря этому поведение типов с плавающей запятой в .NET соответствует их поведению в языках, совместимых с IEEE. Например, результат double.Parse("SomeLiteral") всегда должен совпадать с результатом, создаваемым в C# для double x = SomeLiteral.

Описание изменения

В .NET Core 2.2 и более ранних версиях форматирование с помощью Double.ToString и Single.ToString и анализ с помощью Double.Parse, Double.TryParse, Single.Parse и Single.TryParse не были совместимы со стандартами IEEE. В результате это не позволяло гарантировать, что значение будет соответствовать какой-либо поддерживаемой стандартной или пользовательской строке формата. Для некоторых входных данных попытка проанализировать отформатированное значение может завершиться ошибкой, а для других — проанализированное значение не равно исходному.

Начиная с .NET Core 3.0, операции анализа и форматирования для чисел с плавающей запятой совместимы со стандартом IEEE 754.

В следующей таблице показаны два фрагмента кода и отличие выходных данных между .NET Core 2.2 и .NET Core 3.1.

Фрагмент кода Выходные данные в .NET Core 2.2 Выходные данные в .NET Core 3.1
Console.WriteLine((-0.0).ToString()); 0 0–
var value = -3.123456789123456789;
Console.WriteLine(value == double.Parse(value.ToString()));		 False True

Дополнительные сведения см. в записи блога Улучшения в синтаксическом анализе и форматировании плавающей запятой в .NET Core 3.0.

Введённая версия

3.0

В разделе Потенциальное воздействие на существующий код записи блога Улучшения в синтаксическом анализе и форматировании чисел с плавающей запятой в .NET Core 3.0 предлагаются изменения, которые можно внести в код, чтобы сохранить предыдущее поведение.

  • Для некоторых изменений в форматировании можно получить поведение, эквивалентное предыдущему поведению, указав другую строку форматирования.
  • Но для изменений в синтаксическом анализе не существует механизма, позволяющего вернуть предыдущее поведение.

Категория

Основные библиотеки .NET

Затронутые API

Операции синтаксического анализа с плавающей запятой больше не завершаются ошибкой и не вызывают исключение OverflowException

Методы синтаксического анализа с плавающей запятой больше не вызывают OverflowException и не возвращают false при синтаксическом анализе строки, числовое значение которой находится вне диапазона типа с плавающей запятой Single или Double.

Описание изменения

В .NET Core 2.2 и более ранних версиях методы Double.Parse и Single.Parse вызывают OverflowException для значений, которые выходят за пределы диапазона соответствующего типа. Методы Double.TryParse и Single.TryParse возвращают false для строковых представлений числовых значений вне диапазона.

Начиная с .NET Core 3.0 методы Double.Parse, Double.TryParse, Single.Parse и Single.TryParse больше не вызывают ошибку при проверке числовых строк вне диапазона. Вместо этого методы синтаксического анализа Double возвращают Double.PositiveInfinity для значений, превышающих Double.MaxValue, и Double.NegativeInfinity — для значений, которые меньше Double.MinValue. Подобным образом, методы синтаксического анализа Single возвращают Single.PositiveInfinity для значений, превышающих Single.MaxValue, и Single.NegativeInfinity — для значений, которые меньше Single.MinValue.

Это изменение было внесено для улучшения соответствия требованиям IEEE 754:2008.

Введённая версия

3.0

Это изменение может повлиять на код одним из двух способов:

  • Код зависит от обработчика OverflowException для выполнения при переполнении. В этом случае следует удалить оператор catch и поместить необходимый код в оператор If, который проверяет, является ли Double.IsInfinity или Single.IsInfinitytrue.

  • В коде предполагается, что значения с плавающей запятой не являются Infinity. В этом случае следует добавить необходимый код для проверки значений с плавающей запятой PositiveInfinity и NegativeInfinity.

Категория

Основные библиотеки .NET

Затронутые API

Исключение InvalidAsynchronousStateException перенесено в другую сборку

Класс InvalidAsynchronousStateException перемещен.

Описание изменения

В .NET Core 2.2 и более ранних версиях класс InvalidAsynchronousStateException находится в сборке System.ComponentModel.TypeConverter.

Начиная с .NET Core 3.0, он находится в сборке System.ComponentModel.Primitives.

Введённая версия

3.0

Это изменение влияет исключительно на приложения, которые используют механизм отражения для загрузки InvalidAsynchronousStateException путем вызова метода, такого как Assembly.GetType, или перегруженной версии метода Activator.CreateInstance, если предполагается, что тип присутствует в конкретной сборке. В этом случае обновите сборку, указанную в вызове метода, в соответствии с новым расположением сборки типа.

Категория

Основные библиотеки .NET

Затронутые API

Нет.

Замена неправильно сформированных последовательностей байтов в кодировке UTF-8 в соответствии с правилами Юникода

UTF8Encoding Когда класс сталкивается с неправильно сформированной последовательностью байтов UTF-8 во время операции перекодирования байтов к символам, он заменяет такую последовательность символом ' (U+FFFD REPLACE CHARACTER) в выходной строке. В .NET Core 3.0, в отличие от предыдущих версий .NET Core и .NET Framework, применяются рекомендации по Юникоду для таких замен при операциях перекодирования.

Это лишь часть больших усилий улучшить обработку данных в формате UTF-8 в .NET, включая новые типы System.Text.Unicode.Utf8 и System.Text.Rune. Для типа UTF8Encoding предоставлен улучшенный механизм обработки ошибок, чтобы его выходные данные соответствовали новым типам.

Описание изменения

Начиная с .NET Core 3.0, при перекодировании байтов в символы класс UTF8Encoding выполняет подстановку символов на основе рекомендаций по Юникоду. Используемый механизм подстановки описан в стандарте "Юникод", версия 12.0, раздел 3.9 (PDF) под заголовком U+FFFD Substitution of Maximal Subparts.

Такой подход применяется только в том случае, если входная последовательность байтов содержит некорректные данные в кодировке UTF-8. Кроме того, если экземпляр UTF8Encoding был создан с помощью throwOnInvalidBytes: true, экземпляр UTF8Encoding будет и дальше выдавать исключение при недопустимых входных данных, а не выполнять замену символом U+FFFD. Дополнительные сведения о конструкторе UTF8Encoding см. в статье UTF8Encoding(Boolean, Boolean).

В следующей таблице показано влияние этого изменения на примере недопустимых 3-байтовых входных данных.

Некорректно сформированные 3-байтовые входные данные Выходные данные в версиях до .NET Core 3.0 Выходные данные в .NET Core 3.0 и более поздних версиях
[ ED A0 90 ] [ FFFD FFFD ] (выходные данные в виде двухзначного кода) [ FFFD FFFD FFFD ] (выходные данные в виде трехзначного кода)

Согласно таблице 3-9 из PDF-документа по Юникоду, ссылка на который приведена выше, предпочтительным является вариант с выходными данными в виде трехзначного кода.

Введённая версия

3.0

От разработчика не требуется никаких действий.

Категория

Основные библиотеки .NET

Затронутые API

Класс TypeDescriptionProviderAttribute перенесен в другую сборку

Класс TypeDescriptionProviderAttribute перемещен.

Описание изменения

В .NET Core 2.2 и более ранних версиях класс TypeDescriptionProviderAttribute находится в сборке System.ComponentModel.TypeConverter.

Начиная с .NET Core 3.0 он находится в сборке System.ObjectModel.

Введённая версия

3.0

Это изменение влияет только на приложения, использующие отражение для загрузки типа TypeDescriptionProviderAttribute путем вызова метода, такого как Assembly.GetType, или перегрузки Activator.CreateInstance, которая предполагает, что тип находится в определенной сборке. В этом случае сборку, указанную в вызове метода, необходимо обновить в соответствии с новым расположением сборки типа.

Категория

Windows Forms

Затронутые API

Нет.

ZipArchiveEntry больше не обрабатывает архивы с несогласованными размерами записей

Для ZIP-архивов указывается размер в сжатом и несжатом виде в центральном каталоге и в локальном заголовке. В данных записи также содержится информация о ее размере. В .NET Core 2.2 и более ранних версиях эти значения не проверялись на согласованность. Начиная с версии .NET Core 3.0, это стало возможным.

Описание изменения

В .NET Core 2.2 и более ранних версиях метод ZipArchiveEntry.Open() выполняется успешно, даже если данные в локальном заголовке не совпадают с данными в центральном заголовке ZIP-файла. Данные распаковываются до тех пор, пока не будет достигнут конец сжатого потока, даже если его длина превышает размер несжатого файла, указанный в центральном каталоге или в локальном заголовке.

Начиная с .NET Core 3.0 метод ZipArchiveEntry.Open() проверяет, чтобы данные в локальном и центральном заголовках о размерах сжатой и несжатой записи были согласованными. Если они этого не сделают, метод вызовет исключение InvalidDataException, если размеры локального заголовка и/или дескриптора данных архива отличаются от размеров в центральном каталоге ZIP-файла. При считывании записи распакованные данные усекаются до размера несжатого файла, который указан в заголовке.

Это изменение позволит ZipArchiveEntry корректно представлять размер данных и обеспечит считывание именно такого объема данных.

Введённая версия

3.0

Переархивируйте все ZIP-файлы, с которыми возникают такие проблемы.

Категория

Основные библиотеки .NET

Затронутые API

FieldInfo.SetValue вызывает исключение для статических полей и полей только для инициализации

Начиная с .NET Core версии 3.0, при попытке задать значение в статическом поле InitOnly путем вызова System.Reflection.FieldInfo.SetValue, возникает исключение.

Описание изменения

В .NET Framework и версиях .NET Core до 3.0 можно было задать значение статического поля, которое являлось константой после его инициализации (только для чтения в C#) путем вызова System.Reflection.FieldInfo.SetValue. Однако установка такого поля таким образом приведет к непредсказуемому поведению в зависимости от целевой платформы и параметров оптимизации.

В .NET Core 3.0 и более поздних версиях, при вызове SetValue для статического поля InitOnly создается исключение System.FieldAccessException.

Совет

Поле InitOnly — это поле, которое можно задать только во время объявления или в конструкторе содержащего класса. Иными словами, оно остается константой после инициализации.

Введённая версия

3.0

Инициализируйте статические поля InitOnly в статическом конструкторе. Это относится как к динамическим, так и к не динамическим типам.

Кроме того, можно удалить атрибут FieldAttributes.InitOnly из поля, а затем вызвать FieldInfo.SetValue.

Категория

Основные библиотеки .NET

Затронутые API

Передача GroupCollection в методы расширения, принимающие IEnumerable<T>, требует разрешения неоднозначностей

При вызове метода расширения, который принимает IEnumerable<T> на GroupCollection, необходимо устранить неоднозначность типа с помощью приведения.

Описание изменения

Начиная с .NET Core 3.0 System.Text.RegularExpressions.GroupCollection реализует IEnumerable<KeyValuePair<String,Group>> в дополнение к другим реализуемым типам, включая IEnumerable<Group>. Это приводит к неоднозначности при вызове метода расширения, который принимает IEnumerable<T>. При вызове такого метода расширения в экземпляре GroupCollection, например Enumerable.Count, вы увидите следующую ошибку компилятора:

CS1061: GroupCollection не содержит определения для Count, и нет доступного метода расширения Count, принимающего первый аргумент типа GroupCollection (отсутствует директива using или ссылка на сборку?)

В предыдущих версиях .NET не существовало неоднозначности и не было таких ошибок компилятора.

Введённая версия

3.0

Причина изменения

Это было непреднамеренное ломающее изменение. Поскольку так происходит уже некоторое время, мы не планируем это изменять. Кроме того, такое изменение само по себе будет разрушающим.

Для экземпляров GroupCollection устраните неоднозначность вызовов методов расширения, которые принимают IEnumerable<T>, путем приведения.

// Without a cast - causes CS1061.
match.Groups.Count(_ => true)

// With a disambiguating cast.
((IEnumerable<Group>)m.Groups).Count(_ => true);

Категория

Основные библиотеки .NET

Затронутые API

Затрагиваются все методы расширения, принимающие IEnumerable<T>. Например:

Шифрование

Синтаксис "BEGIN TRUSTED CERTIFICATE" больше не поддерживается для корневых сертификатов в Linux

Корневые сертификаты в Linux и других Unix-подобных системах (но не macOS) можно представить в двух формах: стандартный заголовок PEM BEGIN CERTIFICATE и относящийся к OpenSSL заголовок PEM BEGIN TRUSTED CERTIFICATE. Последний синтаксис допускает дополнительную конфигурацию, которая вызвала проблемы совместимости с классом System.Security.Cryptography.X509Certificates.X509Chain .NET Core. Содержимое корневого сертификата BEGIN TRUSTED CERTIFICATE больше не загружается подсистемой цепочек, начиная с .NET Core 3.0.

Описание изменения

Ранее синтаксисы BEGIN CERTIFICATE и BEGIN TRUSTED CERTIFICATE использовались для заполнения списка корневого доверия. Если использовался синтаксис BEGIN TRUSTED CERTIFICATE и в файле были указаны дополнительные параметры, X509Chain мог сообщить о том, что доверие цепочки было явно запрещено (X509ChainStatusFlags.ExplicitDistrust). Однако если сертификат был также указан с использованием синтаксиса BEGIN CERTIFICATE в ранее загруженном файле, доверие цепочки было разрешено.

Начиная с .NET Core 3.0 содержимое BEGIN TRUSTED CERTIFICATE больше не считывается. Если сертификат также не указан с использованием стандартного синтаксиса BEGIN CERTIFICATE, X509Chain сообщает о том, что корень не является доверенным (X509ChainStatusFlags.UntrustedRoot).

Введённая версия

3.0

Это изменение не затрагивает большинство приложений, но приложения, которые не могут видеть оба источника корневых сертификатов из-за проблем с разрешениями, могут столкнуться с непредвиденными ошибками UntrustedRoot после обновления.

Многие дистрибутивы Linux записывают корневые сертификаты в два места: каталог, где каждый сертификат находится в отдельном файле, и один файл, содержащий все сертификаты вместе. В некоторых дистрибутивах каталог, где каждый файл содержит отдельный сертификат, использует синтаксис BEGIN TRUSTED CERTIFICATE, а при объединении файлов используется стандартный синтаксис BEGIN CERTIFICATE. Убедитесь, что все пользовательские корневые сертификаты добавляются как BEGIN CERTIFICATE по меньшей мере в одно из этих расположений, а сами эти расположения могут быть считаны приложением.

Типичным каталогом является /etc/ssl/certs/, а типичным объединенным файлом — /etc/ssl/cert.pem. Используйте команду openssl version -d, чтобы определить корневой каталог, зависящий от платформы, который может отличаться от /etc/ssl/. Например, в Ubuntu 18.04 этим каталогом является /usr/lib/ssl/certs/, а этим файлом — /usr/lib/ssl/cert.pem. Однако /usr/lib/ssl/certs/ является символьной ссылкой на /etc/ssl/certs/, и /usr/lib/ssl/cert.pem не существует.

$ openssl version -d
OPENSSLDIR: "/usr/lib/ssl"
$ ls -al /usr/lib/ssl
total 12
drwxr-xr-x  3 root root 4096 Dec 12 17:10 .
drwxr-xr-x 73 root root 4096 Feb 20 15:18 ..
lrwxrwxrwx  1 root root   14 Mar 27  2018 certs -> /etc/ssl/certs
drwxr-xr-x  2 root root 4096 Dec 12 17:10 misc
lrwxrwxrwx  1 root root   20 Nov 12 16:58 openssl.cnf -> /etc/ssl/openssl.cnf
lrwxrwxrwx  1 root root   16 Mar 27  2018 private -> /etc/ssl/private

Категория

Шифрование

Затронутые API

Для EnvelopedCms по умолчанию используется шифрование AES-256

Алгоритм симметричного шифрования по умолчанию, используемый EnvelopedCms, изменен с TripleDES на AES-256.

Описание изменения

В прошлых версиях при использовании EnvelopedCms для шифрования данных без указания алгоритма симметричного шифрования с помощью перегрузки конструктора данные зашифровываются с помощью алгоритма TripleDES/3DES/3DEA/DES3-EDE.

Начиная с .NET Core 3.0 (через версию 4.6.0 пакета NuGet System.Security.Cryptography.Pkcs) алгоритм по умолчанию изменён на AES-256 для модернизации алгоритмов и повышения безопасности стандартных параметров. Если в сертификате получателя сообщения используется открытый ключ Диффи-Хеллмана (не EC) операция шифрования может завершиться ошибкой CryptographicException из-за ограничений базовой платформы.

В приведенном ниже примере кода показано, что в .NET Core 2.2 и более ранних версиях для шифрования данных используется TripleDES. При работе в .NET Core 3.0 и более поздних версиях для шифрования используется AES-256.

EnvelopedCms cms = new EnvelopedCms(content);
cms.Encrypt(recipient);
return cms.Encode();

Введённая версия

3.0

Если изменение отрицательно повлияет на работу, можете восстановить шифрование TripleDES, явно указав идентификатор алгоритма шифрования в конструкторе EnvelopedCms, который содержит параметр типа AlgorithmIdentifier, например:

Oid tripleDesOid = new Oid("1.2.840.113549.3.7", null);
AlgorithmIdentifier tripleDesIdentifier = new AlgorithmIdentifier(tripleDesOid);
EnvelopedCms cms = new EnvelopedCms(content, tripleDesIdentifier);

cms.Encrypt(recipient);
return cms.Encode();

Категория

Шифрование

Затронутые API

Увеличен минимальный размер создаваемых ключей RSAOpenSsl

Минимальный размер создаваемых ключей RSA в Linux увеличен с 384 до 512 бит.

Описание изменения

Начиная с версии .NET Core 3.0, минимальный допустимый размер ключа, сообщаемый свойством LegalKeySizes для экземпляров RSA из RSA.Create, RSAOpenSsl и RSACryptoServiceProvider в Linux, увеличился с 384 до 512.

В результате в .NET Core 2.2 и более ранних версий вызов такого метода, как RSA.Create(384), выполняется успешно. В .NET Core 3.0 и более поздних версий при вызове метода RSA.Create(384) создается исключение, указывающее на то, что размер слишком мал.

Изменение было внесено, поскольку OpenSSL, который выполняет криптографические операции в Linux, поднял минимальную поддерживаемую версию с 1.0.2 до 1.1.0. В .NET Core 3.0 предпочтительно использовать OpenSSL версии 1.1.x, нежели 1.0.x, и минимально поддерживаемая версия была повышена, чтобы отразить эту новую более высокую зависимость.

Введённая версия

3.0

Если вы вызываете любой затронутый API-интерфейс, убедитесь, что размер созданных ключей не меньше минимального значения, установленного поставщиком.

Примечание.

Стандарт 384-битового шифрования RSA уже считается небезопасным (как и стандарт 512-битового шифрования). В современных документах, таких как NIST Special Publication 800-57 Part 1 Revision 4 (Специальная публикация NIST 800-57, часть 1, редакция 4), рекомендуется создавать ключи с минимальным размером 2048 бит.

Категория

Шифрование

Затронутые API

Для .NET Core 3.0 более предпочтительным является использование OpenSSL 1.1.x вместо OpenSSL 1.0.x

.NET Core с поддержкой разных дистрибутивов Linux также поддерживает OpenSSL 1.0.x и OpenSSL 1.1.x. .NET Core 2.1 и .NET Core 2.2 в первую очередь ищут версию 1.0.x и только потом версию 1.1.x; .NET Core 3.0 в первую очередь ищет версию 1.1.x. Это изменение было внесено, чтобы реализовать поддержку новых криптографических стандартов.

Это изменение может повлиять на библиотеки или приложения, которые отвечают за взаимодействие между платформой и типами взаимодействия на основе OpenSSL в .NET Core.

Описание изменения

В .NET Core 2.2 и предыдущих версиях для среды выполнения предпочтительной является загрузка OpenSSL 1.0.x вместо 1.1.x. Это означает, что типы IntPtr и SafeHandle для взаимодействия с OpenSSL используются с libcrypto.so.1.0.0, libcrypto.so.1.0 или libcrypto.so.10 согласно предпочтениям.

Начиная с .NET Core 3.0, для среды выполнения предпочтительной является загрузка OpenSSL 1.1.x вместо OpenSSL 1.0.x, поэтому типы IntPtr и SafeHandle для взаимодействия с OpenSSL используются с libcrypto.so.1.1, libcrypto.so.11, libcrypto.so.1.1.0 или libcrypto.so.1.1.1 согласно предпочтениям. В результате библиотеки и приложения, которые напрямую взаимодействуют с OpenSSL, могут иметь несовместимые указатели со значениями, предоставляемыми .NET Core, при обновлении с .NET Core 2.1 или .NET Core 2.2.

Введённая версия

3.0

Библиотеки и приложения, которые выполняют прямые операции с OpenSSL, должны использовать ту же версию OpenSSL, которую использует среда выполнения .NET Core.

Все библиотеки или приложения, использующие значения IntPtr или SafeHandle криптографических типов .NET Core непосредственно с OpenSSL, должны сравнивать версию библиотеки, которую они используют, с новым свойством SafeEvpPKeyHandle.OpenSslVersion, чтобы обеспечить совместимость указателей.

Категория

Шифрование

Затронутые API

CryptoStream.Dispose преобразует окончательный блок только при записи

Метод CryptoStream.Dispose, который используется для завершения операций CryptoStream, больше не пытается преобразовать последний блок при чтении.

Описание изменения

В предыдущих версиях .NET, если пользователь выполнил неполное чтение при использовании CryptoStream в режиме Read, метод Dispose может вызвать исключение (например, при использовании AES с заполнением). Исключение было выброшено, так как была предпринята попытка преобразовать последний блок, но данные были неполными.

В .NET Core 3.0 и более поздних версиях Dispose больше не пытается преобразовать окончательный блок при чтении, что позволяет выполнять неполные операции чтения.

Причина изменения

Это изменение позволяет выполнять неполные операции чтения из потока шифрования при отмене сетевой операции, без необходимости обрабатывать исключение.

Введённая версия

3.0

Это изменение не затрагивает большинство приложений.

Если ваше приложение ранее перехватило исключение в случае неполного чтения, можно удалить этот блок catch. Если приложение использовало преобразование окончательного блока в сценариях хэширования, перед уничтожением может потребоваться считать весь поток.

Категория

Шифрование

Затронутые API

Entity Framework Core (платформа для работы с базами данных)

Разрушающие изменения в Entity Framework Core

Глобализация

Языковой стандарт "C" сопоставляется с инвариантным языковым стандартом

.NET Core 2.2 и более ранние версии зависят от стандартного поведения ICU, которое связывает локаль "C" с локалью en_US_POSIX. Языковой стандарт en_US_POSIX имеет нежелательное поведение сортировки, так как не поддерживает сравнение строк без учета регистра. Так как некоторые дистрибутивы Linux устанавливают локаль "C" в качестве используемой по умолчанию, пользователи сталкивались с непредвиденным поведением.

Описание изменения

Начиная с .NET Core 3.0, сопоставление языкового стандарта "C" изменилось на использование инвариантного языкового стандарта вместо en_US_POSIX. Для обеспечения согласованности в Windows также применяется сопоставление стандартного локали "C" с инвариантным.

Сопоставление "C" с языком и региональными параметрами en_US_POSIX вызывало путаницу у клиентов, так как en_US_POSIX не поддерживает операции сортировки и поиска строк без учета регистра. Так как в некоторых дистрибутивах Linux языковой стандарт "C" используется по умолчанию, клиенты столкнулись с нежелательным поведением в этих операционных системах.

Введённая версия

3.0

Нет ничего конкретного, только осознание этого изменения. Это изменение затрагивает только приложения, использующие локаль "C".

Категория

Глобализация

Затронутые API

Это изменение затрагивает все API для сортировки и региональных параметров.

MSBuild

Изменение имени файла манифеста для ресурса

Начиная с .NET Core 3.0, в стандартных ситуациях MSBuild создает другие имена файлов манифеста для файлов ресурсов.

Введённая версия

3.0

Описание изменения

До версии .NET Core 3.0, если для элемента LogicalName в файле проекта не были указаны метаданные ManifestResourceName, DependentUponили EmbeddedResource, платформа MSBuild создавала имя файла манифеста в формате <RootNamespace>.<ResourceFilePathFromProjectRoot>.resources. Если в файле проекта не определено значение RootNamespace, по умолчанию используется имя проекта. Например, для файла ресурсов с именем Form1.resx в корневом каталоге проекта создавался манифест с именем MyProject.Form1.resources.

Начиная с версии .NET Core 3.0, при размещении файла ресурса в одной папке с одноименным исходным файлом, (Form1.resx и Form1.cs), MSBuild использует сведения о типе из исходного файла для создания имени файла манифеста в формате <Namespace>.<ClassName>.resources. Пространство имен и имя класса извлекаются из первого типа в исходном файле, найденном в той же папке. Например, для файла ресурсов с именем Form1.resx, который расположен в одной папке с исходным файлом Form1.cs, создается манифест с именем MyNamespace.Form1.resources. Важно отметить, что первая часть имени файла отличается от имени в прежних версиях .NET Core (MyNamespace вместо MyProject).

Примечание.

Если для элемента LogicalName в файле проекта указаны метаданные ManifestResourceName, DependentUpon или EmbeddedResource, это изменение не применяется к соответствующему файлу ресурсов.

Это критическое изменение было введено одновременно с добавлением свойства EmbeddedResourceUseDependentUponConvention для проектов .NET Core. По умолчанию файлы ресурсов не указаны явным образом в файле проекта .NET Core, поэтому в них нет метаданных DependentUpon, которые позволяют задать формат именования созданного файла .resources. Если EmbeddedResourceUseDependentUponConvention имеет значение true (используется по умолчанию), MSBuild ищет в той же папке исходный файл и извлекает из этого файла пространство имен и имя класса. Если для EmbeddedResourceUseDependentUponConvention задано значение false, MSBuild создает имя манифеста по правилам для прежних версий, то есть объединяет RootNamespace и относительный путь к файлу.

В большинстве случаев разработчикам не нужно предпринимать по этому поводу никаких действий, и приложение должно работать нормально. Если же это изменение нарушит работу приложения, вы можете выполнить одно из следующих действий.

  • Измените код так, чтобы он ожидал новое имя манифеста.

  • Откажитесь от новой конвенции об именовании, установив EmbeddedResourceUseDependentUponConvention на false в вашем файле проекта.

    <PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>false</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

Категория

MSBuild

Затронутые API

Н/П

Сеть

Значение по умолчанию для параметра HttpRequestMessage.Version изменено на 1.1

Значение свойства System.Net.Http.HttpRequestMessage.Version по умолчанию изменено с 2.0 на 1.1.

Введённая версия

3.0

Описание изменения

В .NET Core с 1.0 по 2.0 значением свойства System.Net.Http.HttpRequestMessage.Version по умолчанию является 1.1. Начиная с .NET Core 2.1 оно было изменено на 2.1.

Начиная с .NET Core 3.0 номер версии по умолчанию, возвращаемый свойством System.Net.Http.HttpRequestMessage.Version, снова стал 1.1.

Обновите код, если он зависит от свойства System.Net.Http.HttpRequestMessage.Version, возвращающего значение по умолчанию 2.0.

Категория

Сеть

Затронутые API

Windows Forms

Шрифт элемента управления по умолчанию изменен на Segoe UI 9 pt

Описание изменения

В .NET Framework свойству Control.DefaultFont было присвоено значение Microsoft Sans Serif 8.25 pt. На следующем рисунке показано окно, использующее шрифт по умолчанию.

Шрифт элемента управления по умолчанию в .NET Framework

Начиная с .NET Core 3.0, шрифт по умолчанию имеет значение Segoe UI 9 pt (тот же шрифт, что SystemFonts.MessageBoxFontи ). В результате этого изменения формы и элементы управления увеличены примерно на 27%, чтобы соответствовать большему размеру нового шрифта по умолчанию. Например:

шрифт управления по умолчанию в .NET Core

Это изменение было внесено для приведения в соответствие с руководящими принципами пользовательского опыта (UX) Windows.

Введённая версия

3.0

Из-за изменения размера форм и элементов управления проследите, чтобы ваше приложение корректно отображалось.

Чтобы сохранить исходный шрифт для одной формы, установите его шрифт по умолчанию на Microsoft Sans Serif 8.25 pt. Например:

public MyForm()
{
    InitializeComponent();
    Font = new Font(new FontFamily("Microsoft Sans Serif"), 8.25f);
}

Кроме того, можно изменить шрифт по умолчанию для всего приложения следующим образом:

  • Присвоив свойству ApplicationDefaultFont MSBuild значение "Microsoft Sans Serif, 8.25pt". Это предпочтительный способ, так как он позволяет Visual Studio использовать новые параметры в конструкторе.

    <PropertyGroup>
  <ApplicationDefaultFont>Microsoft Sans Serif, 8.25pt</ApplicationDefaultFont>
</PropertyGroup>

  • При вызове Application.SetDefaultFont(Font).

    class Program
{
    [STAThread]
    static void Main()
    {
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);
        Application.SetHighDpiMode(HighDpiMode.SystemAware);
        Application.SetDefaultFont(new Font(new FontFamily("Microsoft Sans Serif"), 8.25f));
        Application.Run(new Form1());
    }
}

Категория

  • Windows Forms

Затронутые API

Нет.

Модернизация диалога выбора папки

Элемент FolderBrowserDialog управления изменился в приложениях Windows Forms для .NET Core.

Описание изменения

В .NET Framework Windows Forms использует следующий диалог для элемента управления FolderBrowserDialog.

FolderBrowserDialogControl в .NET Framework

В .NET Core 3.0 Windows Forms использует новый элемент управления на основе COM, который появился в Windows Vista:

FolderBrowserDialogControl в .NET Core

Введённая версия

3.0

Диалоговое окно будет автоматически обновлено.

Если вы хотите сохранить исходное диалоговое окно, задайте FolderBrowserDialog.AutoUpgradeEnabled для свойства значение false перед отображением диалогового окна, как показано в следующем фрагменте кода:

var dialog = new FolderBrowserDialog();
dialog.AutoUpgradeEnabled = false;
dialog.ShowDialog();

Категория

Windows Forms

Затронутые API

SerializableAttribute удален из некоторых типов Windows Forms

SerializableAttribute был удален из некоторых классов Windows Forms, для которых не существует известных сценариев двоичной сериализации.

Описание изменения

Следующие типы аннотированы с помощью SerializableAttribute в .NET Framework, но атрибут был удален в .NET Core.

Исторически этот механизм сериализации имел серьезные проблемы с обслуживанием и безопасностью. Поддержание SerializableAttribute в типах означает, что эти типы должны быть проверены на изменения сериализации от версии к версии и потенциально от фреймворка к фреймворку. Это затрудняет развитие этих типов и может быть дорогостоящим для обслуживания. Эти типы не имеют известных сценариев двоичной сериализации, что сводит к минимуму влияние удаления атрибута.

Более подробную информацию см. в о двоичной сериализации.

Введённая версия

3.0

Обновите любой код, который может зависеть от этих типов, помеченных как сериализуемый.

Категория

Windows Forms

Затронутые API

  • нет

Параметр совместимости AllowUpdateChildControlIndexForTabControls не поддерживается

Параметр Switch.System.Windows.Forms.AllowUpdateChildControlIndexForTabControls совместимости поддерживается в Windows Forms начиная с .NET Framework 4.6, но не поддерживается в .NET Core, .NET 5.0 и более поздних версиях.

Описание изменения

В .NET Framework 4.6 и более поздних версиях выбор вкладки приводит к переупорядочиванию коллекции элементов управления. Переключатель Switch.System.Windows.Forms.AllowUpdateChildControlIndexForTabControls совместимости позволяет приложению пропускать это изменение порядка, если это поведение нежелательно.

В .NET Core и .NET 5.0 и более поздних версиях параметр Switch.System.Windows.Forms.AllowUpdateChildControlIndexForTabControls не поддерживается.

Введённая версия

3.0

Удалите переключатель. Переключатель не поддерживается, а альтернативные функции недоступны.

Категория

Windows Forms

Затронутые API

  • нет

Параметр совместимости DomainUpDown.UseLegacyScrolling не поддерживается

Параметр Switch.System.Windows.Forms.DomainUpDown.UseLegacyScrolling совместимости, введенный в .NET Framework 4.7.1, не поддерживается в Windows Forms на платформах .NET Core и .NET 5.0 и более поздних.

Описание изменения

Начиная с .NET Framework 4.7.1, Switch.System.Windows.Forms.DomainUpDown.UseLegacyScrolling переключатель совместимости позволил разработчикам отказаться от независимых DomainUpDown.DownButton() и DomainUpDown.UpButton() действий. Переключатель восстановил устаревшее поведение, при котором DomainUpDown.UpButton() игнорируется, если присутствует контекстный текст, и разработчику необходимо использовать действие DomainUpDown.DownButton() на элемент управления перед действием DomainUpDown.UpButton(). Дополнительные сведения см. в элементе <AppContextSwitchOverrides>.

В .NET Core и .NET 5.0 и более поздних версиях параметр Switch.System.Windows.Forms.DomainUpDown.UseLegacyScrolling не поддерживается.

Введённая версия

3.0

Удалите переключатель. Переключатель не поддерживается, а альтернативные функции недоступны.

Категория

Windows Forms

Затронутые API

Переключатель совместимости DoNotLoadLatestRichEditControl не поддерживается

Параметр Switch.System.Windows.Forms.UseLegacyImages совместимости, введенный в .NET Framework 4.7.1, не поддерживается в Windows Forms на платформах .NET Core и .NET 5.0 и более поздних.

Описание изменения

В .NET Framework 4.6.2 и предыдущих версиях контрол RichTextBox инстанцирует Win32 RichEdit версии 3.0, а для приложений, ориентированных на .NET Framework 4.7.1, контрол RichTextBox инстанцирует RichEdit версии 4.1 (в msftedit.dll). Параметр Switch.System.Windows.Forms.DoNotLoadLatestRichEditControl совместимости был представлен, чтобы разрешить приложениям, предназначенным для .NET Framework 4.7.1 и более поздних версий, отказаться от нового элемента управления RichEdit версии 4.1 и использовать старый элемент управления RichEdit версии 3.

В .NET Core и .NET 5.0 и в более поздних версиях параметр Switch.System.Windows.Forms.DoNotLoadLatestRichEditControl не поддерживается. Поддерживаются только новые версии RichTextBox элемента управления.

Введённая версия

3.0

Удалите переключатель. Переключатель не поддерживается, а альтернативные функции недоступны.

Категория

Windows Forms

Затронутые API

Переключатель совместимости DoNotSupportSelectAllShortcutInMultilineTextBox не поддерживается

Переключатель совместимости Switch.System.Windows.Forms.DoNotSupportSelectAllShortcutInMultilineTextBox, введённый в .NET Framework 4.6.1, не поддерживается в Windows Forms на платформах .NET Core, .NET 5.0 и более поздних версиях.

Описание изменения

Начиная с .NET Framework 4.6.1, при нажатии сочетания клавиш Ctrl + A в элементе управления TextBox выделяется весь текст. В .NET Framework 4.6 и предыдущих версиях выбор сочетания клавиш Ctrl + A не удавалось выделить весь текст, если оба свойства Textbox.ShortcutsEnabled и TextBox.Multiline установлены в значение true. Переключатель Switch.System.Windows.Forms.DoNotSupportSelectAllShortcutInMultilineTextBox совместимости был введен в .NET Framework 4.6.1, чтобы сохранить исходное поведение. Дополнительные сведения см. в TextBox.ProcessCmdKey.

В .NET Core и .NET 5.0 и в более поздних версиях параметр Switch.System.Windows.Forms.DoNotSupportSelectAllShortcutInMultilineTextBox не поддерживается.

Введённая версия

3.0

Удалите переключатель. Переключатель не поддерживается, а альтернативные функции недоступны.

Категория

Windows Forms

Затронутые API

  • нет

Переключатель совместимости DontSupportReentrantFilterMessage не поддерживается.

Переключатель совместимости Switch.System.Windows.Forms.DontSupportReentrantFilterMessage, введённый в .NET Framework 4.6.1, не поддерживается в Windows Forms на платформах .NET Core, .NET 5.0 и более поздних версиях.

Описание изменения

Начиная с .NET Framework 4.6.1, переключатель совместимости Switch.System.Windows.Forms.DontSupportReentrantFilterMessage решает проблему возможных исключений IndexOutOfRangeException, когда сообщение Application.FilterMessage вызывается с пользовательской реализацией IMessageFilter.PreFilterMessage. Дополнительные сведения см. в разделе Устранение рисков: пользовательские реализации IMessageFilter.PreFilterMessage.

В .NET Core и .NET 5.0 и более поздних версиях параметр Switch.System.Windows.Forms.DontSupportReentrantFilterMessage не поддерживается.

Введённая версия

3.0

Удалите переключатель. Переключатель не поддерживается, а альтернативные функции недоступны.

Категория

Windows Forms

Затронутые API

Параметр совместимости EnableVisualStyleValidation не поддерживается

Параметр совместимости Switch.System.Windows.Forms.EnableVisualStyleValidation не поддерживается в Windows Forms на .NET Core или в .NET 5.0 и более поздних версиях.

Описание изменения

В .NET Framework Switch.System.Windows.Forms.EnableVisualStyleValidation переключатель совместимости позволил приложению отказаться от проверки визуальных стилей, предоставленных в числовой форме.

В .NET Core и .NET 5.0 и более поздних версиях параметр Switch.System.Windows.Forms.EnableVisualStyleValidation не поддерживается.

Введённая версия

3.0

Удалите переключатель. Переключатель не поддерживается, а альтернативные функции недоступны.

Категория

Windows Forms

Затронутые API

  • нет

Параметр совместимости "UseLegacyContextMenuStripSourceControlValue" не поддерживается

Переключатель совместимости Switch.System.Windows.Forms.UseLegacyContextMenuStripSourceControlValue, который был введен в .NET Framework 4.7.2, не поддерживается в Windows Forms на .NET Core или .NET 5.0 и более поздних версиях.

Описание изменения

Начиная с .NET Framework 4.7.2, параметр совместимости Switch.System.Windows.Forms.UseLegacyContextMenuStripSourceControlValue позволяет разработчику отказаться от нового поведения свойства ContextMenuStrip.SourceControl, которое теперь возвращает ссылку на исходный элемент управления. Предыдущее поведение свойства заключалось в возвращении null. Дополнительные сведения см. в элементе <AppContextSwitchOverrides>.

В .NET Core и .NET 5.0 и более поздних версиях параметр Switch.System.Windows.Forms.UseLegacyContextMenuStripSourceControlValue не поддерживается.

Введённая версия

3.0

Удалите переключатель. Переключатель не поддерживается, а альтернативные функции недоступны.

Категория

Windows Forms

Затронутые API

Параметр совместимости UseLegacyImages не поддерживается

Параметр Switch.System.Windows.Forms.UseLegacyImages совместимости, представленный в .NET Framework 4.8, не поддерживается в Windows Forms, работающих на .NET Core или .NET 5.0 и более поздних версиях.

Описание изменения

Начиная с .NET Framework 4.8, Switch.System.Windows.Forms.UseLegacyImages коммутатор совместимости устранял возможные проблемы с масштабированием изображений в сценариях ClickOnce в средах с высоким уровнем DPI. Если задано значение true, переключатель позволяет пользователю восстанавливать устаревшие изображения масштабирования на высоком уровне DPI, масштаб которого имеет значение более 100%. Дополнительные сведения см. в заметках о выпуске .NET Framework 4.8 на GitHub.

В .NET Core и .NET 5.0 и более поздних версиях параметр Switch.System.Windows.Forms.UseLegacyImages не поддерживается.

Введённая версия

3.0

Удалите переключатель. Переключатель не поддерживается, а альтернативные функции недоступны.

Категория

Windows Forms

Затронутые API

  • нет

Шаблоны About и SplashScreen разбиты

Файлы About.vb и SplashScreen.vb, созданные Visual Studio, содержат ссылки на типы в пространстве имен My, которые недоступны в .NET Core 3.0 и 3.1.

Введённая версия

3.0

Описание изменения

.NET Core 3.0 и 3.1 не содержат полную поддержку Visual Basic My . Шаблоны форм About и SplashScreen в приложениях Visual Studio для Windows Forms на Visual Basic ссылаются на свойства типа My.Application.Info, которые недоступны.

Поддержка Visual Basic My была улучшена в .NET 5, обновите проект до .NET 5 или более поздней версии.

-или-

Исправьте ошибки компилятора в типах About и SplashScreen в вашем приложении. Используйте класс System.Reflection.Assembly, чтобы получить сведения, предоставленные типом My.Application.Info. Здесь доступен прямой порт обеих форм.

Совет

Это пример кода и неоптимизирован. Список атрибутов должен кэшироваться для уменьшения времени загрузки формы.

О нас

Imports System.Reflection

Public NotInheritable Class About

    Private Sub about_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
        ' Set the title of the form.
        Dim applicationTitle As String = Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyTitleAttribute)()?.Title

        If String.IsNullOrEmpty(applicationTitle) Then
            applicationTitle = System.IO.Path.GetFileNameWithoutExtension(Assembly.GetExecutingAssembly().GetName().Name)
        End If

        Me.Text = String.Format("About {0}", applicationTitle)
        ' Initialize all of the text displayed on the About Box.
        ' TODO: Customize the application's assembly information in the "Application" pane of the project
        '    properties dialog (under the "Project" menu).
        Me.LabelProductName.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyProductAttribute)()?.Product, "")
        Me.LabelVersion.Text = String.Format("Version {0}", Assembly.GetExecutingAssembly().GetName().Version)
        Me.LabelCopyright.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyCopyrightAttribute)()?.Copyright, "")
        Me.LabelCompanyName.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyCompanyAttribute)()?.Company, "")
        Me.TextBoxDescription.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyDescriptionAttribute)()?.Description, "")
    End Sub

    Private Sub OKButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles OKButton.Click
        Me.Close()
    End Sub

End Class

Экран заставки

Imports System.Reflection

Public NotInheritable Class SplashScreen

    Private Sub SplashScreen1_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
        'Set up the dialog text at runtime according to the application's assembly information.  

        'TODO: Customize the application's assembly information in the "Application" pane of the project
        '  properties dialog (under the "Project" menu).

        'Application title
        Dim appTitle As String = Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyTitleAttribute)()?.Title

        If String.IsNullOrEmpty(appTitle) Then
            appTitle = System.IO.Path.GetFileNameWithoutExtension(Assembly.GetExecutingAssembly().GetName().Name)
        End If

        ApplicationTitle.Text = appTitle

        Dim versionValue = Assembly.GetExecutingAssembly().GetName().Version

        'Format the version information using the text set into the Version control at design time as the
        '  formatting string.  This allows for effective localization if desired.
        '  Build and revision information could be included by using the following code and changing the
        '  Version control's designtime text to "Version {0}.{1:00}.{2}.{3}" or something similar.  See
        '  String.Format() in Help for more information.
        '
        '    Version.Text = System.String.Format(Version.Text, versionValue.Major, versionValue.Minor, versionValue.Build, versionValue.Revision)

        Version.Text = System.String.Format(Version.Text, versionValue.Major, versionValue.Minor)

        'Copyright info
        Copyright.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyCopyrightAttribute)()?.Copyright, "")
    End Sub

End Class

Категория

Visual Basic Windows Forms

Затронутые API

нет

WPF (Windows Presentation Foundation)

Измененное поведение перетаскивания в текстовых редакторах

.NET Core 3.0 внесло изменение в то, как элементы управления текстовым редактором создают System.Windows.DataObject при перетаскивании текста в другой элемент управления. Изменение отключило автоконверсию, в результате чего операция сохраняет данные как DataFormats.Text или DataFormats.UnicodeText вместо преобразования их в DataFormats.StringFormat.

Введённая версия

.NET Core 3.0

Категория

Windows Presentation Foundation

Прежнее поведение

Тип данных на System.Windows.DataObject при перетаскивании текста из элемента управления текстовым редактором был DataFormats.StringFormat.

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

Тип данных на System.Windows.DataObject при перетаскивании текста из элемента управления текстового редактора - это DataFormats.Text или DataFormats.UnicodeText.

Тип ломающего изменения

Это изменение поведения.

Причина изменения

Это изменение было непреднамеренным.

Это изменение было отменено в .NET 7. Обновление до .NET 7 или более поздней версии.

Затронутые API

См. также

  • Last updated on