C# / .NET Kompendium PLEN
.NET / C# / Web API, Blazor

Endpoint Routing w ASP.NET Core

Problem, który rozwiązuje - rozdzielenie "dopasowania trasy" od "wykonania"

W starszym modelu (klasyczny middleware routing) dopasowanie URL do logiki działo się w jednym miejscu, blisko samej logiki obsługi. Endpoint Routing (domyślny od ASP.NET Core 3.0) rozdziela to na dwa oddzielne kroki w pipeline:

var app = builder.Build();

app.UseRouting();      // KROK 1: dopasuj URL do endpointu (ale jeszcze NIE wykonuj)
app.UseAuthentication();
app.UseAuthorization(); // działa TU, bo już WIE który endpoint został dopasowany (i jego metadane)
app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
    endpoints.MapGet("/health", () => "OK");
});          // KROK 2: dopiero TU faktycznie wykonaj dopasowany endpoint

Dlaczego to jest ważne - metadane dostępne WCZEŚNIEJ w pipeline

Kluczowa zaleta: middleware między UseRouting() i UseEndpoints() wie już, jaki endpoint zostanie wywołany, i może odczytać jego metadane (atrybuty typu [Authorize], [AllowAnonymous]), zanim faktycznie do niego dojdzie:

[Authorize(Roles = "Admin")]
[HttpGet("admin/reports")]
public IActionResult GetReports() => Ok();

UseAuthorization() middleware, działając po UseRouting(), ale przed UseEndpoints(), widzi atrybut [Authorize(Roles = "Admin")] na dopasowanym endpoincie bez jego wykonywania - może odrzucić request (403) zanim jakikolwiek kod kontrolera się wykona. W starym modelu (bez rozdzielenia) taka kontrola musiałaby być wpisana w każdą akcję ręcznie albo middleware musiałby "zgadywać" co się stanie.

Endpoint jako obiekt pierwszej klasy

app.Use(async (context, next) =>
{
    var endpoint = context.GetEndpoint(); // dostępny PO UseRouting(), przed wykonaniem
    if (endpoint != null)
    {
        Console.WriteLine($"Dopasowano endpoint: {endpoint.DisplayName}");
    }
    await next();
});

Endpoint Routing reprezentuje dopasowaną trasę jako obiekt (Endpoint) z metadanymi, dostępny przez HttpContext.GetEndpoint() - to jest fundament, na którym stoi Minimal API, routing w Blazor, gRPC i SignalR w ASP.NET Core - wszystkie używają tego samego, wspólnego mechanizmu, zamiast każdy mieć swój.

Minimal API - routing bez kontrolerów

app.MapGet("/orders/{id}", (int id, IOrderService service) => service.GetOrder(id));
app.MapPost("/orders", (CreateOrderRequest req, IOrderService service) => service.CreateOrder(req));

To jest ten sam Endpoint Routing "pod spodem" - MapGet/MapPost rejestrują endpoint z takimi samymi metadanymi i takim samym mechanizmem dopasowania jak [HttpGet] w kontrolerze.

Route constraints i priorytetyzacja

app.MapGet("/orders/{id:int}", (int id) => $"Zamówienie {id}");        // TYLKO liczba całkowita
app.MapGet("/orders/{id:guid}", (Guid id) => $"Zamówienie {id}");       // TYLKO GUID
app.MapGet("/orders/search", () => "wyszukiwanie");                     // bardziej SPECYFICZNY - wygrywa

Endpoint Routing sam ustala priorytet dopasowania na podstawie specyficzności trasy (literalny segment search wygrywa z parametrem {id}), bez potrzeby ręcznego ustawiania kolejności rejestracji, jak to bywało konieczne w starszych systemach routingu.

Pełny przykład w Web API - jak to się składa w praktyce

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddAuthentication(/* ... */);
builder.Services.AddAuthorization();
builder.Services.AddScoped<IOrderService, OrderService>();

var app = builder.Build();

app.UseRouting();               // (1) dopasowanie trasy

app.Use(async (context, next) =>
{
    var endpoint = context.GetEndpoint();
    var requiresAuth = endpoint?.Metadata.GetMetadata<IAuthorizeData>() != null;
    Console.WriteLine($"{context.Request.Path} -> wymaga auth: {requiresAuth}");
    await next();
});                              // (2) własny middleware, WIDZI już metadane endpointu

app.UseAuthentication();
app.UseAuthorization();         // (3) blokuje request, jeśli [Authorize] nie jest spełnione

app.UseEndpoints(endpoints =>   // (4) dopiero TU faktyczne wykonanie
{
    endpoints.MapControllers();

    endpoints.MapGet("/orders/{id:int}", async (int id, IOrderService service) =>
    {
        var order = await service.GetOrderAsync(id);
        return order != null ? Results.Ok(order) : Results.NotFound();
    });
});

app.Run();

Ten przykład pokazuje pełny sens rozdzielenia: własny middleware logujący (2) i UseAuthorization() (3) oba korzystają z tego, że endpoint został już dopasowany w kroku (1), zanim jego kod faktycznie się wykona w kroku (4) - niezależnie czy to kontroler (MapControllers()) czy Minimal API (MapGet).

Podsumowanie

Endpoint Routing rozdziela dopasowanie trasy (UseRouting()) od jej wykonania (UseEndpoints()/mapowania), udostępniając middleware'owi w tym przedziale metadane dopasowanego endpointu (przez HttpContext.GetEndpoint()) - to jest mechanizm, na którym opiera się UseAuthorization() (blokowanie na podstawie [Authorize] przed wykonaniem kodu), a także wspólny fundament dla kontrolerów, Minimal API, Blazor, gRPC i SignalR w ASP.NET Core.

Postaw mi kawę