Alterações interruptivas no .NET Core 3.0

  • Artigo

Se você estiver migrando para a versão 3.0 do .NET Core, do ASP.NET Core ou do EF Core, as alterações interruptivas listadas neste artigo poderão afetar seu aplicativo.

ASP.NET Core

APIs obsoletas antifalsificação, CORS, de diagnóstico, MVC e de roteamento removidas

Os membros obsoletos e os comutadores de compatibilidade no ASP.NET Core 2.2 foram removidos.

Versão introduzida

3.0

Motivo da alteração

Aprimoramento da superfície da API ao longo do tempo.

Ao direcionar projetos ao .NET Core 2.2, siga as diretrizes nas mensagens de build sobre obsolescência para adotar novas APIs.

Categoria

ASP.NET Core

APIs afetadas

Os seguintes tipos e membros foram marcados como obsoletos no ASP.NET Core 2.1 e 2.2:

Types

  • 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

Construtores

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

Propriedades

  • 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

Métodos

APIs do "Pubternal" removidas

Para manter melhor a superfície de API pública do ASP.NET Core, a maioria dos tipos nos namespaces *.Internal (conhecidos como APIs "pubternal") tornaram-se verdadeiramente internos. Os membros desses namespaces não foram projetados para ter suporte como APIs voltadas ao público. As APIs podem ser interrompidas em versões secundárias (e muitas vezes foram). Códigos que dependem dessas APIs são interrompidos ao atualizar para o ASP.NET Core 3.0.

Para obter mais informações, confira dotnet/aspnetcore#4932 e dotnet/aspnetcore#11312.

Versão introduzida

3.0

Comportamento antigo

As APIs afetadas são marcadas com o public modificador de acesso e existem nos namespaces *.Internal.

Novo comportamento

As APIs afetadas são marcadas com o modificador de acesso internal e não podem mais ser usadas pelo código fora desse assembly.

Motivo da alteração

A orientação para essas APIs "pubternal" era que elas:

  • Podem ser alteradas sem aviso prévio.
  • Não estavam sujeitas às políticas do .NET para evitar alterações interruptivas.

Deixar as APIs public (mesmo nos namespaces *.Internal) era confuso para os clientes.

Pare de usar essas APIs "pubternal". Se você tiver dúvidas sobre APIs alternativas, abra um problema no repositório dotnet/aspnetcore.

Por exemplo, considere o código de buffer de solicitação HTTP a seguir em um projeto do ASP.NET Core 2.2. O método de extensão EnableRewind existe no namespace Microsoft.AspNetCore.Http.Internal.

HttpContext.Request.EnableRewind();

Em um projeto ASP.NET Core 3.0, substitua a chamada EnableRewind por uma chamada ao método de extensão EnableBuffering. O recurso de buffer de solicitação funciona como no passado. EnableBuffering chama agora a API internal.

HttpContext.Request.EnableBuffering();

Categoria

ASP.NET Core

APIs afetadas

Todas as APIs nos namespaces Microsoft.AspNetCore.* e Microsoft.Extensions.* que têm um segmento Internal no nome. Por exemplo:

  • 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

Autenticação: Google+ preterido e substituído

O Google começou a encerrar a entrada do Google+ para aplicativos em 28 de janeiro de 2019.

Descrição das alterações

O ASP.NET 4.x e o ASP.NET Core têm usado as APIs de entrada do Google+ para autenticar usuários de conta do Google em aplicativos Web. Os pacotes NuGet afetados são Microsoft.AspNetCore.Authentication.Google para ASP.NET Core e Microsoft.Owin.Security.Google para Microsoft.Owin com ASP.NET Web Forms e MVC.

As APIs de substituição do Google usam uma fonte de dados e um formato diferentes. As mitigações e soluções fornecidas abaixo explicam as alterações estruturais. Os aplicativos devem verificar se os dados em si ainda atendem aos requisitos. Por exemplo, nomes, endereços de email, links de perfil e fotos de perfil podem ter valores um pouco diferentes dos anteriores.

Versão introduzida

Todas as versões. Essa alteração é externa ao ASP.NET Core.

Owin com ASP.NET Web Forms e MVC

Para Microsoft.Owin 3.1.0 e posteriores, uma mitigação temporária está descrita aqui. Os aplicativos devem concluir o teste com a mitigação para verificar se há alterações no formato de dados. Há planos para lançar o Microsoft.Owin 4.0.1 com uma correção. Os aplicativos que usam qualquer versão anterior devem ser atualizados para a versão 4.0.1.

ASP.NET Core 1.x

A mitigação em Owin com ASP.NET Web Forms e MVC pode ser adaptada para o ASP.NET Core 1.x. Não há planos de patch para o pacote NuGet porque o 1.x atingiu o status de fim de vida útil.

ASP.NET Core 2.x

Para o Microsoft.AspNetCore.Authentication.Google a versão 2.x, substitua a chamada existente para AddGoogle em Startup.ConfigureServices pelo seguinte código:

.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");
});

Os patches de fevereiro das versões 2.1 e 2.2 incorporaram a reconfiguração anterior como o novo padrão. Nenhum patch está planejado para o ASP.NET Core 2.0, pois ele chegou ao fim da vida útil.

ASP.NET Core 3.0

A mitigação fornecida para o ASP.NET Core 2.x também pode ser usada para o ASP.NET Core 3.0. Em versões prévias futuras do 3.0, o pacote Microsoft.AspNetCore.Authentication.Google poderá ser removido. Nesse caso, os usuários serão direcionados ao Microsoft.AspNetCore.Authentication.OpenIdConnect. O código a seguir mostra como substituir AddGoogle por AddOpenIdConnect em Startup.ConfigureServices. Essa substituição pode ser usada com o ASP.NET Core 2.0 e posteriores e pode ser adaptada para o ASP.NET Core 1.x, conforme o necessário.

.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();

Categoria

ASP.NET Core

APIs afetadas

Microsoft.AspNetCore.Authentication.Google

Autenticação: propriedade HttpContext.Authentication removida

A propriedade preterida Authentication em HttpContext foi removida.

Descrição das alterações

Como parte do dotnet/aspnetcore#6504, a propriedade Authentication preterida em HttpContext foi removida. A propriedade Authentication foi preterida desde a versão 2.0. Um guia de migração foi publicado para migrar o código usando essa propriedade preterida para as novas APIs de substituição. As classes/APIs não utilizados restantes relacionadas à pilha de autenticação antiga do ASP.NET Core 1.x foram removidas no commit dotnet/aspnetcore@d7a7c65.

Para ver a discussão, confira dotnet/aspnetcore#6533.

Versão introduzida

3.0

Motivo da alteração

As APIs do ASP.NET Core 1.0 foram substituídas por métodos de extensão no Microsoft.AspNetCore.Authentication.AuthenticationHttpContextExtensions.

Confira o Guia de migração.

Categoria

ASP.NET Core

APIs afetadas

Autenticação: tipos Newtonsoft.Json substituídos

No ASP.NET Core 3.0, os tipos Newtonsoft.Json usados em APIs de Autenticação foram substituídos por tipos System.Text.Json. Exceto nos seguintes casos, o uso básico dos pacotes de autenticação permanece inalterado:

  • Classes derivadas dos provedores OAuth, como as de aspnet-contrib.
  • Implementações avançadas de manipulação de declarações.

Para obter mais informações, confira dotnet/aspnetcore#7105. Para ver a discussão, confira dotnet/aspnetcore#7289.

Versão introduzida

3.0

Para implementações do OAuth derivadas, a alteração mais comum é substituir JObject.Parse por JsonDocument.Parse no CreateTicketAsync, como é mostrado aqui. JsonDocument implementa IDisposable.

A seguinte lista descreve as alterações conhecidas:

Categoria

ASP.NET Core

APIs afetadas

Autenticação: assinatura do ExchangeCodeAsync do OAuthHandler alterada

No ASP.NET Core 3.0, a assinatura de OAuthHandler.ExchangeCodeAsync foi alterada de:

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

Para:

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

Versão introduzida

3.0

Comportamento antigo

As cadeias de caracteres code e redirectUri foram passadas como argumentos separados.

Novo comportamento

Code e RedirectUri são propriedades em OAuthCodeExchangeContext que podem ser definidas por meio do construtor OAuthCodeExchangeContext. O novo tipo OAuthCodeExchangeContext é o único argumento passado para OAuthHandler.ExchangeCodeAsync.

Motivo da alteração

Essa alteração permite que parâmetros adicionais sejam fornecidos de maneira não interruptiva. Não é necessário criar sobrecargas de ExchangeCodeAsync.

Construa um OAuthCodeExchangeContext com os valores apropriados de code e redirectUri. Uma instância de AuthenticationProperties precisa ser fornecida. Essa única instância de OAuthCodeExchangeContext pode ser passada para OAuthHandler.ExchangeCodeAsync em vez de vários argumentos.

Categoria

ASP.NET Core

APIs afetadas

OAuthHandler<TOptions>.ExchangeCodeAsync(String, String)

Autorização: sobrecarga de AddAuthorization movida para um assembly diferente

Os métodos AddAuthorization principais que costumavam residir em Microsoft.AspNetCore.Authorization foram renomeado para AddAuthorizationCore. Os métodos AddAuthorization antigos ainda existem, mas estão no assembly Microsoft.AspNetCore.Authorization.Policy. Nos aplicativos que usam os dois métodos, não deve haver nenhum impacto. Observe que Microsoft.AspNetCore.Authorization.Policy agora é fornecido na estrutura compartilhada em vez de em um pacote autônomo, conforme discutido em Estrutura compartilhada: assemblies removidos de Microsoft.AspNetCore.App.

Versão introduzida

3.0

Comportamento antigo

Os métodos AddAuthorization existiam em Microsoft.AspNetCore.Authorization.

Novo comportamento

Os métodos AddAuthorization existem em Microsoft.AspNetCore.Authorization.Policy. AddAuthorizationCore é o novo nome dos métodos antigos.

Motivo da alteração

AddAuthorization é um nome de método melhor para adicionar todos os serviços comuns necessários para autorização.

Nesse caso, adicione uma referência a Microsoft.AspNetCore.Authorization.Policy ou use AddAuthorizationCore.

Categoria

ASP.NET Core

APIs afetadas

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

Autorização: IAllowAnonymous removido de AuthorizationFilterContext.Filters

Do ASP.NET Core 3.0 em diante, o MVC não adiciona AllowAnonymousFilters a atributos [AllowAnonymous] descobertos em controladores e métodos de ação. Essa alteração é tratada localmente para derivativos de AuthorizeAttribute, mas é uma alteração interruptiva e para implementações de IAsyncAuthorizationFilter e IAuthorizationFilter. Essas implementações encapsuladas em um atributo [TypeFilter] são uma forma popular e com suporte de obter autorização baseada em atributo fortemente tipada quando a configuração e a injeção de dependência são necessárias.

Versão introduzida

3.0

Comportamento antigo

IAllowAnonymous aparecia na coleção AuthorizationFilterContext.Filters. O teste de presença da interface foi era abordagem válida para substituir ou desabilitar o filtro em métodos de controlador individuais.

Novo comportamento

IAllowAnonymous não aparece mais na coleção AuthorizationFilterContext.Filters. As implementações de IAsyncAuthorizationFilter que dependem do comportamento antigo normalmente causam as respostas intermitentes HTTP 401 Não Autorizado ou HTTP 403 Proibido.

Motivo da alteração

Uma nova estratégia de roteamento de ponto de extremidade foi introduzida no ASP.NET Core 3.0.

Pesquise os metadados de ponto de extremidade para IAllowAnonymous. Por exemplo:

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

Um exemplo dessa técnica é visto neste método HasAllowAnonymous.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Autorização: implementações IAuthorizationPolicyProvider exigem novo método

No ASP.NET Core 3.0, um novo método GetFallbackPolicyAsync foi adicionado a IAuthorizationPolicyProvider. Essa política de fallback é usada pelo middleware de autorização quando nenhuma política é especificada.

Para obter mais informações, confira dotnet/aspnetcore#9759.

Versão introduzida

3.0

Comportamento antigo

As implementações de IAuthorizationPolicyProvider não exigiam um método GetFallbackPolicyAsync.

Novo comportamento

As implementações de IAuthorizationPolicyProvider exigem um método GetFallbackPolicyAsync.

Motivo da alteração

Um novo método era necessário para que o novo AuthorizationMiddleware fosse usado quando nenhuma política era especificada.

Adicione o método GetFallbackPolicyAsync às implementações de IAuthorizationPolicyProvider.

Categoria

ASP.NET Core

APIs afetadas

Microsoft.AspNetCore.Authorization.IAuthorizationPolicyProvider

Cache: propriedade CompactOnMemoryPressure removida

A versão ASP.NET Core 3.0 removeu as APIs obsoletas de MemoryCacheOptions.

Descrição das alterações

Essa alteração é um acompanhamento do aspnet/Caching#221. Para ver a discussão, confira dotnet/aspnetcore#1062.

Versão introduzida

3.0

Comportamento antigo

A propriedade MemoryCacheOptions.CompactOnMemoryPressure estava disponível.

Novo comportamento

A propriedade MemoryCacheOptions.CompactOnMemoryPressure foi removida.

Motivo da alteração

A compactação automática do cache causava problemas. Para evitar um comportamento inesperado, o cache só deve ser compactado quando necessário.

Para compactar o cache, faça downcast para MemoryCache e chame Compact quando necessário.

Categoria

ASP.NET Core

APIs afetadas

MemoryCacheOptions.CompactOnMemoryPressure

Cache: Microsoft.Extensions.Caching.SqlServer usa um novo pacote SqlClient

O pacote Microsoft.Extensions.Caching.SqlServer usará o novo pacote Microsoft.Data.SqlClient em vez do pacote System.Data.SqlClient. Essa alteração pode causar pequenas alterações interruptivas no comportamento. Para obter mais informações, confira Introdução ao novo Microsoft.Data.SqlClient.

Versão introduzida

3.0

Comportamento antigo

O pacote Microsoft.Extensions.Caching.SqlServer usava o pacote System.Data.SqlClient.

Novo comportamento

Agora, Microsoft.Extensions.Caching.SqlServer está usando o pacote Microsoft.Data.SqlClient.

Motivo da alteração

Microsoft.Data.SqlClient é um novo pacote que é criado com base em System.Data.SqlClient. É nele que todo o novo trabalho de recursos será feito a partir de agora.

Os clientes não devem precisar se preocupar com essa alteração interruptiva, a menos que estejam usando tipos retornados pelo pacote Microsoft.Extensions.Caching.SqlServer e convertendo-os em tipos System.Data.SqlClient. Por exemplo, se alguém estiver convertendo um DbConnection no tipo SqlConnection antigo, será necessário alterar a conversão para o novo tipo Microsoft.Data.SqlClient.SqlConnection.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Cache: tipos "pubterais" ResponseCaching alterados para internos

No ASP.NET Core 3.0, os tipos "pubternal" em ResponseCaching foram alterados para internal.

Além disso, as implementações padrão de IResponseCachingPolicyProvider e IResponseCachingKeyProvider não são mais adicionadas aos serviços como parte do método AddResponseCaching.

Descrição das alterações

No ASP.NET Core, os tipos "pubternal" são declarados como public, mas residem em um namespace com o sufixo .Internal. Embora esses tipos sejam públicos, eles não têm nenhuma política de suporte e estão sujeitos a alterações interruptivas. O uso acidental desses tipos tem sido comum, resultando em alterações interruptivas nesses projetos e limitando a capacidade de manutenção da estrutura.

Versão introduzida

3.0

Comportamento antigo

Esses tipos eram visíveis publicamente, mas não tinham suporte.

Novo comportamento

Esses tipos são internal agora.

Motivo da alteração

O escopo de internal reflete melhor a política sem suporte.

Copie os tipos que são usados pelo aplicativo ou a biblioteca.

Categoria

ASP.NET Core

APIs afetadas

Proteção de dados: DataProtection.Blobs usa novas APIs do Armazenamento do Azure

Azure.Extensions.AspNetCore.DataProtection.Blobs depende das bibliotecas do Armazenamento do Azure. Nessas bibliotecas, foram renomeados os assemblies, os pacotes e os namespaces. Do ASP.NET Core 3.0 em diante, Azure.Extensions.AspNetCore.DataProtection.Blobs usa as novas APIs e pacotes prefixados com Azure.Storage..

Para perguntas sobre as APIs do Armazenamento do Azure, use https://github.com/Azure/azure-storage-net. Para conferir a discussão sobre esse problema, veja dotnet/aspnetcore#19570.

Versão introduzida

3.0

Comportamento antigo

O pacote referenciava o pacote NuGet WindowsAzure.Storage. O pacote referencia o pacote NuGet Microsoft.Azure.Storage.Blob.

Novo comportamento

O pacote referencia o pacote NuGet Azure.Storage.Blob.

Motivo da alteração

Essa alteração permite que Azure.Extensions.AspNetCore.DataProtection.Blobs seja migrado para os pacotes recomendados do Armazenamento do Azure.

Se você ainda precisar usar as APIs do Armazenamento do Azure mais antigas com o ASP.NET Core 3.0, adicione uma dependência direta ao pacote WindowsAzure.Storage ou Microsoft.Azure.Storage. Esse pacote pode ser instalado junto com as novas APIs do Azure.Storage.

Em muitos casos, a atualização envolve apenas a alteração das instruções using para usar os novos namespaces:

- 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;

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Hospedagem: AspNetCoreModule V1 removido do Pacote de Hospedagem do Windows

Do ASP.NET Core 3.0 em diante, o Pacote de Hospedagem do Windows não conterá o AspNetCoreModule (ANCM) V1.

O ANCM V2 é compatível com a versões anteriores ANCM OutOfProcess e é recomendado para uso com aplicativos ASP.NET Core 3.0.

Para ver a discussão, confira dotnet/aspnetcore#7095.

Versão introduzida

3.0

Comportamento antigo

O ANCM V1 está incluído no Pacote de Hospedagem do Windows.

Novo comportamento

O ANCM V1 não está incluído no Pacote de Hospedagem do Windows.

Motivo da alteração

O ANCM V2 é compatível com a versões anteriores ANCM OutOfProcess e é recomendado para uso com aplicativos ASP.NET Core 3.0.

Use o ANCM V2 com os aplicativos ASP.NET Core 3.0.

Se o ANCM V1 for necessário, ele poderá ser instalado usando o Pacote de Hospedagem do Windows do ASP.NET Core 2.1 ou 2.2.

Essa alteração interromperá os aplicativos ASP.NET Core 3.0 que:

  • Optaram explicitamente por usar o ANCM V1 com <AspNetCoreModuleName>AspNetCoreModule</AspNetCoreModuleName>.
  • Têm um arquivo web.config personalizado com <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Hospedagem: o host genérico restringe a injeção de construtor de inicialização

Os únicos tipos aos quais o host genérico dá suporte para injeção de construtor de classe Startup são IHostEnvironment, IWebHostEnvironment e IConfiguration. Os aplicativos que usam WebHost não foram afetados.

Descrição das alterações

Antes do ASP.NET Core 3.0, a injeção de construtor podia ser usada para tipos arbitrários no construtor da classe Startup. No ASP.NET Core 3.0, a pilha da Web foi mudou para uma plataforma de biblioteca de host genérica. Você pode ver a alteração no arquivo Program.cs dos modelos:

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

O Host usa um contêiner de DI (injeção de dependência) para compilar o aplicativo. O WebHost usa dois contêineres: um para o host e outro para o aplicativo. Como resultado, o construtor Startup não dá mais suporte à injeção de serviço personalizada. Somente IHostEnvironment, IWebHostEnvironment e IConfiguration pode ser injetado. Essa alteração impede problemas de DI, como a criação duplicada de um serviço singleton.

Versão introduzida

3.0

Motivo da alteração

Essa alteração é consequência da mudança de plataforma da pilha da Web na biblioteca de host genérica.

Injete serviços na assinatura do método Startup.Configure. Por exemplo:

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

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Hospedagem: redirecionamento de HTTPS habilitado para aplicativos fora de processo do IIS

A versão 13.0.19218.0 do ANCM (ASP.NET Core Module) para hospedagem por meio do IIS fora do processo permite um recurso de redirecionamento HTTPS existente para ASP.NET Core aplicativos 3.0 e 2.2 existentes.

Para ver a discussão, confira dotnet/AspNetCore#15243.

Versão introduzida

3.0

Comportamento antigo

O modelo de projeto do ASP.NET Core 2.1 introduziu pela primeira vez o suporte para métodos de middleware HTTPS, como UseHttpsRedirection e UseHsts. A habilitação do redirecionamento HTTPS exigia a adição da configuração, já que os aplicativos em desenvolvimento não usam a porta padrão 443. HSTS (HTTP Strict Transport Security) só estará ativo se a solicitação já estiver usando HTTPS. Localhost é ignorado por padrão.

Novo comportamento

No ASP.NET Core 3.0, o cenário HTTPS do IIS foi aprimorado. Com o aprimoramento, um aplicativo pode descobrir as portas HTTPS do servidor e fazer UseHttpsRedirection funcionar por padrão. O componente em processo realiza a descoberta da porta com o recurso IServerAddresses, o que afeta apenas aplicativos ASP.NET Core 3.0 porque a biblioteca em processo é usada com a estrutura. O componente fora do processo foi alterado para adicionar automaticamente a variável de ambiente ASPNETCORE_HTTPS_PORT. Essa alteração afetou os aplicativos ASP.NET Core 2.2 e 3.0 porque o componente fora de processo é compartilhado globalmente. Os aplicativos ASP.NET Core 2.1 não são afetados porque usam uma versão anterior do ANCM por padrão.

O comportamento anterior foi modificado no ASP.NET Core 3.0.1 e 3.1.0 versão prévia 3 para reverter as alterações de comportamento no ASP.NET Core 2.x. Essas alterações afetam apenas os aplicativos fora de processo do IIS.

Conforme detalhado acima, a instalação do ASP.NET Core 3.0.0 teve o efeito colateral de também ativar o middleware UseHttpsRedirection nos aplicativos ASP.NET Core 2.x. Foi feita uma alteração no ANCM no ASP.NET Core 3.0.1 e 3.1.0 versão prévia 3, de modo que a instalação deles não tem mais esse efeito em aplicativos ASP.NET Core 2.x. A variável de ambiente ASPNETCORE_HTTPS_PORT que o ANCM populava no ASP.NET Core 3.0.0 foi alterada para ASPNETCORE_ANCM_HTTPS_PORT no ASP.NET Core 3.0.1 e 3.1.0 versão prévia 3. UseHttpsRedirection também foi atualizado nessas versões para entender as variáveis novas e antigas. O ASP.NET Core 2.x não será atualizado. Como resultado, ele será revertido para o comportamento anterior de ser desabilitado por padrão.

Motivo da alteração

Funcionalidade aprimorada do ASP.NET Core 3.0.

Nenhuma ação será necessária se você quiser que todos os clientes usem HTTPS. Para permitir que alguns clientes usem HTTP, execute uma das seguintes etapas:

  • Remova as chamadas para UseHttpsRedirection e UseHsts do método do projeto Startup.Configure e reimplante o aplicativo.

  • No arquivo web.config, defina a variável de ambiente ASPNETCORE_HTTPS_PORT como uma cadeia de caracteres vazia. Essa alteração pode ocorrer diretamente no servidor sem reimplantar o aplicativo. Por exemplo:

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

UseHttpsRedirection ainda pode ser:

  • Ativado manualmente no ASP.NET Core 2.x definindo a variável de ambiente ASPNETCORE_HTTPS_PORT como o número da porta apropriado (443 na maioria dos cenários de produção).
  • Desativado no ASP.NET Core 3.x definindo ASPNETCORE_ANCM_HTTPS_PORT com um valor de cadeia de caracteres vazio. Esse valor é definido da mesma forma que o exemplo anterior ASPNETCORE_HTTPS_PORT.

Os computadores que executam aplicativos ASP.NET Core 3.0.0 devem instalar o runtime do ASP.NET Core 3.0.1 antes de instalar o ANCM do ASP.NET Core 3.1.0 versão prévia 3. Isso garante que UseHttpsRedirection continue operando conforme o esperado para os aplicativos ASP.NET Core 3.0.

No Serviço de Aplicativo do Azure, o ANCM é implantado em um agendamento separado do runtime devido à sua natureza global. O ANCM foi implantado no Azure com essas alterações após a implantação do ASP.NET Core 3.0.1 e 3.1.0.

Categoria

ASP.NET Core

APIs afetadas

HttpsPolicyBuilderExtensions.UseHttpsRedirection(IApplicationBuilder)

Hospedagem: tipos IHostingEnvironment e IApplicationLifetime marcados como obsoletos e substituídos

Novos tipos foram introduzidos para substituir os tipos existentes IHostingEnvironment e IApplicationLifetime.

Versão introduzida

3.0

Comportamento antigo

Havia dois tipos diferentes IHostingEnvironment e IApplicationLifetime de Microsoft.Extensions.Hosting e Microsoft.AspNetCore.Hosting.

Novo comportamento

Os tipos antigos foram marcados como obsoletos e substituídos por novos tipos.

Motivo da alteração

Quando Microsoft.Extensions.Hosting foi introduzido no ASP.NET Core 2.1, alguns tipos como IHostingEnvironment e IApplicationLifetime foram copiados de Microsoft.AspNetCore.Hosting. Algumas alterações do ASP.NET Core 3.0 fazem com que os aplicativos incluam os namespaces Microsoft.Extensions.Hosting e Microsoft.AspNetCore.Hosting. Qualquer uso desses tipos duplicados causa um erro de compilador de "referência ambígua" quando os dois namespaces são referenciados.

Substitua todos os usos dos tipos antigos pelos tipos recém-introduzidos, desta forma:

Tipos obsoletos (aviso):

Novos tipos:

Os métodos novos IHostEnvironmentIsDevelopment e IsProduction de extensão estão no namespace Microsoft.Extensions.Hosting. Talvez esse namespace precise ser adicionado ao projeto.

Categoria

ASP.NET Core

APIs afetadas

Hospedagem: ObjectPoolProvider removido das dependências do WebHostBuilder

Como parte do aprimoramento do ASP.NET Core, o ObjectPoolProvider foi removido do conjunto principal de dependências. Os componentes específicos que dependem do ObjectPoolProvider agora o adicionam por conta própria.

Para ver a discussão, confira dotnet/aspnetcore#5944.

Versão introduzida

3.0

Comportamento antigo

WebHostBuilder fornece ObjectPoolProvider por padrão no contêiner de DI.

Novo comportamento

WebHostBuilder não fornece mais ObjectPoolProvider por padrão no contêiner de DI.

Motivo da alteração

Essa mudança foi feita para fazer o ASP.NET Core valer mais a pena.

Se o componente exige o ObjectPoolProvider, ele precisará ser adicionado às dependências por meio do IServiceCollection.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

HTTP: extensibilidade de DefaultHttpContext removida

Como parte dos aprimoramentos de desempenho do ASP.NET Core 3.0, a extensibilidade DefaultHttpContext foi removida. A classe agora é sealed. Para obter mais informações, confira dotnet/aspnetcore#6504.

Se os testes de unidade usarem Mock<DefaultHttpContext>, use Mock<HttpContext> ou new DefaultHttpContext().

Para ver a discussão, confira dotnet/aspnetcore#6534.

Versão introduzida

3.0

Comportamento antigo

As classes podem ser derivadas de DefaultHttpContext.

Novo comportamento

As classes não podem ser derivadas de DefaultHttpContext.

Motivo da alteração

A extensibilidade foi fornecida inicialmente para permitir o agrupamento do HttpContext, mas gerou uma complexidade desnecessária e impediu outras otimizações.

Se você estiver usando o Mock<DefaultHttpContext> em testes de unidade, comece a usar o Mock<HttpContext>.

Categoria

ASP.NET Core

APIs afetadas

Microsoft.AspNetCore.Http.DefaultHttpContext

HTTP: constantes HeaderNames alteradas para estáticas somente leitura

Começando no ASP.NET Core 3.0 versão prévia 5, os campos em Microsoft.Net.Http.Headers.HeaderNames foram alterados de const para static readonly.

Para ver a discussão, confira dotnet/aspnetcore#9514.

Versão introduzida

3.0

Comportamento antigo

Esses campos eram const.

Novo comportamento

Esses campos agora são static readonly.

Motivo da alteração

A alteração:

  • Impede que os valores sejam inseridos entre limites de assembly, permitindo correções de valor conforme o necessário.
  • Acelera as verificações de igualdade de referência.

Recompilar em relação ao 3.0. O código-fonte que usa esses campos das seguintes maneiras não pode mais usá-lo:

  • Como um argumento de atributo
  • Como um case em uma instrução switch
  • Ao definir outro const

Para contornar a alteração interruptiva, passe a usar constantes de nome de cabeçalho autodefinidas ou literais de cadeia de caracteres.

Categoria

ASP.NET Core

APIs afetadas

Microsoft.Net.Http.Headers.HeaderNames

HTTP: alterações na infraestrutura do corpo da resposta

A infraestrutura que dá suporte a um corpo da resposta HTTP foi alterada. Se você estiver usando o HttpResponse diretamente, não precisará fazer nenhuma alteração de código. Leia mais se você estiver encapsulando ou substituindo o HttpResponse.Body ou acessando o HttpContext.Features.

Versão introduzida

3.0

Comportamento antigo

Havia três APIs associadas ao corpo da resposta HTTP:

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

Novo comportamento

Se você substituir o HttpResponse.Body, ele substituirá todo o IHttpResponseBodyFeature por um wrapper no fluxo fornecido usando StreamResponseBodyFeature para fornecer as implementações padrão para todas as APIs esperadas. A configuração do fluxo original reverte essa alteração.

Motivo da alteração

A motivação é combinar as APIs do corpo da resposta em uma só nova interface de recurso.

Use IHttpResponseBodyFeature no lugar em que você usava IHttpResponseFeature.Body, IHttpSendFileFeature ou IHttpBufferingFeature.

Categoria

ASP.NET Core

APIs afetadas

SameSite é uma opção para cookies que pode ajudar a mitigar alguns ataques de CSRF (solicitação intersite forjada). Quando essa opção foi introduzida inicialmente, padrões inconsistentes foram usados em várias APIs do ASP.NET Core. A inconsistência levou a resultados confusos. Do ASP.NET Core 3.0 em diante, esses padrões estão mais alinhados. Você precisa aceitar esse recurso em cada componente.

Versão introduzida

3.0

Comportamento antigo

APIs do ASP.NET Core semelhantes usavam valores padrão de SameSiteMode diferentes. Um exemplo da inconsistência é visto em HttpResponse.Cookies.Append(String, String) e HttpResponse.Cookies.Append(String, String, CookieOptions), que usavam como padrão SameSiteMode.None e SameSiteMode.Lax, respectivamente.

Novo comportamento

Todas as APIs afetadas usam como padrão SameSiteMode.None.

Motivo da alteração

O valor padrão foi alterado para que SameSite seja um recurso de aceitação.

Cada componente que emite cookies precisa decidir se SameSite é apropriado para os respectivos cenários. Examine o uso das APIs afetadas e reconfigure o SameSite conforme o necessário.

Categoria

ASP.NET Core

APIs afetadas

HTTP: E/S síncrona desabilitada em todos os servidores

Do ASP.NET Core 3.0 em diante, as operações de servidor síncronas são desabilitadas por padrão.

Descrição das alterações

AllowSynchronousIO é uma opção em cada servidor que habilita ou desabilita APIs de E/S síncronas como HttpRequest.Body.Read, HttpResponse.Body.Write e Stream.Flush. Essas APIs têm sido uma fonte de privação de threads e travamentos de aplicativos. Do ASP.NET Core 3.0 versão prévia 3 em diante, essas operações síncronas são desabilitadas por padrão.

Servidores afetados:

  • Kestrel
  • HttpSys
  • IIS em processo
  • TestServer

Espera-se erros semelhantes a:

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

Cada servidor tem uma opção AllowSynchronousIO que controla esse comportamento e o padrão para todos eles agora é false.

O comportamento também pode ser substituído por solicitação como uma mitigação temporária. Por exemplo:

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

Se você tiver problemas com um TextWriter ou outro fluxo chamando uma API síncrona em Dispose, chame a nova API DisposeAsync.

Para ver a discussão, confira dotnet/aspnetcore#7644.

Versão introduzida

3.0

Comportamento antigo

HttpRequest.Body.Read, HttpResponse.Body.Writee Stream.Flush eram permitidos por padrão.

Novo comportamento

Estas APIs síncronas são não permitidas por padrão:

Espera-se erros semelhantes a:

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

Motivo da alteração

Essas APIs síncronas têm sido uma fonte de privação de threads e travamentos de aplicativos. Do ASP.NET Core 3.0 versão prévia 3 em diante, as operações síncronas são desabilitadas por padrão.

Use as versões assíncronas dos métodos. O comportamento também pode ser substituído por solicitação como uma mitigação temporária.

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

Categoria

ASP.NET Core

APIs afetadas

Identity: sobrecarga do método AddDefaultUI removida

Do ASP.NET Core 3.0 em diante, a sobrecarga do método IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder, UIFramework) não existe mais.

Versão introduzida

3.0

Motivo da alteração

Essa alteração foi resultado da adoção do recurso de ativos Web estáticos.

Chame IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder) em vez da sobrecarga que usa dois argumentos. Se você estiver usando o Bootstrap 3, adicione também a seguinte linha a um elemento <PropertyGroup> no arquivo de projeto:

<IdentityUIFrameworkVersion>Bootstrap3</IdentityUIFrameworkVersion>

Categoria

ASP.NET Core

APIs afetadas

IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder,UIFramework)

Identity: a versão padrão da interface do usuário do Bootstrap foi alterada

Do ASP.NET Core 3.0 em diante, a interface do usuário do Identity usa a versão 4 do Bootstrap.

Versão introduzida

3.0

Comportamento antigo

A chamada de método services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(); era a mesma que services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap3);

Novo comportamento

A chamada de método services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(); é a mesma que services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap4);

Motivo da alteração

O Bootstrap 4 foi lançado durante o período do ASP.NET Core 3.0.

Você será afetado por essa alteração se usar a interface do usuário padrão do Identity e a tiver adicionado em Startup.ConfigureServices, conforme é mostrado no seguinte exemplo:

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

Execute uma das seguintes ações:

  • Migre o aplicativo para usar o Bootstrap 4 seguindo o respectivo guia de migração.

  • Atualize o Startup.ConfigureServices para impor o uso do Bootstrap 3. Por exemplo:

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

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Identity: SignInAsync gera exceção para identidade não autenticada

Por padrão, SignInAsync gera uma exceção para entidades de segurança/identidades em que IsAuthenticated é false.

Versão introduzida

3.0

Comportamento antigo

SignInAsync aceita quaisquer entidades de segurança/identidades, incluindo identidades nas quais IsAuthenticated é false.

Novo comportamento

Por padrão, SignInAsync gera uma exceção para entidades de segurança/identidades em que IsAuthenticated é false. Há um novo sinalizador para suprimir esse comportamento, mas o comportamento padrão mudou.

Motivo da alteração

O comportamento antigo era problemático porque, por padrão, essas entidades de segurança eram rejeitadas por [Authorize] / RequireAuthenticatedUser().

No ASP.NET Core 3.0 versão prévia 6, há um sinalizador RequireAuthenticatedSignIn em AuthenticationOptions que é true por padrão. Defina esse sinalizador como false para restaurar o comportamento antigo.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Identity: construtor SignInManager aceita novo parâmetro

Do ASP.NET Core 3.0 em diante, um novo parâmetro IUserConfirmation<TUser> foi adicionado ao construtor SignInManager. Para obter mais informações, confira dotnet/aspnetcore#8356.

Versão introduzida

3.0

Motivo da alteração

A motivação para a alteração foi adicionar suporte para novos fluxos de email/confirmação no Identity.

Se estiver construindo um SignInManager manualmente, forneça uma implementação de IUserConfirmation ou pegue uma da injeção de dependência a ser fornecida.

Categoria

ASP.NET Core

APIs afetadas

SignInManager<TUser>

Identity: interface do usuário usa o recurso de ativos Web estáticos

O ASP.NET Core 3.0 introduziu um recurso de ativos Web estáticos e a interface do usuário do Identity o adotou.

Descrição das alterações

Como resultado da adoção do recurso de ativos Web estáticos pela interface do usuário do Identity:

  • A seleção da estrutura é realizada usando a propriedade IdentityUIFrameworkVersion no arquivo de projeto.
  • O Bootstrap 4 é a estrutura de interface do usuário padrão para a interface do usuário do Identity. O Bootstrap 3 atingiu o fim da vida útil e você deve considerar a migração para uma versão com suporte.

Versão introduzida

3.0

Comportamento antigo

A estrutura de interface do usuário padrão do Identity era o Bootstrap 3. A estrutura da interface do usuário podia ser configurada usando um parâmetro para a chamada de método AddDefaultUI em Startup.ConfigureServices.

Novo comportamento

A estrutura de interface do usuário padrão do Identity é o Bootstrap 4. A estrutura da interface do usuário precisa ser configurada no arquivo de projeto, não na chamada do método AddDefaultUI.

Motivo da alteração

A adoção do recurso de ativos Web estáticos exigiu que a configuração da estrutura de interface do usuário mudasse para o MSBuild. A decisão sobre qual estrutura inserir é uma decisão de tempo de compilação, não uma decisão de tempo de execução.

Examine a interface do usuário do site para garantir que os novos componentes do Bootstrap 4 sejam compatíveis. Se necessário, use a propriedade IdentityUIFrameworkVersion do MSBuild para reverter para o Bootstrap 3. Adicione a propriedade a um elemento <PropertyGroup> no arquivo de projeto:

<IdentityUIFrameworkVersion>Bootstrap3</IdentityUIFrameworkVersion>

Categoria

ASP.NET Core

APIs afetadas

IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder, UIFramework)

Kestrel: adaptadores de conexão removidos

Como parte da mudança para mover as APIs "pubterais" para public, o conceito de um IConnectionAdapter foi removido do Kestrel. Os adaptadores de conexão estão sendo substituídos pelo middleware de conexão (semelhante ao middleware HTTP no pipeline do ASP.NET Core, mas para conexões de nível inferior). Os logs de conexões e HTTPS foram movidos dos adaptadores de conexão para o middleware de conexão. Esses métodos de extensão devem continuar funcionando perfeitamente, mas os detalhes da implementação foram alterados.

Para obter mais informações, confira dotnet/aspnetcore#11412. Para ver a discussão, confira dotnet/aspnetcore#11475.

Versão introduzida

3.0

Comportamento antigo

Os componentes de extensibilidade do Kestrel eram criados usando IConnectionAdapter.

Novo comportamento

Os componentes de extensibilidade do Kestrel são criados como middleware.

Motivo da alteração

Essa alteração se destina a fornecer uma arquitetura de extensibilidade mais flexível.

Converta todas as implementações de IConnectionAdapter para usar o novo padrão de middleware, conforme mostrado aqui.

Categoria

ASP.NET Core

APIs afetadas

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

Kestrel: assembly HTTPS vazio removido

O assembly Microsoft.AspNetCore.Server.Kestrel.Https foi removido.

Versão introduzida

3.0

Motivo da alteração

No ASP.NET Core 2.1, o conteúdo de Microsoft.AspNetCore.Server.Kestrel.Https foi movido para Microsoft.AspNetCore.Server.Kestrel.Core. Essa alteração foi feita de maneira não interruptiva usando atributos [TypeForwardedTo].

  • As bibliotecas que fazem referência ao Microsoft.AspNetCore.Server.Kestrel.Https 2.0 devem atualizar todas as dependências do ASP.NET Core para a versão 2.1 ou posterior. Caso contrário, elas poderão ser interrompidas quando carregadas em um aplicativo ASP.NET Core 3.0.
  • Os aplicativos e as bibliotecas direcionados ao ASP.NET Core 2.1 e posterior devem remover todas as referências diretas ao pacote NuGet Microsoft.AspNetCore.Server.Kestrel.Https.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Kestrel: cabeçalhos de trailer de solicitação movidos para a nova coleção

Em versões anteriores, o Kestrel adicionava cabeçalhos de trailer em partes HTTP/1.1 à coleção de cabeçalhos de solicitação quando o corpo da solicitação era lido até o final. Esse comportamento causava preocupações sobre a ambiguidade entre cabeçalhos e trailers. A decisão foi tomada para mover os trailers para uma nova coleção.

Os trailers de solicitação HTTP/2 não estavam disponíveis no ASP.NET Core 2.2, mas agora também estão disponíveis nessa nova coleção no ASP.NET Core 3.0.

Novos métodos de extensão de solicitação foram adicionados para acessar esses trailers.

Os trailers HTTP/1.1 ficam disponíveis depois que todo o corpo da solicitação é lido.

Os trailers HTTP/2 ficam disponíveis quando são recebidos do cliente. O cliente não enviará os trailers até que todo o corpo da solicitação tenha sido pelo menos armazenado em buffer pelo servidor. Talvez seja necessário ler o corpo da solicitação para liberar espaço no buffer. Os trailers estarão sempre disponíveis quando você lê o corpo da solicitação até o final. Os trailers marcam o fim do corpo.

Versão introduzida

3.0

Comportamento antigo

Os cabeçalhos de trailer de solicitação seriam adicionados à coleção HttpRequest.Headers.

Novo comportamento

Os cabeçalhos de trailer de solicitação não estão presentes na coleção HttpRequest.Headers. Use os seguintes métodos de extensão em HttpRequest para acessá-los:

  • GetDeclaredTrailers() – Obtém o cabeçalho "Trailer" da solicitação que lista quais trailers são esperados após o corpo.
  • SupportsTrailers() – Indica se a solicitação dá suporte ao recebimento de cabeçalhos de trailer.
  • CheckTrailersAvailable() – Determina se a solicitação dá suporte a trailers e se eles estão disponíveis para leitura.
  • GetTrailer(string trailerName) – Obtém o cabeçalho de trailer solicitado da resposta.

Motivo da alteração

Trailers são um recurso fundamental em cenários como gRPC. A mesclagem dos trailers nos cabeçalhos de solicitação era confusa para os usuários.

Use os métodos de extensão relacionados a trailer no HttpRequest para acessar os trailers.

Categoria

ASP.NET Core

APIs afetadas

HttpRequest.Headers

Kestrel: abstrações de transporte removidas e alteradas para públicas

Como parte do abandono das APIs "pubterais", as APIs da camada de transporte do Kestrel são expostas como uma interface pública na biblioteca Microsoft.AspNetCore.Connections.Abstractions.

Versão introduzida

3.0

Comportamento antigo

  • As abstrações relacionadas ao transporte estavam disponíveis na biblioteca Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.
  • A propriedade ListenOptions.NoDelay estava disponível.

Novo comportamento

  • A interface IConnectionListener foi introduzida na biblioteca Microsoft.AspNetCore.Connections.Abstractions para expor a funcionalidade mais usada da biblioteca ...Transport.Abstractions.
  • O NoDelay agora está disponível nas opções de transporte (LibuvTransportOptions e SocketTransportOptions).
  • SchedulingMode não está mais disponível.

Motivo da alteração

O ASP.NET Core 3.0 abandonou as APIs "pubterais".

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Localização: ResourceManagerWithCultureStringLocalizer e WithCulture marcados como obsoletos

A classe ResourceManagerWithCultureStringLocalizer e o membro da interface WithCulture geralmente são motivos de confusão para os usuários de localização, principalmente quando eles criam a própria implementação de IStringLocalizer. Esses itens dão ao usuário a impressão de que uma instância de IStringLocalizer varia de acordo com o idioma e o recurso. Na realidade, as instâncias devem variar apenas por recurso. O idioma procurado é determinado pelo CultureInfo.CurrentUICulture em tempo de execução. Para eliminar a fonte de confusão, as APIs foram marcadas como obsoletas no ASP.NET Core 3.0 versão prévia 3. As APIs serão removidas em uma versão futura.

Para ver o contexto, confira dotnet/aspnetcore#3324. Para ver a discussão, confira dotnet/aspnetcore#7756.

Versão introduzida

3.0

Comportamento antigo

Os métodos não eram marcados como Obsolete.

Novo comportamento

Os métodos são marcados como Obsolete.

Motivo da alteração

As APIs representavam um caso de uso que não é recomendado. Havia confusão sobre o design da localização.

Nesse caso, a recomendação é usar ResourceManagerStringLocalizer. Deixe que a cultura seja definida pelo CurrentCulture. Se não houver essa opção, crie e use uma cópia de ResourceManagerWithCultureStringLocalizer.

Categoria

ASP.NET Core

APIs afetadas

Log: classe DebugLogger alterada para interna

Antes do ASP.NET Core 3.0, o modificador de acesso de DebugLogger era public. No ASP.NET Core 3.0, o modificador de acesso foi alterado para internal.

Versão introduzida

3.0

Motivo da alteração

A alteração está sendo feita para:

  • Impor consistência com outras implementações de agente, como ConsoleLogger.
  • Reduzir a superfície da API.

Use o método de extensão AddDebugILoggingBuilder para habilitar o registro em log de depuração. Além disso, DebugLoggerProvider ainda é public quando o serviço precisa ser registrado manualmente.

Categoria

ASP.NET Core

APIs afetadas

Microsoft.Extensions.Logging.Debug.DebugLogger

MVC: sufixo assíncrono cortado de nomes de ação do controlador

Como parte da solução de dotnet/aspnetcore#4849, o ASP.NET Core MVC corta o sufixo Async de nomes de ação por padrão. Do ASP.NET Core 3.0 em diante, essa alteração afeta o roteamento e a geração de link.

Versão introduzida

3.0

Comportamento antigo

Considere o seguinte controlador do ASP.NET Core MVC:

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

A ação é roteável por meio de Product/ListAsync. A geração de link requer a especificação do sufixo Async. Por exemplo:

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

Novo comportamento

No ASP.NET Core 3.0, a ação é roteável por meio de Product/List. O código de geração de link deve omitir o sufixo Async. Por exemplo:

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

Essa alteração não afeta os nomes especificados usando o atributo [ActionName]. O novo comportamento pode ser desabilitado definindo MvcOptions.SuppressAsyncSuffixInActionNames como false em Startup.ConfigureServices:

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

Motivo da alteração

Por convenção, os métodos .NET assíncronos têm o sufixo Async. No entanto, quando um método define uma ação MVC, não convém usar o sufixo Async.

Se o aplicativo depender de ações de MVC que preservam o sufixo Async do nome, escolha uma das seguintes mitigações:

  • Use o atributo [ActionName] para preservar o nome original.
  • Desabilite a renomeação inteiramente definindo MvcOptions.SuppressAsyncSuffixInActionNames como false em Startup.ConfigureServices:
services.AddMvc(options =>
{
   options.SuppressAsyncSuffixInActionNames = false;
});

Categoria

ASP.NET Core

APIs afetadas

Nenhum

MVC: JsonResult mudou para Microsoft.AspNetCore.Mvc.Core

JsonResult mudou para o assembly Microsoft.AspNetCore.Mvc.Core. Esse tipo costumava ser definido em Microsoft.AspNetCore.Mvc.Formatters.Json. Um atributo [TypeForwardedTo] no nível do assembly foi adicionado a Microsoft.AspNetCore.Mvc.Formatters.Json a fim de resolver esse problema para a maioria dos usuários. Aplicativos que usam bibliotecas de terceiros podem encontrar problemas.

Versão introduzida

3.0 versão prévia 6

Comportamento antigo

Um aplicativo que usa uma biblioteca baseada em 2.2 é compilado com êxito.

Novo comportamento

Um aplicativo que usa uma biblioteca baseada em 2.2 falha na compilação. Um erro que contém uma variação do seguinte texto é fornecido:

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'

Para obter um exemplo desse problema, confira dotnet/aspnetcore#7220.

Motivo da alteração

Alterações no nível da plataforma na composição do ASP.NET Core conforme a descrição em aspnet/Announcements#325.

As bibliotecas compiladas na versão 2.2 do Microsoft.AspNetCore.Mvc.Formatters.Json podem precisar ser recompiladas a fim de resolver o problema para todos os consumidores. Se você foi afetado, entre em contato com o autor da biblioteca. Solicite a recompilação da biblioteca para direcioná-la ao ASP.NET Core 3.0.

Categoria

ASP.NET Core

APIs afetadas

Microsoft.AspNetCore.Mvc.JsonResult

MVC: ferramenta de pré-compilação preterida

No ASP.NET Core 1.1, o pacote (ferramenta de pré-compilação MVC) Microsoft.AspNetCore.Mvc.Razor.ViewCompilation foi introduzido para adicionar suporte para compilação em tempo de publicação de arquivos Razor (arquivos .cshtml). No ASP.NET Core 2.1, o SDK do Razor foi introduzido para expandir os recursos da ferramenta de pré-configuração. O SDK do Razor adicionou suporte para compilação de arquivos Razor em tempo de compilação e de publicação. O SDK verifica se os arquivos .cshtml estão corretos em tempo de build enquanto, aprimorando o tempo de inicialização do aplicativo. O SDK do Razor está ativado por padrão e não é necessário fazer nada para começar a usá-lo.

No ASP.NET Core 3.0, a ferramenta de pré-compilação MVC do ASP.NET Core 1.1 foi removida. As versões anteriores do pacote continuarão recebendo correções importantes de bug e de segurança no lançamento do patch.

Versão introduzida

3.0

Comportamento antigo

O pacote Microsoft.AspNetCore.Mvc.Razor.ViewCompilation era usado para pré-compilar exibições do Razor do MVC.

Novo comportamento

O SDK do Razor dá suporte nativo a essa funcionalidade. O pacote Microsoft.AspNetCore.Mvc.Razor.ViewCompilation não é mais atualizado.

Motivo da alteração

O SDK do Razor fornece mais funcionalidade e verifica se os arquivos .cshtml estão corretos em tempo de build. O SDK também aprimora o tempo de inicialização do aplicativo.

Os usuários do ASP.NET Core 2.1 ou posteriores devem fazer a atualização para usar o suporte nativo para pré-recompilação no SDK do Razor. Se bugs ou recursos ausentes impedirem a migração para o SDK do Razor, abra um problema em dotnet/aspnetcore.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

MVC: tipos "pubterais" alterados para internos

No ASP.NET Core 3.0, todos os tipos "pubterais" no MVC foram atualizados para ser public em um namespace com suporte ou internal conforme apropriado.

Descrição das alterações

No ASP.NET Core, os tipos "pubternal" são declarados como public, mas residem em um namespace com o sufixo .Internal. Embora esses tipos sejam public, eles não têm nenhuma política de suporte e estão sujeitos a alterações interruptivas. O uso acidental desses tipos tem sido comum, resultando em alterações interruptivas nesses projetos e limitando a capacidade de manutenção da estrutura.

Versão introduzida

3.0

Comportamento antigo

Alguns tipos no MVC eram public, mas em um namespace .Internal. Esses tipos não tinham nenhuma política de suporte e estavam sujeitos a alterações interruptivas.

Novo comportamento

Todos esses tipos foram atualizados para ser public em um namespace com suporte ou foram marcados como internal.

Motivo da alteração

O uso acidental dos tipos "pubternal" tem sido comum, resultando em alterações interruptivas nesses projetos e limitando a capacidade de manutenção da estrutura.

Se você estiver usando tipos que realmente se tornaram public e foram movidos para um namespace novo e com suporte, atualize as referências para corresponder aos novos namespaces.

Se estiver usando tipos marcados como internal, você precisará encontrar uma alternativa. Os tipos "pubterais" anteriores nunca foram compatíveis com uso público. Se houver tipos específicos nesses namespaces que sejam essenciais para seus aplicativos, registre um problema em dotnet/aspnetcore. Podem ser exigidas algumas considerações para que os tipos solicitados sejam alterados para public.

Categoria

ASP.NET Core

APIs afetadas

Essa alteração inclui tipos nos seguintes namespaces:

  • 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: shim de compatibilidade da Web API removido

Do ASP.NET Core 3.0 em diante, o pacote Microsoft.AspNetCore.Mvc.WebApiCompatShim não está mais disponível.

Descrição das alterações

O pacote Microsoft.AspNetCore.Mvc.WebApiCompatShim (WebApiCompatShim) fornece compatibilidade parcial no ASP.NET Core com a Web API 2 do ASP.NET 4.x para simplificar a migração de implementações da Web API existentes para o ASP.NET Core. No entanto, os aplicativos que usam o WebApiCompatShim não se beneficiam dos recursos relacionados à API enviados em versões recentes do ASP.NET Core. Esses recursos incluem melhor geração de especificação de API aberta, tratamento de erro padronizado e geração de código cliente. Para concentrar melhor os esforços de API na 3.0, o WebApiCompatShim foi removido. Os aplicativos existentes que usam o WebApiCompatShim devem ser migrados para o modelo [ApiController] mais recente.

Versão introduzida

3.0

Motivo da alteração

O shim de compatibilidade da Web API era uma ferramenta de migração. Ele restringe o acesso do usuário a novas funcionalidades adicionadas no ASP.NET Core.

Remova o uso desse shim e migre diretamente para a funcionalidade semelhante no próprio ASP.NET Core.

Categoria

ASP.NET Core

APIs afetadas

Microsoft.AspNetCore.Mvc.WebApiCompatShim

Razor: API RazorTemplateEngine removida

A API RazorTemplateEngine foi removida e substituída por Microsoft.AspNetCore.Razor.Language.RazorProjectEngine.

Para ver a discussão, confira o problema do GitHub dotnet/aspnetcore#25215.

Versão introduzida

3.0

Comportamento antigo

Um mecanismo de modelo pode ser criado e usado para analisar e gerar código para arquivos Razor.

Novo comportamento

RazorProjectEngine pode ser criado e receber o mesmo tipo de informação que RazorTemplateEngine para analisar e gerar código para arquivos Razor. RazorProjectEngine também fornece níveis extras de configuração.

Motivo da alteração

RazorTemplateEngine era muito acoplado às implementações existentes. Esse forte acoplamento gerava mais questionamentos ao tentar configurar corretamente um pipeline de análise/geração do Razor.

Use RazorProjectEngine em vez de RazorTemplateEngine. Considere os exemplos a seguir.

Criar e configurar o 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
        });
Gerar código para um arquivo 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();

Categoria

ASP.NET Core

APIs afetadas

  • RazorTemplateEngine
  • RazorTemplateEngineOptions

Razor: compilação de runtime movida para um pacote

O suporte para compilação de runtime de exibições Razor e Razor Pages foi movido para um pacote separado.

Versão introduzida

3.0

Comportamento antigo

A compilação de runtime está disponível sem exigir pacotes adicionais.

Novo comportamento

A funcionalidade foi movida para o pacote Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

As APIs a seguir estavam disponíveis no Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions para dar suporte à compilação de runtime. As APIs agora estão disponíveis por meio de Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.MvcRazorRuntimeCompilationOptions.

  • RazorViewEngineOptions.FileProviders agora é MvcRazorRuntimeCompilationOptions.FileProviders
  • RazorViewEngineOptions.AdditionalCompilationReferences agora é MvcRazorRuntimeCompilationOptions.AdditionalReferencePaths

Além disso, Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions.AllowRecompilingViewsOnFileChange foi removido. A recompilação em alterações de arquivo é habilitada por padrão com a referência ao pacote Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

Motivo da alteração

Essa alteração foi necessária para remover a dependência da estrutura compartilhada do ASP.NET Core no Roslyn.

Os aplicativos que exigem compilação ou recompilação de runtime de arquivos Razor devem seguir as seguintes etapas:

  1. Adicione uma referência ao pacote Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.

  2. Atualize o método Startup.ConfigureServices do projeto para incluir uma chamada para AddRazorRuntimeCompilation. Por exemplo:

    services.AddMvc()
    .AddRazorRuntimeCompilation();

Categoria

ASP.NET Core

APIs afetadas

Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions

Estado de sessão: APIs obsoletas removidas

As APIs obsoletas para configurar cookies de sessão foram removidas. Para obter mais informações, confira aspnet/Announcements#257.

Versão introduzida

3.0

Motivo da alteração

Essa alteração impõe consistência entre APIs para configurar recursos que usam cookies.

Migre o uso das APIs removidas para suas substituições mais recentes. Considere o exemplo a seguir em 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;
    });
}

Categoria

ASP.NET Core

APIs afetadas

Estrutura compartilhada: assemblies removidos de Microsoft.AspNetCore.App

Do ASP.NET Core 3.0 em diante, a estrutura compartilhada do ASP.NET Core (Microsoft.AspNetCore.App) contém apenas assemblies da Microsoft totalmente desenvolvidos, com suporte e que podem receber manutenção da Microsoft.

Descrição das alterações

Pense na alteração como a redefinição de limites da "plataforma" ASP.NET Core. A estrutura compartilhada poderá ser compilada por qualquer pessoa por meio do GitHub e continuará oferecendo os benefícios existentes das estruturas compartilhadas do .NET Core aos aplicativos. Alguns benefícios incluem tamanho de implantação menor, aplicação de patch centralizada e tempo de inicialização mais rápido.

Como parte da alteração, algumas alterações interruptivas importantes são introduzidas em Microsoft.AspNetCore.App.

Versão introduzida

3.0

Comportamento antigo

Os projetos referenciavam Microsoft.AspNetCore.App por meio de um elemento <PackageReference> no arquivo de projeto.

Além disso, Microsoft.AspNetCore.App continha os seguintes subcomponentes:

  • Json.NET (Newtonsoft.Json)
  • Entity Framework Core (assemblies prefixados com Microsoft.EntityFrameworkCore.)
  • Roslyn (Microsoft.CodeAnalysis)

Novo comportamento

Uma referência a Microsoft.AspNetCore.App não exige mais um elemento <PackageReference> no arquivo de projeto. O SDK do .NET Core dá suporte a um novo elemento chamado <FrameworkReference>, que substitui o uso de <PackageReference>.

Para obter mais informações, confira dotnet/aspnetcore#3612.

O Entity Framework Core é enviado como pacotes NuGet. Essa alteração alinha o modelo de envio com todas as outras bibliotecas de acesso a dados no .NET. Ela fornece ao Entity Framework Core o caminho mais simples para continuar inovando enquanto dá suporte a várias plataformas .NET. A mudança do Entity Framework Core para deixar de usar a estrutura compartilhada não afeta seu status como uma biblioteca desenvolvida pela Microsoft, que recebe suporte e manutenção da Microsoft. Ela continua coberta pela política de suporte do .NET Core.

O Json.NET e o Entity Framework Core continuam a funcionar com o ASP.NET Core. No entanto, eles não serão incluídos na estrutura compartilhada.

Para obter mais informações, confira O futuro do JSON no .NET Core 3.0. Veja também a lista completa de binários removidos da estrutura compartilhada.

Motivo da alteração

Essa alteração simplifica o consumo de Microsoft.AspNetCore.App e reduz a duplicação entre pacotes NuGet e estruturas compartilhadas.

Para obter mais informações sobre a motivação dessa alteração, confira esta postagem no blog.

Do ASP.NET Core 3.0 em diante, não é mais necessário que os projetos consumam assemblies em Microsoft.AspNetCore.App como pacotes NuGet. Para simplificar o direcionamento e o uso da estrutura compartilhada do ASP.NET Core, muitos pacotes NuGet enviados desde o ASP.NET Core 1.0 não são mais produzidos. As APIs fornecidas por esses pacotes ainda estão disponíveis para aplicativos usando um <FrameworkReference> para Microsoft.AspNetCore.App. Exemplos comuns de API incluem Kestrel, MVC e Razor.

Essa alteração não se aplica a todos os binários referenciados por Microsoft.AspNetCore.App no ASP.NET Core 2.x. Exceções notáveis incluem:

Para obter mais informações, confira Parar de produzir pacotes para assemblies de estrutura compartilhada no 3.0. Para ver a discussão, confira dotnet/aspnetcore#3757.

Categoria

ASP.NET Core

APIs afetadas

Estrutura compartilhada: Microsoft.AspNetCore.All removido

Do ASP.NET Core 3.0 em diante, o metapacote Microsoft.AspNetCore.All e a estrutura compartilhada correspondente Microsoft.AspNetCore.All não são mais produzidos. Esse pacote está disponível no ASP.NET Core 2.2 e continuará recebendo atualizações de manutenção no ASP.NET Core 2.1.

Versão introduzida

3.0

Comportamento antigo

Os aplicativos podem usar o metapacote Microsoft.AspNetCore.All para serem direcionados à estrutura compartilhada Microsoft.AspNetCore.All no .NET Core.

Novo comportamento

O .NET Core 3.0 não inclui uma estrutura compartilhada Microsoft.AspNetCore.All.

Motivo da alteração

O metapacote Microsoft.AspNetCore.All incluía um grande número de dependências externas.

Migre seu projeto para usar a estrutura Microsoft.AspNetCore.App. Os componentes que estavam disponíveis no Microsoft.AspNetCore.All ainda estão disponíveis no NuGet. Esses componentes agora são implantados com o aplicativo em vez de serem incluídos na estrutura compartilhada.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

SignalR: HandshakeProtocol.SuccessHandshakeData substituído

O campo HandshakeProtocol.SuccessHandshakeData foi removido e substituído por um método auxiliar que gera uma resposta de handshake bem-sucedida quando um IHubProtocol específico é fornecido.

Versão introduzida

3.0

Comportamento antigo

HandshakeProtocol.SuccessHandshakeData era um campo public static ReadOnlyMemory<byte>.

Novo comportamento

HandshakeProtocol.SuccessHandshakeData foi substituído por um método staticGetSuccessfulHandshake(IHubProtocol protocol) que retorna um ReadOnlyMemory<byte> com base no protocolo especificado.

Motivo da alteração

Campos adicionais foram adicionados à resposta de handshake que não são constantes e são alterados dependendo do protocolo selecionado.

Nenhum. Esse tipo não foi projetado para ser usado por meio do código do usuário. Ele é public, portanto, pode ser compartilhado entre o servidor e o cliente SignalR. Ele também pode ser usado por clientes SignalR do cliente escritos no .NET. Os usuários do SignalR não devem ser afetados por essa alteração.

Categoria

ASP.NET Core

APIs afetadas

HandshakeProtocol.SuccessHandshakeData

SignalR: Métodos HubConnection ResetSendPing e ResetTimeout removidos

Os métodos ResetSendPing e ResetTimeout foram removidos da API HubConnection do SignalR. Esses métodos eram destinados inicialmente apenas a uso interno, mas ficaram públicos no ASP.NET Core 2.2. Esses métodos não estarão disponíveis do ASP.NET Core 3.0 versão prévia 4 em diante. Para ver a discussão, confira dotnet/aspnetcore#8543.

Versão introduzida

3.0

Comportamento antigo

As APIs estavam disponíveis.

Novo comportamento

As APIs foram removidas.

Motivo da alteração

Esses métodos eram destinados inicialmente apenas a uso interno, mas ficaram públicos no ASP.NET Core 2.2.

Não use esses métodos.

Categoria

ASP.NET Core

APIs afetadas

SignalR: construtores HubConnectionContext alterados

Os construtores HubConnectionContext do SignalR foram alterados para aceitar um tipo de opções, em vez de vários parâmetros, considerando futuras opções de adição. Essa alteração substitui dois construtores por um só construtor que aceita um tipo de opções.

Versão introduzida

3.0

Comportamento antigo

HubConnectionContext tem dois construtores:

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

Novo comportamento

Os dois construtores foram removidos e substituídos por um construtor:

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

Motivo da alteração

O novo construtor usa um novo objeto de opções. Consequentemente, os recursos do HubConnectionContext podem ser expandidos no futuro sem necessidade de mais construtores nem de alterações interruptivas.

Em vez de usar o seguinte construtor:

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

Use o seguinte construtor:

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

Categoria

ASP.NET Core

APIs afetadas

SignalR: nome do pacote do cliente JavaScript alterado

No ASP.NET Core 3.0 versão prévia 7, o nome do pacote do cliente JavaScript do SignalR foi alterado de @aspnet/signalr para @microsoft/signalr. A alteração de nome reflete o fato de que o SignalR é útil em mais do que apenas aplicativos ASP.NET Core, graças ao Serviço do Azure SignalR.

Para reagir a essa alteração, altere as referências em arquivos package.json, instruções require e instruções ECMAScript import. Nenhuma API será alterada nessa renomeação.

Para ver a discussão, confira dotnet/aspnetcore#11637.

Versão introduzida

3.0

Comportamento antigo

O pacote cliente se chamava @aspnet/signalr.

Novo comportamento

O pacote cliente se chama @microsoft/signalr.

Motivo da alteração

A alteração de nome esclarece que o SignalR é útil em mais do que apenas aplicativos ASP.NET Core, graças ao Serviço do Azure SignalR.

Mude para o novo pacote @microsoft/signalr.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

SignalR: métodos UseSignalR e UseConnections marcados como obsoletos

Os métodos UseConnections e UseSignalR as classes ConnectionsRouteBuilder e HubRouteBuilder foram marcados como obsoletos no ASP.NET Core 3.0.

Versão introduzida

3.0

Comportamento antigo

O roteamento do hub do SignalR era configurado usando UseSignalR ou UseConnections.

Novo comportamento

A maneira antiga de configurar o roteamento ficou obsoleta e foi substituída pelo roteamento de ponto de extremidade.

Motivo da alteração

O middleware está passando para o novo sistema de roteamento de ponto de extremidade. A maneira antiga de adicionar middleware está ficando obsoleta.

Substituir UseSignalR por UseEndpoints:

Código antigo:

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

Novo código:

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

Categoria

ASP.NET Core

APIs afetadas

SPAs: SpaServices e NodeServices marcados como obsoletos

O conteúdo dos pacotes NuGet a seguir ficou desnecessário desde o ASP.NET Core 2.1. Consequentemente, os seguintes pacotes estão sendo marcados como obsoletos:

Pelo mesmo motivo, os seguintes módulos npm estão sendo marcados como preteridos:

Os pacotes e os módulos npm anteriores serão removidos posteriormente no .NET 5.

Versão introduzida

3.0

Comportamento antigo

Os pacotes e os módulos npm preteridos eram destinados a integrar o ASP.NET Core a várias estruturas de SPA (aplicativo de página única). Essas estruturas incluem Angular, React e React com Redux.

Novo comportamento

Existe um novo mecanismo de integração no pacote NuGet Microsoft.AspNetCore.SpaServices.Extensions. O pacote continua sendo a base dos modelos de projeto Angular e React desde o ASP.NET Core 2.1.

Motivo da alteração

O ASP.NET Core dá suporte à integração com várias estruturas de SPA (aplicativo de página única), incluindo Angular, React e React com Redux. Inicialmente, a integração com essas estruturas foi realizada com componentes específicos do ASP.NET Core que lidavam com cenários como a pré-renderização do servidor e a integração com o Webpack. Com o passar do tempo, os padrões do setor mudaram. Cada uma das estruturas de SPA lançou as próprias interfaces de linha de comando padrão. Por exemplo, a CLI do Angular e o create-react-app.

Quando o ASP.NET Core 2.1 foi lançado em maio de 2018, a equipe respondeu à mudança nos padrões. Foi fornecida uma forma mais nova e mais simples de se integrar às próprias cadeiras de ferramentas das estruturas SPA. O novo mecanismo de integração existe no pacote Microsoft.AspNetCore.SpaServices.Extensions e continua sendo a base dos modelos de projeto Angular e React desde o ASP.NET Core 2.1.

Para esclarecer que os componentes mais antigos específicos do ASP.NET Core são irrelevantes e não recomendados:

  • O mecanismo de integração pré-2.1 foi marcado como obsoleto.
  • Os pacotes npm de suporte foram marcados como preteridos.

Se você estiver usando esses pacotes, atualize os aplicativos para usar a funcionalidade:

  • No pacote Microsoft.AspNetCore.SpaServices.Extensions.
  • Fornecida pelas estruturas do SPA que você está usando

Para habilitar recursos como pré-renderização do servidor e recarregamento de módulos quentes, confira a documentação da estrutura do SPA correspondente. A funcionalidade em Microsoft.AspNetCore.SpaServices.Extensionsnão está obsoleta e continuará com suporte.

Categoria

ASP.NET Core

APIs afetadas

SPAs: SpaServices e NodeServices não retornam mais ao agente de console

Microsoft.AspNetCore.SpaServices e Microsoft.AspNetCore.NodeServices não exibirão logs de console, a menos que o registro em log esteja configurado.

Versão introduzida

3.0

Comportamento antigo

Microsoft.AspNetCore.SpaServices e Microsoft.AspNetCore.NodeServices criavam um agente de console automaticamente quando o registro em log não estava configurado.

Novo comportamento

Microsoft.AspNetCore.SpaServices e Microsoft.AspNetCore.NodeServices não exibirão logs de console, a menos que o registro em log esteja configurado.

Motivo da alteração

É necessário se alinhar com a forma como outros pacotes do ASP.NET Core implementam o registro em log.

Se o comportamento antigo for necessário, para configurar o registro em log do console, adicione services.AddLogging(builder => builder.AddConsole()) ao método Setup.ConfigureServices.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Estrutura de destino: suporte ao .NET Framework removido

Do ASP.NET Core 3.0 em diante, o .NET Framework é uma estrutura de destino sem suporte.

Descrição das alterações

O .NET Framework 4.8 é a última versão principal do .NET Framework. Novos aplicativos ASP.NET Core devem ser criados no .NET Core. Do lançamento do .NET Core 3.0 em diante, considere o ASP.NET Core 3.0 como parte do .NET Core.

Os clientes que usam o ASP.NET Core com o .NET Framework puderam continuar usando a versão 2.1 LTS contando com suporte completo. O suporte e a manutenção do 2.1 continuaram até pelo menos 21 de agosto de 2021. Essa data foi três anos após a declaração da versão LTS de acordo com a Política de Suporte do .NET. O suporte para pacotes ASP.NET Core 2.1 no .NET Framework será estendido indefinidamente, semelhante à política de manutenção para outras estruturas do ASP.NET baseadas em pacote.

Para obter mais informações sobre a portabilidade do .NET Framework para o .NET Core, confira Portabilidade para o .NET Core.

Os pacotes Microsoft.Extensions (como registro em log, injeção de dependência e configuração) e o Entity Framework Core não foram afetados. Eles continuarão a dar suporte ao .NET Standard.

Para obter mais informações sobre a motivação dessa alteração, confira a postagem original no blog.

Versão introduzida

3.0

Comportamento antigo

Os aplicativos ASP.NET Core podiam ser executados no .NET Core ou no .NET Framework.

Novo comportamento

Os aplicativos ASP.NET Core só podem ser executados no .NET Core.

Execute uma das seguintes ações:

  • Mantenha o aplicativo no ASP.NET Core 2.1.
  • Migre o aplicativo e as dependências para o .NET Core.

Categoria

ASP.NET Core

APIs afetadas

Nenhum

Bibliotecas principais do .NET

APIs que relatam a versão agora relatam o produto e não a versão do arquivo

Muitas das APIs que retornam versões no .NET Core agora retornam a versão do produto em vez da versão do arquivo.

Descrição das alterações

No .NET Core 2.2, e em versões anteriores, métodos como Environment.Version, RuntimeInformation.FrameworkDescription e a caixa de diálogo propriedades do arquivo para assemblies do .NET Core refletem a versão do arquivo. Do .NET Core 3.0 em diante, eles refletem a versão do produto.

A figura a seguir ilustra a diferença nas informações de versão do assembly System.Runtime.dll para o .NET Core 2.2 (à esquerda) e o .NET Core 3.0 (à direita), conforme exibido pela caixa de diálogo propriedades do arquivo do Windows Explorer.

Difference in product version information

Versão introduzida

3.0

Nenhum. Essa alteração deve tornar a detecção de versão intuitiva em vez de obtusa.

Categoria

Bibliotecas principais do .NET

APIs afetadas

As instâncias personalizadas do EncoderFallbackBuffer não podem fazer fallback recursivamente

As instâncias personalizadas EncoderFallbackBuffer não podem fazer fallback recursivamente. A implementação de EncoderFallbackBuffer.GetNextChar() deve resultar em uma sequência de caracteres que é conversível para a codificação de destino. Caso contrário, uma exceção ocorrerá.

Descrição das alterações

Durante uma operação de transcodificação de caractere a byte, o runtime detecta sequências UTF-16 mal formadas ou não reversíveis e fornece esses caracteres para o método EncoderFallbackBuffer.Fallback. O método Fallback determina quais caracteres devem ser substituídos pelos dados não reversíveis originais e esses caracteres são drenados chamando EncoderFallbackBuffer.GetNextChar em um loop.

Em seguida, o runtime tenta transcodificar esses caracteres de substituição para a codificação de destino. Se essa operação for bem-sucedida, o runtime continuará a transcodificação de onde parou na cadeia de caracteres de entrada original.

Anteriormente, as implementações personalizadas de EncoderFallbackBuffer.GetNextChar() podem retornar sequências de caracteres que não são conversíveis para a codificação de destino. Se os caracteres substituídos não puderem ser transcodificados para a codificação de destino, o runtime invocará o método EncoderFallbackBuffer.Fallback mais uma vez com os caracteres de substituição, esperando que o método EncoderFallbackBuffer.GetNextChar() retorne uma nova sequência de substituição. Esse processo continua até que o runtime eventualmente veja uma substituição conversível bem formada ou até que uma contagem máxima de recursão seja atingida.

Do .NET Core 3.0 em diante, as implementações personalizadas de EncoderFallbackBuffer.GetNextChar() devem retornar sequências de caracteres conversíveis para a codificação de destino. Se os caracteres substituídos não puderem ser transcodificados para a codificação de destino, um ArgumentException será gerado. O runtime não fará mais chamadas recursivas na instância EncoderFallbackBuffer.

Esse comportamento só se aplica quando todas as três condições seguintes são atendidas:

  • O runtime detecta uma sequência UTF-16 mal formada ou uma sequência UTF-16 que não pode ser convertida na codificação de destino.
  • Um EncoderFallback personalizado foi especificado.
  • As tentativas personalizadas EncoderFallback de substituir uma nova sequência UTF-16 mal formada ou não reversível.

Versão introduzida

3.0

A maioria dos desenvolvedores não precisa tomar nenhuma ação.

Se um aplicativo usa classes EncoderFallback e EncoderFallbackBuffer personalizadas, verifique se a implementação de EncoderFallbackBuffer.Fallback popula o buffer de fallback com os dados UTF-16 bem formados que são diretamente conversíveis para a codificação de destino, quando o método Fallback é invocado pela primeira vez pelo runtime.

Categoria

Bibliotecas principais do .NET

APIs afetadas

Alterações de comportamento de formatação e análise de ponto flutuante

O comportamento de análise e formatação de ponto flutuante (por tipos Double e Single) agora é compatível com IEEE. Isso garante que o comportamento de tipos de ponto flutuante no .NET corresponda ao de outras linguagens compatíveis com IEEE. Por exemplo, double.Parse("SomeLiteral") sempre deve corresponder ao que o C# produz para double x = SomeLiteral.

Descrição das alterações

No .NET Core 2.2 e versões anteriores, a formatação com Double.ToString e Single.ToString e a análise com Double.Parse, Double.TryParse, Single.Parse e Single.TryParse não são compatíveis com IEEE. Como resultado, é impossível garantir que um valor seja arredondado com qualquer cadeia de caracteres de formato padrão ou personalizado com suporte. Para algumas entradas, a tentativa de analisar um valor formatado pode falhar e, para outras, o valor analisado não é igual ao valor original.

Do .NET Core 3.0 em diante, as operações de análise e formatação de ponto flutuante são compatíveis com o IEEE 754.

A tabela a seguir mostra dois snippets de código e como a saída é alterada entre o .NET Core 2.2 e o .NET Core 3.1.

Snippet de código Saída no .NET Core 2.2 Saída no .NET Core 3.1
Console.WriteLine((-0.0).ToString()); 0 -0
var value = -3.123456789123456789;
Console.WriteLine(value == double.Parse(value.ToString()));		 False True

Para obter mais informações, confira a postagem no blog Aprimoramentos de formatação e análise de ponto flutuante no .NET Core 3.0.

Versão introduzida

3.0

O impacto potencial na seção de código existente das melhorias de análise e formatação de ponto flutuante na postagem de blog do .NET Core 3.0 sugere algumas alterações que você pode fazer ao seu código se quiser manter o comportamento anterior.

  • Para algumas diferenças na formatação, você pode obter um comportamento equivalente ao comportamento anterior especificando uma cadeia de caracteres de formato diferente.
  • Para diferenças na análise, não há mecanismo para voltar ao comportamento anterior.

Categoria

Bibliotecas principais do .NET

APIs afetadas

As operações de análise de ponto flutuante não falham mais ou lançam uma OverflowException

Os métodos de análise de ponto flutuante não lançam mais um OverflowException ou retornam false quando analisam uma cadeia de caracteres cujo valor numérico está fora do intervalo do tipo Single ou Double ponto flutuante.

Descrição das alterações

No .NET Core 2.2 e em versões anteriores, os métodos Double.Parse e Single.Parse lançam OverflowException para valores que estão fora do intervalo de seu respectivo tipo. Os métodos Double.TryParse e Single.TryParse retornam false para as representações de cadeia de caracteres de valores numéricos fora do intervalo.

Do .NET Core 3.0 em diante, os métodos Double.Parse, Double.TryParse, Single.Parse e Single.TryParse não falham mais ao analisar cadeias de caracteres numéricas fora do intervalo. Em vez disso, os métodos de análise Double retornam Double.PositiveInfinity, para valores que excedem Double.MaxValue, e retornam Double.NegativeInfinity, para valores menores que Double.MinValue. Similarmente, os métodos de análise Single retornam Single.PositiveInfinity, para valores que excedem Single.MaxValue, e retornam Single.NegativeInfinity, para valores menores que Single.MinValue.

Essa alteração foi feita para melhorar a conformidade do IEEE 754:2008.

Versão introduzida

3.0

Essa alteração pode afetar seu código de duas maneiras:

  • Seu código depende do manipulador para a execução OverflowException quando ocorrer um estouro. Nesse caso, você deve remover a instrução catch e colocar qualquer código necessário em uma instrução If que testa se Double.IsInfinity ou Single.IsInfinity é true.

  • Seu código pressupõe que os valores de ponto flutuante não são Infinity. Nesse caso, você deve adicionar o código necessário para verificar se há valores de ponto flutuante PositiveInfinity e NegativeInfinity.

Categoria

Bibliotecas principais do .NET

APIs afetadas

InvalidAsynchronousStateException movido para outro assembly

A classe InvalidAsynchronousStateException foi movida.

Descrição das alterações

No .NET Core 2.2 e versões anteriores, a classe InvalidAsynchronousStateException é encontrada no assembly System.ComponentModel.TypeConverter.

Do .NET Core 3.0 em diante, ele é encontrado no assembly System.ComponentModel.Primitives.

Versão introduzida

3.0

Essa alteração afeta apenas os aplicativos que usam reflexão para carregar InvalidAsynchronousStateException chamando um método como Assembly.GetType ou uma sobrecarga de Activator.CreateInstance que pressupõe que o tipo esteja em um assembly específico. Se esse for o caso, atualize o assembly referenciado na chamada de método para refletir o novo local do assembly do tipo.

Categoria

Bibliotecas principais do .NET

APIs afetadas

Nenhum.

Substituir sequências de bytes UTF-8 mal formadas segue as diretrizes do Unicode

Quando a classe UTF8Encoding encontra uma sequência de bytes UTF-8 mal formada durante uma operação de transcodificação de byte para caractere, ela substitui essa sequência por um caractere ' (U+FFFD REPLACEMENT CHARACTER) na cadeia de caracteres de saída. O .NET Core 3.0 é diferente das versões anteriores do .NET Core e do .NET Framework seguindo a melhor prática de unicode para executar essa substituição durante a operação de transcodificação.

Isso faz parte de um esforço maior para melhorar a manipulação do UTF-8 em todo o .NET, inclusive pelos novos tipos System.Text.Unicode.Utf8 e System.Text.Rune. O tipo UTF8Encoding recebeu uma mecânica aprimorada de tratamento de erros para que produza uma saída consistente com os tipos recém-introduzidos.

Descrição das alterações

Do .NET Core 3.0 em diante, ao transcodificar bytes para caracteres, a classe UTF8Encoding executa a substituição de caracteres com base nas práticas recomendadas Unicode. O mecanismo de substituição usado é descrito pelo Unicode Standard, Versão 12.0, S. 3.9 (PDF) no título intitulado Substituição U+FFFD de Subpartes Máximas.

Esse comportamento só se aplica quando a sequência de bytes de entrada contém dados UTF-8 mal formados. Além disso, se a instância UTF8Encoding tiver sido construída com throwOnInvalidBytes: true, a instância UTF8Encoding continuará a ser lançada na entrada inválida em vez de executar a substituição U+FFFD. Para obter mais informações sobre o construtor UTF8Encoding, confira UTF8Encoding(Boolean, Boolean).

A seguinte tabela ilustra o impacto dessa alteração com uma entrada inválida de 3 bytes:

Entrada de 3 bytes mal formada Saída antes do .NET Core 3.0 Começando com o SDK do .NET Core 3.0
[ ED A0 90 ] [ FFFD FFFD ] (saída de 2 caracteres) [ FFFD FFFD FFFD ] (saída de 3 caracteres)

A saída de 3 caracteres é a preferencial, de acordo com a Tabela 3-9 do PDF Standard Unicode vinculado anteriormente.

Versão introduzida

3.0

Nenhuma ação é necessária por parte do desenvolvedor.

Categoria

Bibliotecas principais do .NET

APIs afetadas

TypeDescriptionProviderAttribute movido para outro assembly

A classe TypeDescriptionProviderAttribute foi movida.

Descrição das alterações

No .NET Core 2.2 e versões anteriores, a classe TypeDescriptionProviderAttribute é encontrada no assembly System.ComponentModel.TypeConverter .

Do .NET Core 3.0 em diante, ela é encontrada no assembly System.ObjectModel.

Versão introduzida

3.0

Essa alteração afeta apenas os aplicativos que usam reflexão para carregar o tipo TypeDescriptionProviderAttribute chamando um método como Assembly.GetType ou uma sobrecarga de Activator.CreateInstance que pressupõe que o tipo esteja em um assembly específico. Se esse for o caso, o assembly referenciado na chamada de método deverá ser atualizado para refletir o novo local do assembly do tipo.

Categoria

Windows Forms

APIs afetadas

Nenhum.

ZipArchiveEntry não lida mais com arquivos com tamanhos de entrada inconsistentes

Os arquivos zip listam o tamanho compactado e o tamanho não compactado no diretório central e no cabeçalho local. Os próprios dados de entrada também indicam seu tamanho. No .NET Core 2.2 e em versões anteriores, esses valores nunca foram verificados quanto à consistência. Do .NET Core 3.0 em diante, eles serão verificados.

Descrição das alterações

No .NET Core 2.2 e nas versões anteriores, ZipArchiveEntry.Open() é bem-sucedido mesmo que o cabeçalho local discordou do cabeçalho central do arquivo zip. Os dados são descompactados até que o final do fluxo compactado seja atingido, mesmo que seu comprimento exceda o tamanho do arquivo não compactado listado no diretório central/cabeçalho local.

Do .NET Core 3.0 em diante, o método ZipArchiveEntry.Open() verifica se o cabeçalho local e o cabeçalho central concordam em tamanhos compactados e não compactados de uma entrada. Se não o fizerem, o método vai gerar InvalidDataException, se o cabeçalho local do arquivo morto e/ou descritor de dados listar os tamanhos que discordam do diretório central do arquivo zip. Ao ler uma entrada, os dados descompactados são truncados para o tamanho do arquivo não compactado listado no cabeçalho.

Essa alteração foi feita para garantir que um valor ZipArchiveEntry representa corretamente o tamanho de seus dados e que somente essa quantidade de dados seja lida.

Versão introduzida

3.0

Reempacotar qualquer arquivo zip que exponha esses problemas.

Categoria

Bibliotecas principais do .NET

APIs afetadas

FieldInfo.SetValue lança exceção para campos estáticos somente init

Do .NET Core 3.0 em diante, uma exceção é gerada quando você tenta definir um valor em um campo estático InitOnly chamando System.Reflection.FieldInfo.SetValue.

Descrição das alterações

Em .NET Framework e versões do .NET Core anteriores à 3.0, você pode definir o valor de um campo estático que é constante depois que ele é inicializado (somente leitura em C#) chamando System.Reflection.FieldInfo.SetValue. No entanto, definir esse campo dessa forma resultou em um comportamento imprevisível com base na estrutura de destino e nas configurações de otimização.

No .NET Core 3.0 e versões posteriores, quando você chama SetValue em um campo estático InitOnly uma exceção System.FieldAccessException é lançada.

Dica

Um campo InitOnly é aquele que só pode ser definido no momento em que é declarado ou no construtor da classe que contém. Em outras palavras, ele é constante depois de inicializado.

Versão introduzida

3.0

Inicialize campos estáticos InitOnly em um construtor estático. Isso se aplica a tipos dinâmicos e não dinâmicos.

Como alternativa, você pode remover o atributo do campo FieldAttributes.InitOnly e, em seguida, chamar FieldInfo.SetValue.

Categoria

Bibliotecas principais do .NET

APIs afetadas

Passar GroupCollection para métodos de extensão tomando IEnumerable<T> requer desambiguidade

Ao chamar um método de extensão que usa IEnumerable<T> ou GroupCollection, você deve desambiguar o tipo usando uma conversão.

Descrição das alterações

Do .NET Core 3.0 em diante, System.Text.RegularExpressions.GroupCollection implementa IEnumerable<KeyValuePair<String,Group>> além dos outros tipos implementados, incluindo IEnumerable<Group>. Isso resulta em ambiguidade ao chamar um método de extensão que usa um IEnumerable<T>. Se você chamar esse método de extensão em uma instância GroupCollection, por exemplo, Enumerable.Count, verá o seguinte erro do compilador:

CS1061: 'GroupCollection' não contém uma definição para "{1}" e não foi possível encontrar nenhum método de extensão "{1}" que aceite um primeiro argumento do tipo ‘{0}’ (você está se esquecendo de usar uma diretiva ou uma referência de assembly?)

Nas versões anteriores do .NET, não havia ambiguidade nem erro do compilador.

Versão introduzida

3.0

Motivo da alteração

Essa foi uma alteração interruptiva involuntária. Pois tem sido assim há algum tempo, não planejamos revertê-la. Além disso, tal alteração seria, por si só, interruptiva.

Para instâncias GroupCollection, desambiguar chamadas para métodos de extensão que aceitam IEnumerable<T> com uma conversão.

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

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

Categoria

Bibliotecas principais do .NET

APIs afetadas

Qualquer método de extensão que aceite IEnumerable<T> é afetado. Por exemplo:

Criptografia

A sintaxe "BEGIN TRUSTED CERTIFICATE" não tem mais suporte para certificados raiz no Linux

Certificados raiz no Linux e em outros sistemas semelhantes a Unix (mas não macOS) podem ser apresentados em duas formas: o cabeçalho PEM padrão BEGIN CERTIFICATE e o cabeçalho PEM específico BEGIN TRUSTED CERTIFICATE do OpenSSL. A última sintaxe permite uma configuração adicional que causou problemas de compatibilidade com a classe System.Security.Cryptography.X509Certificates.X509Chain do .NET Core. BEGIN TRUSTED CERTIFICATE O conteúdo do certificado raiz não é mais carregado pelo mecanismo de cadeia do .NET Core 3.0 em diante.

Descrição das alterações

Anteriormente, as sintaxes BEGIN CERTIFICATE e BEGIN TRUSTED CERTIFICATE eram usadas para preencher a lista de confiança raiz. Se a sintaxe BEGIN TRUSTED CERTIFICATE era usada e opções adicionais eram especificadas no arquivo, X509Chain pode ter relatado que a relação de confiança da cadeia era explicitamente não permitida (X509ChainStatusFlags.ExplicitDistrust). No entanto, se o certificado também foi especificado com a sintaxe BEGIN CERTIFICATE em um arquivo carregado anteriormente, a confiança da cadeia foi permitida.

Do .NET Core 3.0 em diante, BEGIN TRUSTED CERTIFICATE o conteúdo não é mais lido. Se o certificado também não for especificado por meio de uma sintaxe padrão BEGIN CERTIFICATE, o X509Chain relata que a raiz não é confiável (X509ChainStatusFlags.UntrustedRoot).

Versão introduzida

3.0

A maioria dos aplicativos não é afetada por essa alteração, mas aplicativos que não podem ver ambas as fontes de certificado raiz devido a problemas de permissões podem sofrer erros UntrustedRoot inesperados após a atualização.

Muitas distribuições (ou distros) do Linux gravam certificados raiz em dois locais: um diretório de um certificado por arquivo e uma concatenação de um arquivo. Em algumas distribuições, o diretório de um certificado por arquivo usa a sintaxe BEGIN TRUSTED CERTIFICATE enquanto a concatenação do arquivo usa a sintaxe padrão BEGIN CERTIFICATE. Verifique se todos os certificados raiz personalizados são adicionados como BEGIN CERTIFICATE em pelo menos um desses locais e se ambos os locais podem ser lidos pelo aplicativo.

O diretório típico é /etc/ssl/certs/ e o arquivo concatenado típico é /etc/ssl/cert.pem. Use o comando openssl version -d para determinar a raiz específica da plataforma, que pode ser diferente de /etc/ssl/. Por exemplo, no Ubuntu 18.04, o diretório é /usr/lib/ssl/certs/ e o arquivo é /usr/lib/ssl/cert.pem. No entanto, /usr/lib/ssl/certs/ é um symlink para /etc/ssl/certs/ e /usr/lib/ssl/cert.pem não existe.

$ 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

Categoria

Criptografia

APIs afetadas

Os envelopedCms são padrão para a criptografia AES-256

O algoritmo de criptografia simétrica padrão usado por EnvelopedCms foi alterado de TripleDES para AES-256.

Descrição das alterações

Nas versões anteriores, quando EnvelopedCms é usado para criptografar dados sem especificar um algoritmo de criptografia simétrica por meio de uma sobrecarga de construtor, os dados são criptografados com o algoritmo TripleDES/3DES/3DEA/DES3-EDE.

Começando com o .NET Core 3.0 (via versão 4.6.0 do pacote NuGet System.Security.Cryptography.Pkcs), o algoritmo padrão foi alterado para AES-256 para modernização de algoritmo e para melhorar a segurança das opções padrão. Se um certificado de destinatário de mensagem tiver uma chave pública (não EC Diffie-Hellman), a operação de criptografia poderá falhar com um CryptographicException devido a limitações na plataforma subjacente.

No código de exemplo a seguir, os dados são criptografados com TripleDES se estiverem em execução no .NET Core 2.2 ou anterior. Se estiver em execução no .NET Core 3.0 ou posterior, ele será criptografado com o AES-256.

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

Versão introduzida

3.0

Se você for afetado negativamente pela alteração, poderá restaurar a criptografia TripleDES especificando explicitamente o identificador de algoritmo de criptografia em um construtor EnvelopedCms que inclui um parâmetro de tipo AlgorithmIdentifier, como:

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();

Categoria

Criptografia

APIs afetadas

O tamanho mínimo para a geração de chave RSAOpenSsl aumentou

O tamanho mínimo para gerar novas chaves RSA no Linux aumentou de 384 bits para 512 bits.

Descrição das alterações

Do .NET Core 3.0 em diante, o tamanho mínimo de chave legal relatado pela propriedade LegalKeySizes em instâncias RSA de RSA.Create, RSAOpenSsl e RSACryptoServiceProvider no Linux aumentou de 384 para 512.

Como resultado, no .NET Core 2.2 e em versões anteriores, uma chamada de método como RSA.Create(384) é bem-sucedida. No .NET Core 3.0 e versões posteriores, a chamada de método RSA.Create(384) gera uma exceção indicando que o tamanho é muito pequeno.

Essa alteração foi feita porque o OpenSSL, que executa as operações criptográficas no Linux, elevou seu mínimo entre as versões 1.0.2 e 1.1.0. O .NET Core 3.0 prefere o OpenSSL 1.1.x a 1.0.x e a versão mínima relatada foi gerada para refletir essa nova limitação de dependência mais alta.

Versão introduzida

3.0

Se você chamar qualquer uma das APIs afetadas, verifique se o tamanho de qualquer chave gerada não é menor que o mínimo do provedor.

Observação

O RSA de 384 bits já é considerado inseguro (assim como o RSA de 512 bits). Recomendações modernas, como a Publicação Especial NIST 800-57 Parte 1 Revisão 4, sugerem 2048 bits como o tamanho mínimo para chaves recém-geradas.

Categoria

Criptografia

APIs afetadas

O .NET Core 3.0 prefere o OpenSSL 1.1.x ao OpenSSL 1.0.x

O .NET Core para Linux, que funciona em várias distribuições do Linux, pode dar suporte ao OpenSSL 1.0.x e ao OpenSSL 1.1.x. O .NET Core 2.1 e o .NET Core 2.2 primeiro procuram 1.0.x e, em seguida, recuam para 1.1.x; o .NET Core 3.0 procura 1.1.x primeiro. Essa alteração foi feita para adicionar suporte a novos padrões criptográficos.

Essa alteração pode afetar bibliotecas ou aplicativos que fazem interoperabilidade de plataforma com os tipos de interoperabilidade específicos do OpenSSL no .NET Core.

Descrição das alterações

No .NET Core 2.2 e em versões anteriores, o runtime prefere carregar o OpenSSL 1.0.x em vez de 1.1.x. Isso significa que os tipos IntPtr e SafeHandle para interoperabilidade com OpenSSL são usados com libcrypto.so.1.0.0/libcrypto.so.1.0/libcrypto.so.10 por preferência.

Começando com o .NET Core 3.0, o runtime prefere carregar o OpenSSL 1.1.x em vez do OpenSSL 1.0.x, de modo que os tipos IntPtr e SafeHandle para interoperabilidade com OpenSSL sejam usados com libcrypto.so.1.1/libcrypto.so.11/libcrypto.so.1.1.0/libcrypto.so.1.1.1 por preferência. Como resultado, bibliotecas e aplicativos que interoperam diretamente com o OpenSSL podem ter ponteiros incompatíveis com os valores expostos pelo .NET Core ao atualizar do .NET Core 2.1 ou do .NET Core 2.2.

Versão introduzida

3.0

Bibliotecas e aplicativos que fazem operações diretas com o OpenSSL precisam ter cuidado para garantir que estejam usando a mesma versão do OpenSSL que o runtime do .NET Core.

Todas as bibliotecas ou aplicativos que usam valores IntPtr ou SafeHandle dos tipos criptográficos do .NET Core diretamente com o OpenSSL devem comparar a versão da biblioteca que usam com a nova propriedade SafeEvpPKeyHandle.OpenSslVersion para garantir que os ponteiros sejam compatíveis.

Categoria

Criptografia

APIs afetadas

CryptoStream.Dispose transforma o bloco final somente ao gravar

O método CryptoStream.Dispose, que é usado para concluir operações CryptoStream, não tenta mais transformar o bloco final ao ler.

Descrição das alterações

Nas versões anteriores do .NET, se um usuário executasse uma leitura incompleta ao usar CryptoStream no modo Read, o método Dispose poderia gerar uma exceção (por exemplo, ao usar o AES com preenchimento). A exceção foi gerada porque o bloco final tentou ser transformado, mas os dados estavam incompletos.

No .NET Core 3.0 e versões posteriores, Dispose não tenta mais transformar o bloco final ao ler, o que permite leituras incompletas.

Motivo da alteração

Essa alteração permite leituras incompletas do fluxo de criptografia quando uma operação de rede é cancelada, sem a necessidade de capturar uma exceção.

Versão introduzida

3.0

A maioria dos aplicativos não deve ser afetada por essa alteração.

Se o aplicativo tiver pego uma exceção anteriormente em caso de uma leitura incompleta, você poderá excluir esse bloco catch. Se o aplicativo usou a transformação do bloco final em cenários de hash, talvez seja necessário garantir que todo o fluxo seja lido antes de ser descartado.

Categoria

Criptografia

APIs afetadas

Entity Framework Core

Alterações interruptivas do Entity Framework Core

Globalização

A localidade "C" é mapeada para a localidade invariável

O .NET Core 2.2 e versões anteriores dependem do comportamento padrão da ICU, que mapeia a localidade "C" para a localidade en_US_POSIX. A localidade en_US_POSIX tem um comportamento de agrupamento indesejável, pois não dá suporte a comparações de cadeia de caracteres que não diferenciam maiúsculas de minúsculas. Como algumas distribuições do Linux definem a localidade "C" como a localidade padrão, os usuários estavam tendo um comportamento inesperado.

Descrição das alterações

Do .NET Core 3.0 em diante, o mapeamento de localidade "C" foi alterado para usar a localidade invariável em vez de en_US_POSIX. O mapeamento da localidade "C" para invariável também é aplicada ao Windows para consistência.

O mapeamento de "C" para a cultura en_US_POSIX causou confusão no cliente, pois en_US_POSIX não dá suporte a operações de cadeia de caracteres de classificação/pesquisa sem diferenciar maiúsculas de minúsculas. Como a localidade "C" é usada como uma localidade padrão em algumas das distribuições do Linux, os clientes experimentaram esse comportamento indesejado nesses sistemas operacionais.

Versão introduzida

3.0

Nada mais específico do que a consciência dessa mudança. Essa alteração afeta apenas os aplicativos que usam o mapeamento de localidade "C".

Categoria

Globalização

APIs afetadas

Todas as APIs de agrupamento e cultura são afetadas por essa alteração.

MSBuild

Alteração do nome do arquivo de manifesto do recurso

Do .NET Core 3.0 em diante, no caso padrão, o MSBuild gera um nome de arquivo de manifesto diferente para arquivos de recursos.

Versão introduzida

3.0

Descrição das alterações

Antes do .NET Core 3.0, se o metadado LogicalName, ManifestResourceName ou DependentUpon não fosse especificado para um item EmbeddedResource no arquivo de projeto, o MSBuild gerava um nome de arquivo de manifesto no padrão <RootNamespace>.<ResourceFilePathFromProjectRoot>.resources. Se RootNamespace não estava definido no arquivo de projeto, ele era assumido como o nome do projeto. Por exemplo, o nome do manifesto gerado para um arquivo de recurso chamado Form1.resx no diretório raiz do projeto era MyProject.Form1.resources.

Do .NET Core 3.0 em diante, se um arquivo de recurso estiver no mesmo local que um arquivo de origem com o mesmo nome (por exemplo, Form1.resx e Form1.cs), o MSBuild usará as informações de tipo do arquivo de origem para gerar o nome do arquivo de manifesto no padrão <Namespace>.<ClassName>.resources. O namespace e o nome de classe são extraídos do primeiro tipo no arquivo de origem no mesmo local. Por exemplo, o nome do manifesto gerado para um arquivo de recurso chamado Form1.resx que está no mesmo local que um arquivo de origem chamado Form1.cs é MyNamespace.Form1.resources. É importante observar que a primeira parte do nome do arquivo é diferente das versões anteriores do .NET Core (MyNamespace em vez de MyProject).

Observação

Se o metadado LogicalName, ManifestResourceName ou DependentUpon estiver especificado em um item EmbeddedResource no arquivo de projeto, essa alteração não afetará esse arquivo de recurso.

Essa alteração interruptiva foi introduzida com a adição da propriedade EmbeddedResourceUseDependentUponConvention aos projetos do .NET Core. Por padrão, os arquivos de recursos não são listados explicitamente em um arquivo de projeto do .NET Core, portanto, eles não têm metadados DependentUpon para especificar como nomear o arquivo .resources gerado. Quando EmbeddedResourceUseDependentUponConvention é definido como true, que é o padrão, o MSBuild procura um arquivo de origem no mesmo local e extrai um namespace e um nome de classe desse arquivo. Se você definir EmbeddedResourceUseDependentUponConvention como false, o MSBuild vai gerar o nome do manifesto de acordo com o comportamento anterior, que combina RootNamespace e o caminho do arquivo relativo.

Na maioria dos casos, nenhuma ação é necessária por parte do desenvolvedor e o aplicativo deve continuar funcionando. Mas se essa alteração interromper o aplicativo, você poderá:

  • Alterar o código para esperar o novo nome do manifesto.

  • Recusar a nova convenção de nomenclatura definindo EmbeddedResourceUseDependentUponConvention como false no arquivo de projeto.

    <PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>false</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

Categoria

MSBuild

APIs afetadas

N/D

Rede

O valor padrão de HttpRequestMessage.Version mudou para 1.1

O valor padrão da propriedade System.Net.Http.HttpRequestMessage.Version mudou de 2.0 para 1.1.

Versão introduzida

3.0

Descrição das alterações

No .NET Core 1.0 a 2.0, o valor padrão da propriedade System.Net.Http.HttpRequestMessage.Version é 1.1. Do .NET Core 2.1 em diante, o valor foi alterado para 2.1.

Do .NET Core 3.0 em diante, o número de versão padrão retornado pela propriedade System.Net.Http.HttpRequestMessage.Version é novamente 1.1.

Atualize seu código se ele depender do retorno do valor padrão 2.0 pela propriedade System.Net.Http.HttpRequestMessage.Version.

Categoria

Rede

APIs afetadas

Confira também