ASP.NET Core no .NET 11 traz union types em JSON, validação assíncrona e OpenAPI 3.2 por padrão
A versão do ASP.NET Core que acompanha o .NET 11 muda como union types do C# 15 aparecem no corpo de requisições e respostas, acelera a validação de Minimal APIs e passa a gerar OpenAPI 3.2 por padrão. Veja o que isso significa para quem mantém API em produção.
Quem mantém uma API em ASP.NET Core vai encontrar, ao atualizar o projeto para o .NET 11, pelo menos quatro mudanças que afetam código que já está em produção: union types do C# 15 aceitos em corpos JSON, validação assíncrona em Minimal APIs, OpenAPI 3.2 como padrão na geração de documentos e um pacote experimental de componentes de IA para Blazor. A Microsoft publicou o lançamento na semana anterior a 19 de novembro de 2026, como uma versão Standard Term Support (STS), com dois anos de suporte. Este texto percorre cada mudança e aponta o que precisa ser conferido antes de atualizar um projeto existente.
Union types em JSON: o que muda no corpo das rotas
Minimal APIs e MVC agora aceitam union types do C# 15 diretamente em corpos de requisição e resposta em JSON. Na prática, um endpoint pode declarar que devolve um entre dois tipos possíveis e deixar que o framework resolva qual deles serializar, sem precisar de um wrapper manual:
// Program.cs — ASP.NET Core no .NET 11
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapPost("/orders", (CreateOrderRequest | UpdateOrderRequest request, OrderStore store) =>
{
// o model binder decide qual dos dois tipos desserializar
// a partir do formato do JSON recebido no corpo
return request switch
{
CreateOrderRequest create => Results.Created($"/orders/{store.Add(create)}", create),
UpdateOrderRequest update => store.Update(update) ? Results.NoContent() : Results.NotFound(),
_ => Results.BadRequest()
};
});
app.Run();A limitação importa: o recurso vale só para o corpo da requisição em JSON. Rota, query string, header e campos de formulário continuam sem suporte a binding para um union type, então quem tenta aplicar o mesmo padrão num parâmetro [FromQuery] vai bater numa parede. Para quem documenta a API, o gerador de OpenAPI já sabe lidar com isso: ele emite um schema anyOf para o union, então o contrato publicado mostra as duas formas possíveis do corpo sem gambiarra manual no arquivo de especificação.
Validação assíncrona e o atributo ShortCircuit
Até aqui, um IValidatableObject que precisasse consultar o banco para checar, por exemplo, se um e-mail já está cadastrado, tinha que fazer essa chamada de forma síncrona dentro do pipeline de validação. No .NET 11, Minimal APIs passam a rodar validadores assíncronos, o que libera a thread enquanto a regra espera uma consulta ao banco ou uma chamada remota responder.
Duas mudanças acompanham esse ajuste:
- o framework agora consegue localizar mensagens de validação e nomes de exibição sem código adicional do time;
- o novo atributo
[ShortCircuit]permite que um endpoint pule o restante do pipeline de middlewares quando uma condição for satisfeita.
Para quem tem uma API com validação pesada de regra de negócio (checar estoque, saldo, duplicidade), vale revisar os validadores existentes: trocar a versão síncrona por uma assíncrona reduz o tempo de thread bloqueada sob carga, sem mudar o contrato da API.
OpenAPI 3.2 por padrão: o que isso documenta e o que quebra
Gerar documentação OpenAPI no ASP.NET Core agora produz a versão 3.2 por padrão, em vez de 3.0. Quem precisa manter compatibilidade com uma ferramenta de terceiros que ainda não lê 3.2 pode fixar a versão anterior ao registrar o gerador:
builder.Services.AddOpenApi(options =>
{
options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
});A mudança depende da biblioteca Microsoft.OpenApi 3.3.1, e as notas de lançamento classificam essa atualização como breaking change: quem usa a biblioteca diretamente, fora do pipeline padrão do ASP.NET Core, precisa revisar o próprio código antes de atualizar.
Com a versão 3.2, o documento gerado passa a cobrir cenários que antes ficavam incompletos:
| Recurso | Antes (3.0) | Agora (3.2) |
|---|---|---|
| Endpoints com server-sent events | Sem schema por evento | Schema documentado para cada payload de evento |
| Union types | Sem representação nativa | Schema anyOf gerado automaticamente |
| Método HTTP QUERY | Não suportado no documento | Descrito normalmente |
Atributo [Obsolete] | Ignorado na geração | Endpoint marcado como deprecated |
Para times que consomem a própria API com um cliente gerado a partir do OpenAPI (NSwag, Kiota, openapi-generator), vale regenerar o cliente depois de atualizar, porque o schema mudou de forma, mesmo quando o contrato da API continua o mesmo.
Blazor: cache, formulários estáticos e o pacote experimental de IA
A lista de mudanças no Blazor é a maior do release, e boa parte mira renderização estática no servidor. O novo componente CacheView guarda o markup já renderizado de uma subárvore de componentes, e os componentes filhos não rodam de novo quando uma cópia em cache é servida, o que ajuda páginas com conteúdo repetitivo (menu, rodapé, cartão de produto) a responder mais rápido sob carga.
Formulários em modo estático (SSR) ganham validação no lado do cliente habilitada por padrão, e o template padrão do Blazor Web App removeu a chamada explícita a app.UseAntiforgery(), porque o middleware de proteção contra CSRF agora é adicionado automaticamente. Quem copiou o template antigo como base de um projeto maior deve conferir se não há uma chamada duplicada ou um middleware customizado que dependia da ordem anterior.
Três ajustes menores merecem atenção em projetos com listas grandes:
Virtualizeagora aceita itens de alturas diferentes na mesma lista, e oOverscanCountpadrão subiu de 3 para 15;- estado de página e ordenação do
QuickGridpassou a viver na query string da URL, com cabeçalhos e paginação renderizados como links em vez de botões, o que as notas de lançamento marcam como breaking change de CSS: estilo escrito parabuttonprecisa ser reescrito paraa; - para apps Interactive Server, um pacote opcional pausa o circuito de uma aba de navegador oculta depois de um tempo (dois minutos por padrão), liberando memória no servidor.
O pacote Microsoft.AspNetCore.Components.AI chega como experimental, com componentes prontos para interface de chat e de agente. A Microsoft deixou claro que vai manter o pacote em prerelease durante todo o ciclo do .NET 11, então não é recomendação para produção ainda, mas já dá para montar um protótipo de atendimento ou copiloto interno sem escrever a interface de chat do zero.
Checklist antes de atualizar
Além do que já foi citado, três mudanças pedem atenção extra na hora de migrar um projeto:
- o pacote
Microsoft.AspNetCore.Grpc.Swaggerestá obsoleto; quem documenta serviço gRPC com Swagger precisa planejar a troca; - a opção
TlsClientHelloBytesCallbackdo Kestrel foi marcada como obsoleta em favor da nova extensãoUseTlsClientHelloListener; - o parser HTTP/1.1 do Kestrel deixou de lançar exceção em requisições malformadas, mudança que a Microsoft relata elevar a vazão em até 20% a 40% sob tráfego pesado de requisições inválidas.
O release também trouxe SignalR com renovação de autenticação durante a conexão (o circuito não precisa mais cair quando o token de acesso expira), suporte a Zstandard em compressão e descompressão habilitado por padrão, e um pacote experimental de Device Bound Session Credentials, protocolo que amarra a renovação de sessão a uma chave privada guardada pelo navegador.
Próximo passo
Para quem decide atualizar um serviço em produção, o caminho prático é isolar as três mudanças com maior chance de quebrar algo: a atualização do Microsoft.OpenApi para 3.3.1, o CSS do QuickGrid e o template do Blazor Web App sem UseAntiforgery() explícito. As notas completas de "What's new in ASP.NET Core in .NET 11", no Microsoft Learn, trazem a lista integral das mudanças citadas aqui.
Fonte: InfoQ
Este artigo foi escrito por Letícia Amaral. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.
Editora virtual de Fundamentos do Linha de Código. Explica o conceito uma vez e mostra em mais de uma linguagem: lógica, algoritmos, estruturas de dados, orientação a objetos, Git, testes, HTTP e arquitetura. É a porta de entrada de quem está aprendendo a programar e a referência de quem precisa lembrar como se resolve.