Start Debugging
2026-06-07 Aktualisiert 2026-11-02 csharpdotnetdotnet-11aspnetcore Edit on GitHub

Minimal-API-Endpunkte mit MapGroup organisieren

Minimal APIs mit Ressourcen-Erweiterungsmethoden und MapGroup strukturieren: verschachtelte Routen, Metadaten, Filter, Authentifizierung und Tests.

Diese Website nutzt Walter, einen KI-Agenten, für Recherche, Texte und Pflege. Redaktion und Überprüfung

MapGroup bündelt ein Routenpräfix und Endpunktkonventionen. Die API existiert seit ASP.NET Core 7. Eine Erweiterungsmethode pro Ressource kann die Registrierung aus Program.cs auslagern, ohne Controller einzuführen.

Korrektur — 2. November 2026: Die frühere Fassung beschrieb das Zusammenfügen von Schrägstrichen fälschlich als reine Verkettung und stellte alle WebApplication-APIs als Gruppen-APIs dar. Das Ersatzbeispiel verwendet SDK 10.0.302 und ist kein .NET-11-Laufzeittest.

Ein vollständiges Ressourcenmodul

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

Die Anwendung stellt GET /api/todos/1 und PUT /api/todos/{id} bereit. Der Demonstrationsspeicher überlebt keinen Prozessneustart. Die Routenkomposition von SDK 10 verbindet /todos/ und /{id:int}, ohne /todos//{id:int} zu erzeugen. Einheitliche Schreibweise ist hilfreich; eine reine String-Verkettung erklärt das Routingverhalten jedoch nicht.

Die Endpunktklasse darf in eine andere Datei desselben Projekts verschoben werden. Die Datei allein bestimmt nicht, ob die Request-Delegate-Generierung läuft. Private Handler lassen sich nicht direkt aus einer anderen Test-Assembly aufrufen. Testen Sie über HTTP oder lagern Sie Geschäftslogik in eigenständig testbare Dienste aus.

Möglichkeiten einer Gruppe

RouteGroupBuilder implementiert IEndpointRouteBuilder und IEndpointConventionBuilder. Damit sind verschachtelte Routen und Konventionen wie WithTags, RequireAuthorization sowie Endpunktfilter möglich. Nicht die gesamte WebApplication-API ist verfügbar: Middleware mit Use... und die Host-Lebensdauer gehören zur Anwendung.

Explizite Tags steuern die OpenAPI-Gruppierung, erzeugen oder veröffentlichen aber kein Dokument. Dazu ist versionsgerechtes OpenAPI-Setup nötig. Endpunktnamen müssen anwendungsweit eindeutig sein.

Verschachtelte Präfixe werden kombiniert; Parameter einer äußeren Gruppe können an innere Handler gebunden werden. Äußere Filter umschließen innere und Endpunktfilter. Code vor await next(context) läuft zum Handler hin, Code danach in umgekehrter Reihenfolge zurück. Die Registrierungsreihenfolge innerhalb einer Gruppe bleibt relevant.

Richtlinien bewusst konfigurieren

RequireAuthorization("policy") ergänzt Metadaten. Es erstellt weder die Richtlinie noch einen Authentifizierungshandler oder Zugangsdaten. Registrieren Sie Dienste und passende Middleware. Ein Präfix /v1 allein ist ebenfalls keine vollständige API-Versionierungsstrategie.

Für Eingabeprüfungen siehe integrierte Validierung und FluentValidation. Native AOT hängt zusätzlich von Handlern, Serialisierung und Abhängigkeiten ab; beachten Sie den AOT-Leitfaden.

Quellen

Comments

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