Start Debugging
JA
2026-06-07 更新日 2026-11-02 csharpdotnetdotnet-11aspnetcore Edit on GitHub

MapGroup で Minimal API のエンドポイントを整理する

リソース別の拡張メソッドと MapGroup で Minimal API を整理。入れ子のルート、メタデータ、フィルター、認証、テストを説明。

このサイトでは、AI エージェントの Walter を調査、執筆、保守に使用しています。 制作と検証の方法

MapGroup はルートの共通プレフィックスとエンドポイント規約をまとめます。ASP.NET Core 7 から利用できます。リソースごとの拡張メソッドにすると、コントローラーを導入せず Program.cs からルート登録を切り出せます。

訂正 — 2026 年 11 月 2 日: 以前の版はスラッシュの結合を単純な文字列連結と説明し、WebApplication の全 API をグループで使えるとしていました。修正例は SDK 10.0.302 を使用し、.NET 11 の実行確認を示すものではありません。

完全なリソースモジュール

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

GET /api/todos/1 と PUT /api/todos/{id} を提供します。メモリ内ストアはデモ用で、再起動後には残りません。SDK 10 のルート合成では /todos/ と /{id:int} を結合しても /todos//{id:int} にはなりません。表記は統一すべきですが、文字列連結だけでルートを判断しないでください。

クラスは同じプロジェクトの別ファイルに移せます。ファイル位置だけでリクエストデリゲート生成の実行が決まるわけではありません。private ハンドラーを別のテストアセンブリから直接呼ぶことはできないため、HTTP 経由でテストするか、業務処理を独立したサービスに分けます。

グループが提供する機能

RouteGroupBuilder は IEndpointRouteBuilder と IEndpointConventionBuilder を実装し、ルートの入れ子や WithTags、RequireAuthorization、フィルターを扱います。WebApplication の全 API ではありません。Use... ミドルウェアやホストの寿命はアプリケーション側で扱います。

明示的なタグは OpenAPI の分類を制御しますが、ドキュメントを生成・公開しません。バージョンに応じて別途設定します。エンドポイント名はアプリケーション全体で一意にします。

入れ子のプレフィックスは合成され、外側のルート引数を内側のハンドラーにバインドできます。外側のフィルターが内側やエンドポイントのフィルターを包みます。await next(context) より前はハンドラーに向かう順、後は逆順です。同一グループ内の登録順も重要です。

ポリシーを設定する

RequireAuthorization("policy") はメタデータを追加するだけで、ポリシー、認証ハンドラー、資格情報を作成しません。適切なサービスとミドルウェアを設定します。/v1 というプレフィックスも、それだけで完全な API バージョニングにはなりません。

入力検証は組み込み検証と FluentValidation の比較を参照してください。Native AOT はルートの整理だけでなくハンドラー、シリアライザー、依存関係にも左右されるため、AOT ガイドを確認してください。

出典

Comments

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