Controllers no .NET 11: ShortCircuit, unions e validação

Como o atributo funciona na prática

O atributo pode ser aplicado na classe do controller ou em uma action específica. Quando ele está na classe, todas as actions do controller passam a ignorar o restante do pipeline.

// HealthController.cs
[ApiController]
[Route("api/health")]
[ShortCircuit]
public class HealthController(HealthCheckService healthCheckService) : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> Get(CancellationToken cancellationToken)
    {
        // Executa todos os health checks registrados
        var report = await healthCheckService.CheckHealthAsync(cancellationToken);

        var result = new
        {
            Status = report.Status.ToString(),
            Checks = report.Entries.Select(entry => new
            {
                Name = entry.Key,
                Status = entry.Value.Status.ToString()
            })
        };

        return report.Status == HealthStatus.Unhealthy
            ? StatusCode(StatusCodes.Status503ServiceUnavailable, result)
            : Ok(result);
    }
}

Para comprovar o efeito, basta registrar um middleware simples no Program.cs e observar o log.

// Program.cs
app.Use(async (context, next) =>
{
    var logger = context.RequestServices
        .GetRequiredService<ILoggerFactory>()
        .CreateLogger("Pipeline");

    // Esta linha não aparece quando o endpoint usa ShortCircuit
    logger.LogInformation("Middleware ran");

    await next(context);
});

Sem o atributo, a chamada ao Get sempre passa pelo middleware e a mensagem aparece no log. Com o atributo, o middleware não executa, e mesmo assim o endpoint devolve a resposta normalmente.

Na prática, o endpoint passa a rodar dentro do próprio middleware de roteamento. Dessa forma, tudo o que foi registrado depois do UseRouting fica de fora daquela requisição.

Status code padrão com ShortCircuit

O atributo aceita um status code opcional. Ele vale para actions que não definem o status por conta própria, como métodos void.

// HealthController.cs
[ApiController]
[Route("api/health")]
[ShortCircuit(204)]
public class ReadinessController : ControllerBase
{
    [HttpGet("app-ready")]
    public void AppReady()
    {
        // Nenhum retorno: a resposta usa o status 204 do atributo
    }
}

Como o método AppReady não devolve nada, a resposta sai com o status 204. Por outro lado, uma action que retorna Ok() continua respondendo 200, porque o status explícito prevalece.

Benefícios e restrições do ShortCircuit nos controllers no .NET 11

Pular parte do pipeline traz três benefícios diretos para os controllers no .NET 11:

• menos CPU e memória por requisição;
• nenhum middleware consegue interferir na resposta;
• health checks deixam de poluir os logs de requisição e a telemetria.

Entretanto, o recurso tem limites claros. Middlewares registrados antes do UseRouting continuam rodando, porque o atalho só acontece depois que a rota é resolvida.

Além disso, um endpoint com short circuit não pode ter metadados de autorização ou de CORS. Se a action tiver [Authorize] ou [EnableCors], a requisição falha com InvalidOperationException.

Em outras palavras, o ShortCircuit nos controllers no .NET 11 serve para endpoints públicos e simples. Ele não substitui a segurança da API, e nunca deve aparecer em uma rota que precise de autenticação.

Como declarar uma union no C# 15

Considere uma API de pagamentos que devolve um pagamento com cartão ou uma transferência bancária. Primeiro, cada formato vira um record próprio.

// CardPaymentDto.cs
public record CardPaymentDto(string Last4, decimal Amount);

// BankTransferDto.cs
public record BankTransferDto(string Reference, decimal Amount);

Em seguida, a palavra-chave union declara o tipo que os controllers no .NET 11 vão retornar.

// PaymentDto.cs
public union PaymentDto(CardPaymentDto, BankTransferDto);

A union gera conversões implícitas a partir de cada caso. Assim, a action pode atribuir qualquer um dos records diretamente a uma variável do tipo PaymentDto.

// PaymentsController.cs
[ApiController]
[Route("api/payments")]
public class PaymentsController : ControllerBase
{
    [HttpGet("{id:int}")]
    public ActionResult<PaymentDto> Get(int id)
    {
        // A conversão implícita transforma cada record em PaymentDto
        PaymentDto payment = id == 1
            ? new CardPaymentDto("4242", 49.99m)
            : new BankTransferDto("RTC-1001", 120.00m);

        return payment;
    }
}

Além disso, o compilador exige que um switch sobre a union trate todos os casos. Quando alguém adicionar um terceiro tipo de pagamento, cada switch incompleto vai gerar um aviso.

Há também uma limitação importante. Unions funcionam no corpo JSON da requisição e da resposta, mas não em route values, query strings, headers ou campos de formulário.

Union types na documentação OpenAPI

Segundo a documentação oficial, um endpoint que retorna uma union aparece no documento OpenAPI com um schema anyOf, listando cada caso. Diferente dos tipos polimórficos, os casos não carregam um discriminador $type.

Na prática, porém, o exemplo gerado pela interface de documentação pode enganar. No teste do autor do artigo original, o valor de exemplo exibia apenas as propriedades de CardPaymentDto, que é o primeiro caso da union.

{
  "last4": "string",
  "amount": 0.1
}

Ou seja, quem consome a API pela interface pode concluir que o endpoint sempre devolve um cartão. Por isso, vale documentar os dois formatos com exemplos explícitos ou revisar o schema anyOf gerado.

Quando dois casos serializam para o mesmo formato JSON, a documentação recomenda usar um classificador [JsonUnion] para diferenciá-los. Nesse caso, o cliente consegue identificar qual tipo recebeu.

Union types nas Minimal APIs

Nas Minimal APIs, a mesma union funciona sem nenhuma diferença. O handler retorna PaymentDto, e o ASP.NET Core serializa o caso que estiver dentro dela.

// PaymentsEndpoints.cs
public static class PaymentsEndpoints
{
    public static IEndpointRouteBuilder MapPaymentsEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/v2/payments");
        group.MapGet("{id:int}", GetPayment);

        return app;
    }

    public static PaymentDto GetPayment(int id)
    {
        // Mesmo comportamento do controller, com menos infraestrutura
        PaymentDto payment = id == 1
            ? new CardPaymentDto("4242", 49.99m)
            : new BankTransferDto("RTC-1001", 120.00m);

        return payment;
    }
}

Com o id igual a 1, o endpoint devolve o pagamento com cartão. Com qualquer outro valor, devolve a transferência bancária.

O atributo [ShortCircuit] também funciona nas Minimal APIs, aplicado diretamente no handler. Assim, o método ShortCircuit() e o atributo convivem sem conflito.

Criando um AsyncValidationAttribute

O caminho mais simples é herdar de AsyncValidationAttribute e sobrescrever o método IsValidAsync. Dentro dele, a regra pode consultar o banco ou chamar uma API externa sem bloquear threads.

// UniqueEmailAttribute.cs
public class UniqueEmailAttribute : AsyncValidationAttribute
{
    protected override async Task<ValidationResult?> IsValidAsync(
        object? value,
        ValidationContext context,
        CancellationToken cancellationToken)
    {
        // Resolve o serviço pelo container de injeção de dependência
        var userService = context.GetRequiredService<IUserService>();

        if (value is string email
            && await userService.EmailExistsAsync(email, cancellationToken))
        {
            return new ValidationResult("That email is already registered.");
        }

        return ValidationResult.Success;
    }

    // O método síncrono também é abstrato; lançar exceção evita que a regra seja ignorada
    protected override ValidationResult? IsValid(object? value, ValidationContext context) =>
        throw new InvalidOperationException("Validate this attribute with IsValidAsync.");
}

O método síncrono IsValid também precisa ser sobrescrito. A própria documentação sugere lançar uma exceção nele, para que a regra nunca seja pulada em silêncio por uma API síncrona.

Depois disso, o atributo entra na propriedade como qualquer outro.

// RegisterEmailRequest.cs
public class RegisterEmailRequest
{
    [Required, EmailAddress, UniqueEmail]
    public string Email { get; set; } = string.Empty;
}

Por fim, a validação é ativada com builder.Services.AddValidation() no Program.cs, e o endpoint recebe a classe como parâmetro.

// UsersEndpoints.cs
public static class UsersEndpoints
{
    public static IEndpointRouteBuilder MapUsersEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/v2/users");
        group.MapPost("/register", Register);

        return app;
    }

    public static Created Register(RegisterEmailRequest request) =>
        TypedResults.Created($"/users/{request.Email}");
}

Ao enviar um e-mail já cadastrado, o endpoint responde 400 com a mensagem da regra. Portanto, a requisição passou pelo atributo assíncrono antes de chegar ao handler.

Dois cuidados merecem atenção. Primeiro, o framework pode executar o mesmo atributo em paralelo, então a implementação precisa ser thread-safe.

Além disso, o IsValidAsync deve respeitar o CancellationToken. O framework aguarda todas as validações iniciadas, então uma regra que ignora o cancelamento atrasa a resposta de erro.

O que acontece nos controllers no .NET 11

Nos controllers no .NET 11, a mesma classe de requisição não funciona como esperado. O MVC continua usando o pipeline de validação síncrono.

// UsersController.cs
[ApiController]
[Route("api/v1/users")]
public class UsersController : ControllerBase
{
    [HttpPost("register")]
    public Created Register(RegisterEmailRequest request) =>
        TypedResults.Created($"/users/{request.Email}");
}

No teste do artigo original, o controller chamou o método IsValid síncrono do UniqueEmailAttribute. Como esse método lança exceção, a requisição falhou em vez de validar o e-mail.

Assim, quem precisa de regras assíncronas em controllers continua dependendo de bibliotecas externas ou de verificações dentro da action. Esse é, hoje, o argumento técnico mais forte para escolher Minimal APIs em projetos novos.

Criar e aplicar migration em um passo

Antes, adicionar uma migration exigia dois comandos: um para gerar e outro para atualizar o banco. Agora, a opção --add do database update faz as duas coisas.

# Package Manager Console do Visual Studio
Update-Database -Migration AddProducts -Add

# .NET CLI
dotnet ef database update AddProducts --add

O comando gera a migration, compila o código em tempo de execução com o Roslyn e aplica o resultado no banco. Ainda assim, os arquivos continuam salvos em disco para o controle de versão.

As opções --output-dir e --namespace também funcionam junto com --add. Mesmo assim, em projetos com revisão de código, gerar e revisar a migration antes de aplicar continua sendo a prática mais segura.

MinBy e MaxBy no EF Core

O EF Core 11 passou a traduzir MinBy e MaxBy para SQL. Diferente de Min e Max, esses métodos devolvem o item inteiro com o menor ou o maior valor, e não apenas o valor.

// Produto com o menor preço
var cheapest = await context.Products
    .Select(p => new { p.Id, p.Name, p.Price })
    .MinByAsync(p => p.Price);

// Produto com o maior preço
var mostExpensive = await context.Products
    .Select(p => new { p.Id, p.Name, p.Price })
    .MaxByAsync(p => p.Price);

No SQL Server, a consulta vira um SELECT TOP(1) com ORDER BY na chave escolhida. Dessa forma, o banco faz o trabalho, e a aplicação não precisa carregar a tabela inteira para descobrir o item.

Vale a pena atualizar agora?

Lançado como versão STS, o .NET 11 tem dois anos de suporte, até novembro de 2028. Já o .NET 10, por ser LTS, também tem suporte encerrado em novembro de 2028.

Ou seja, quem migra do .NET 10 para o .NET 11 não ganha tempo de suporte. Pelo contrário, assume uma atualização extra e terá de migrar de novo na mesma janela.

Por isso, a recomendação do artigo original é pragmática: manter aplicações existentes no .NET 10 e usar o .NET 11 em projetos novos. A exceção são aplicações no .NET 8 ou no .NET 9, cujo suporte termina em novembro de 2026.

Para essas aplicações, a migração deixa de ser opcional. Nesse caso, a escolha entre .NET 10 e .NET 11 depende de quanto o time valoriza os recursos novos frente ao esforço de atualizar.