Критические изменения в .NET Core 3.0

  • Статья

Если вы выполняете миграцию на версию 3.0 .NET Core, 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.ImageTagHelper(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 и более поздних здесь описаны меры для временного устранения рисков. Приложения должны по этой процедуре проверить наличие изменений в формате данных. Планируется выпуск версии 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.Parse на JsonDocument.Parse в переопределении CreateTicketAsync, как показано здесь. 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 в IAuthorizationPolicyProvider был добавлен новый метод GetFallbackPolicyAsync. Эта политика отката используется ПО промежуточного слоя для авторизации, если не указана другая политика.

Подробную информацию см. на странице 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

нет

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

В 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 версии 1 удален из пакета размещения Windows

Начиная с 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 версии 1, выполните установку с помощью пакета размещения 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 только типы 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 использует контейнер внедрения зависимостей для сборки приложения. WebHost использует два контейнера: один для узла и один для приложения. В результате конструктор Startup теперь не поддерживает внедрение пользовательской службы. Можно внедрять только IHostEnvironment, IWebHostEnvironment или IConfiguration. Это изменение предотвращает такие проблемы, как дублирование создания одноэлементной службы.

Представленные версии

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, синхронные операции сервера по умолчанию отключены.

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

  • Kestrel
  • HttpSys
  • IIS (внутрипроцессный)
  • TestServer

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

  • 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)

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

Начиная с 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 в конструктор SignInManager был добавлен новый параметр IUserConfirmation<TUser>. Подробную информацию см. на странице dotnet/aspnetcore#8356.

Представленные версии

3.0

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

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

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

Категория

ASP.NET Core

Затронутые API

SignInManager<TUser>

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

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

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

Внедрение функции статических веб-ресурсов в пользовательский интерфейс удостоверений принесло следующие результаты.

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

Представленные версии

3.0

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

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

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

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

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

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

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

<IdentityUIFrameworkVersion>Bootstrap3</IdentityUIFrameworkVersion>

Категория

ASP.NET Core

Затронутые API

IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder, UIFramework)

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

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

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

Представленные версии

3.0

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

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

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

Компоненты расширяемости Kestrel созданы с помощью ПО промежуточного слоя.

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

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

Преобразуйте все реализации IConnectionAdapter, чтобы использовать новый шаблон ПО промежуточного слоя.

Категория

ASP.NET Core

Затронутые API

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

Kestrel: удалена пустая сборка HTTPS

Сборка 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 предварительной версии 3. Эти API будут удалены в будущем выпуске.

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

Представленные версии

3.0

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

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

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

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

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

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

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

Категория

ASP.NET Core

Затронутые API

Ведение журнала: класс 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. В приложениях, использующих сторонние библиотеки, могут возникать проблемы.

Представленные версии

6 предварительная версия 3.0

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

Сборка приложения, использующего библиотеку на основе версии 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.

Прекратите использование оболочки и переходите сразу к использованию аналогичных функций в 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:
  • Расширения 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: рукопожатиеProtocol.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 Подключение ion ResetSendPing и ResetTimeout

Методы 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: изменены конструкторы Hub Подключение ionContext

Конструкторы 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 и Use Подключение ions помечены как устаревшие

Методы 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, сохраняют полноценную поддержку в выпуске .NET Core 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 (справа), отображаемых в диалоговом окне свойств файла в проводнике.

Difference in product version information

Представленные версии

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 (Замена наибольшей части неправильной последовательности символом U+FFFD).

Такой подход применяется только в том случае, если входная последовательность байтов содержит некорректные данные в кодировке 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() проверяет, чтобы данные в локальном и центральном заголовках о размерах сжатой и несжатой записи были согласованными. Если в локальном заголовке архива и/или в дескрипторе данных указаны размеры, которые отличаются от размеров в центральном каталоге ZIP-файла, метод вызывает исключение InvalidDataException. При считывании записи распакованные данные усекаются до размера несжатого файла, который указан в заголовке.

Это изменение позволит 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 (устанавливается с помощью пакета NuGet System.Security.Cryptography.Pkcs версии 4.6.0) алгоритм по умолчанию был заменен на 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" изменилось на использование инвариантного (Invariant) языкового стандарта вместо 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, если для элемента EmbeddedResource в файле проекта не были указаны метаданные LogicalName, ManifestResourceNameили DependentUpon, платформа 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).

Примечание.

Если для элемента EmbeddedResource в файле проекта указаны метаданные LogicalName, ManifestResourceName или DependentUpon, это изменение не применяется к соответствующему файлу ресурсов.

Это критическое изменение было введено одновременно с добавлением свойства 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

См. также