Compartilhar via

Alterações interruptivas no ASP.NET Core para as versões 3.0 e 3.1

O ASP.NET Core fornece os recursos de desenvolvimento de aplicativos Web usados pelo .NET Core.

Selecione um dos seguintes links para alterações interruptivas em uma versão específica:

As seguintes alterações interruptivas no ASP.NET Core 3.0 e 3.1 estão documentadas nesta página:

ASP.NET Core 3.1

HTTP: as alterações do SameSite do navegador afetam a autenticação

Alguns navegadores, como Chrome e Firefox, fizeram alterações interruptivas nas respectivas implementações de SameSite para cookies. As alterações afetam cenários de autenticação remota, como OpenID Connect e Web Services Federation, que precisam fazer a recusa enviando SameSite=None. No entanto, SameSite=None falha no iOS 12 e em algumas versões mais antigas de outros navegadores. O aplicativo precisa detectar essas versões e omitir SameSite.

Para conferir a discussão sobre esse problema, veja dotnet/aspnetcore#14996.

Versão introduzida

3.1 versão prévia 1

Comportamento antigo

SameSite é uma extensão padrão de rascunho de 2016 para cookies HTTP. Seu objetivo é atenuar a CSRF (solicitação intersite forjada). Ela foi projetada originalmente como um recurso que os servidores aceitariam por meio da adição de novos parâmetros. No ASP.NET Core 2.0 foi adicionado o suporte inicial para SameSite.

Novo comportamento

O Google propôs um novo padrão de rascunho que não é compatível com versões anteriores. O padrão altera o modo padrão para Lax e adiciona uma nova entrada None para a recusa. Lax é suficiente para a maioria dos cookies de aplicativo, no entanto, ele interrompe cenários entre sites, como o logon do OpenID Connect e do Web Services Federation. A maioria dos logons do OAuth não é afetada devido a diferenças na forma como a solicitação flui. O novo parâmetro None causa problemas de compatibilidade com clientes que implementaram o padrão de rascunho anterior (por exemplo, o iOS 12). O Chrome 80 incluirá as alterações. Confira Atualizações do SameSite para a linha do tempo de lançamento do produto Chrome.

O ASP.NET Core 3.1 foi atualizado para implementar o novo comportamento de SameSite. A atualização redefine o comportamento de SameSiteMode.None para emitir SameSite=None e adiciona o novo valor SameSiteMode.Unspecified para omitir o atributo SameSite. Todas as APIs de cookie agora usam Unspecified como padrão, embora alguns componentes que usam cookies definam valores mais específicos para seus cenários, como a correlação do OpenID Connect e de cookies nonce.

Para outras alterações recentes nessa área, confira HTTP: alguns padrões de cookie do SameSite foram alterados para None. No ASP.NET Core 3.0, a maioria dos padrões foi alterada de SameSiteMode.Lax para SameSiteMode.None (mas ainda usando o padrão anterior).

Motivo da alteração

Alterações de navegador e de especificação conforme a descrição no texto anterior.

Os aplicativos que interagem com sites remotos, como por meio de logon de terceiros, precisam:

Para obter instruções de teste e de detecção de navegador, confira a seção a seguir.

Determinar se você foi afetado

Teste o aplicativo Web usando uma versão do cliente que pode aceitar o novo comportamento. O Chrome, o Firefox e o Microsoft Edge Chromium têm novos sinalizadores de recursos de aceitação que podem ser usados para teste. Verifique se o aplicativo é compatível com versões de cliente mais antigas depois de aplicar os patches, principalmente o Safari. Para obter mais informações, confira Suporte a navegadores mais antigos.

Cromar

O Chrome 78 e posterior geram resultados de teste enganosos. Essas versões têm uma mitigação temporária em vigor e permitem cookies com menos de dois minutos de duração. Com os sinalizadores de teste apropriados habilitados, o Chrome 76 e 77 geram resultados mais precisos. Para testar o novo comportamento, habilite chrome://flags/#same-site-by-default-cookies. O Chrome 75 e as versões anteriores são relatados como falhando com a nova configuração None. Para obter mais informações, confira Suporte a navegadores mais antigos.

O Google não disponibiliza versões mais antigas do Chrome. No entanto, você pode baixar versões mais antigas do Chromium, o que será suficiente para o teste. Siga as instruções em Baixar Chromium.

Safári

O Safari 12 implementou estritamente o rascunho anterior e falhará se o novo valor None estiver em cookies. Isso precisa ser evitado por meio do código de detecção de navegador mostrado em Suporte a navegadores mais antigos. Teste logons no estilo do sistema operacional Safari 12 e 13, bem como baseados em WebKit usando a MSAL (Biblioteca de Autenticação da Microsoft), a ADAL (Biblioteca de Autenticação do Active Directory) ou qualquer biblioteca que você esteja usando. O problema depende da versão subjacente do sistema operacional. Sabe-se que o OSX Mojave 10.14 e o iOS 12 têm problemas de compatibilidade com o novo comportamento. A atualização para o OSX Catalina 10.15 ou iOS 13 corrige o problema. No momento, o Safari não tem um sinalizador de aceitação para testar o novo comportamento de especificação.

Firefox

O suporte do Firefox ao novo padrão pode ser testado na versão 68 e posterior aceitando-o na página about:config com o sinalizador de recurso network.cookie.sameSite.laxByDefault. Nenhum problema de compatibilidade foi relatado em versões mais antigas do Firefox.

Microsoft Edge

Embora o Microsoft Edge dê suporte ao padrão antigo SameSite, da versão 44 em diante, ele não teve problemas de compatibilidade com o novo padrão.

Microsoft Edge Chromium

O sinalizador de recurso é edge://flags/#same-site-by-default-cookies. Nenhum problema de compatibilidade foi observado em testes com o Microsoft Edge Chromium 78.

Elétron

As versões do Electron incluem versões mais antigas do Chromium. Por exemplo, a versão do Electron usada pelo Microsoft Teams é a Chromium 66, que exibe o comportamento mais antigo. Execute seu próprio teste de compatibilidade com a versão do Electron que o seu produto usa. Para obter mais informações, confira Suporte a navegadores mais antigos.

Suporte a navegadores mais antigos

O padrão SameSite de 2016 determina que valores desconhecidos sejam tratados como valores SameSite=Strict. Consequentemente, todos os navegadores mais antigos que dão suporte ao padrão original podem ser interrompidos quando veem uma propriedade SameSite com o valor None. A detecção de navegador precisa ser implementada nos aplicativos Web quando o objetivo é dar suporte a esses navegadores antigos. O ASP.NET Core não implementa a detecção de navegador, pois os valores de cabeçalho de solicitação User-Agent são altamente instáveis e são alterados semanalmente. Nesse caso, um ponto de extensão na política de cookie permite adicionar uma lógica específica do User-Agent.

No Startup.cs, adicione as seguintes instruções:

private void CheckSameSite(HttpContext httpContext, CookieOptions options)
{
    if (options.SameSite == SameSiteMode.None)
    {
        var userAgent = httpContext.Request.Headers["User-Agent"].ToString();
        // TODO: Use your User Agent library of choice here.
        if (/* UserAgent doesn't support new behavior */)
        {
            options.SameSite = SameSiteMode.Unspecified;
        }
    }
}

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<CookiePolicyOptions>(options =>
    {
        options.MinimumSameSitePolicy = SameSiteMode.Unspecified;
        options.OnAppendCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
        options.OnDeleteCookie = cookieContext =>
            CheckSameSite(cookieContext.Context, cookieContext.CookieOptions);
    });
}

public void Configure(IApplicationBuilder app)
{
    // Before UseAuthentication or anything else that writes cookies.
    app.UseCookiePolicy();

    app.UseAuthentication();
    // code omitted for brevity
}
Opções de recusa

A opção de compatibilidade Microsoft.AspNetCore.SuppressSameSiteNone permite que você recuse temporariamente o novo comportamento de cookie do ASP.NET Core. Adicione o seguinte JSON a um arquivo runtimeconfig.template.json no projeto:

{
  "configProperties": {
    "Microsoft.AspNetCore.SuppressSameSiteNone": "true"
  }
}
Outras versões

Em breve haverá patches relacionados ao SameSite:

  • ASP.NET Core 2.1, 2.2 e 3.0
  • Microsoft.Owin 4.1
  • System.Web (para .NET Framework 4.7.2 e versões posteriores)

Categoria

ASP.NET

APIs afetadas

ASP.NET Core 3.0

As APIs antifalsificação, de CORS, de diagnóstico, MVC e de roteamento obsoletas foram 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 Núcleo

APIs afetadas

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

tipos de

  • 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

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

O Google começou a desativar o login do Google+ para aplicativos já 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 posterior, uma mitigação temporária é descrita nos impactos de desligamento do Google+. 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 Núcleo

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 Núcleo

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 OAuth derivadas, a alteração mais comum é substituir JObject.Parse por JsonDocument.Parse na substituição CreateTicketAsync, conforme mostrado em dotnet/aspnetcore#7105. JsonDocument implementa IDisposable.

A seguinte lista descreve as alterações conhecidas:

Categoria

ASP.NET Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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:

As novas extensões IHostEnvironmentIsDevelopment e IsProduction estão no namespace Microsoft.Extensions.Hosting. Talvez esse namespace precise ser adicionado ao projeto.

Categoria

ASP.NET Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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:

  • Peneireiro
  • HttpSys
  • IIS em processo
  • Servidor de Teste

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 quaisquer implementações de IConnectionAdapter para usar o novo padrão de middleware, conforme mostrado em dotnet/aspnetcore#11412.

Categoria

ASP.NET Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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. 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 Núcleo

APIs afetadas

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

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 da depuração. Além disso, DebugLoggerProvider ainda é public quando o serviço precisa ser registrado manualmente.

Categoria

ASP.NET Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

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 Núcleo

APIs afetadas

Nenhum