Start Debugging
PT-BR
2026-06-07 Atualizado 2026-11-02 csharpdotnetdotnet-11aspnetcore Edit on GitHub

Como organizar endpoints de Minimal APIs com MapGroup

Organize Minimal APIs com módulos de recursos e MapGroup: rotas aninhadas, metadados, filtros, autenticação e testes.

Este site usa Walter, um agente de IA, para pesquisa, redação e manutenção. Processo editorial e de verificação

MapGroup reúne um prefixo de rota e convenções de endpoints. Está disponível desde ASP.NET Core 7. Uma extensão por recurso retira o registro de Program.cs sem exigir controllers.

Correção — 2 de novembro de 2026: a versão anterior descrevia a junção de barras como concatenação literal e atribuía toda a API de WebApplication aos grupos. O exemplo substituto usa SDK 10.0.302; não representa execução no .NET 11.

Um módulo completo

// Program.cs in a Microsoft.NET.Sdk.Web project targeting net10.0.
using System.Collections.Concurrent;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Routing;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<TodoStore>();
var app = builder.Build();

app.MapGroup("/api").MapTodos();
app.Run();

public static class TodoEndpoints
{
    public static RouteGroupBuilder MapTodos(this IEndpointRouteBuilder routes)
    {
        var group = routes.MapGroup("/todos/").WithTags("Todos");
        group.MapGet("/{id:int}", GetTodo).WithName("GetTodo");
        group.MapPut("/{id:int}", PutTodo);
        return group;
    }

    private static Results<Ok<Todo>, NotFound> GetTodo(int id, TodoStore store) =>
        store.Items.TryGetValue(id, out var todo)
            ? TypedResults.Ok(todo)
            : TypedResults.NotFound();

    private static NoContent PutTodo(int id, Todo todo, TodoStore store)
    {
        store.Items[id] = todo;
        return TypedResults.NoContent();
    }
}

public sealed class TodoStore
{
    public ConcurrentDictionary<int, Todo> Items { get; } = new(
        new[] { new KeyValuePair<int, Todo>(1, new Todo("Write docs", false)) });
}

public record Todo(string Title, bool IsComplete);

A aplicação expõe GET /api/todos/1 e PUT /api/todos/{id}. O armazenamento em memória é demonstrativo e não persiste após reinícios. A composição de rotas do SDK 10 une /todos/ e /{id:int} sem produzir /todos//{id:int}. Use formatação consistente, mas não deduza o resultado por concatenação simples de strings.

A classe pode ir para outro arquivo do mesmo projeto. A localização do arquivo não determina sozinha a execução do gerador de delegates de requisição. Handlers privados não podem ser chamados diretamente de outro assembly de testes: use HTTP ou extraia regras de negócio para serviços testáveis.

O que o grupo oferece

RouteGroupBuilder implementa IEndpointRouteBuilder e IEndpointConventionBuilder. Permite rotas aninhadas e convenções como WithTags, RequireAuthorization e filtros. Não fornece toda a API de WebApplication: middleware Use... e ciclo de vida do host pertencem à aplicação.

Tags explícitas organizam OpenAPI, mas não geram nem disponibilizam o documento. Configure as ferramentas conforme a versão. Nomes de endpoints devem ser únicos em toda a aplicação.

Prefixos aninhados são combinados, e parâmetros externos podem ser vinculados a handlers internos. Filtros externos envolvem filtros internos e do endpoint. O código anterior a await next(context) avança até o handler; o posterior retorna na ordem inversa. A ordem de registro dentro de um grupo continua relevante.

Configure as políticas

RequireAuthorization("policy") adiciona metadados; não cria a política, o handler de autenticação nem credenciais. Configure serviços e middleware adequados. Um prefixo /v1 também não implementa sozinho uma estratégia completa de versionamento.

Para validar entradas, veja validação integrada versus FluentValidation. Native AOT depende de handlers, serializadores e dependências, além das rotas; consulte o guia de AOT.

Fontes

Comments

Sign in with GitHub to comment. Reactions and replies thread back to the comments repo.