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 (przezHttpContext.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.