Route-Gruppen, Parameter und Validierung
Organisieren Sie Endpunkte mit MapGroup, binden Sie Route-, Query- und Body-Parameter und validieren Sie sie mit Data Annotations.
Route-Gruppen, Parameter und Validierung ist eine kostenlose C# Academy-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des C# Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der C# Academy-Kurs umfasst insgesamt 4 Lektionen.
Routengruppen zur Organisation
Mit MapGroup() (eingeführt in .NET 7) können Sie verwandte Endpunkte unter einem gemeinsamen Präfix gruppieren und gemeinsame Konfigurationen – Middleware, Authentifizierungsrichtlinien und Tags – anwenden, ohne sie für jeden Endpunkt zu wiederholen.
Eine Routengruppe erstellen
Rufen Sie app.MapGroup("/api/products") auf und ordnen Sie anschließend Endpunkte der zurückgegebenen Gruppe zu. Das Präfix wird automatisch allen Routen vorangestellt.
var products = app.MapGroup("/api/products").WithTags("Products");
products.MapGet("/", GetAll);
products.MapGet("/{id}", GetById);
products.MapPost("/", Create);
products.MapPut("/{id}", Update);
products.MapDelete("/{id}", Delete);
// Routes: /api/products, /api/products/{id}Authentifizierung auf eine Gruppe anwenden
Verwenden Sie RequireAuthorization() für die Gruppe, um alle Endpunkte gleichzeitig zu schützen. Einzelne Endpunkte können dies weiterhin mit AllowAnonymous() überschreiben.
var adminGroup = app.MapGroup("/admin")
.RequireAuthorization("AdminPolicy")
.WithTags("Admin");
adminGroup.MapGet("/users", GetAllUsers);
adminGroup.MapDelete("/users/{id}", DeleteUser);
// This one inside the group opts out
adminGroup.MapGet("/status", () => "OK").AllowAnonymous();Einschränkungen von Routenparametern
Schränken Sie Routenparameter mithilfe von Typmustern ein. Der Router weist Anfragen zurück, die nicht übereinstimmen, und liefert automatisch den Statuscode 404 zurück.
// Only matches numeric IDs
app.MapGet("/products/{id:int}", (int id) => id);
// GUID constraint
app.MapGet("/orders/{orderId:guid}", (Guid orderId) => orderId);
// Length constraint
app.MapGet("/codes/{code:length(6)}", (string code) => code);
// Min value
app.MapGet("/page/{page:min(1)}", (int page) => page);Binden aus verschiedenen Quellen
Parameter werden mithilfe von Attributen aus verschiedenen Quellen gebunden. Standardmäßig stammen einfache Typen aus Route oder Query und komplexe Typen aus dem Body.
app.MapPost("/search", (
[FromQuery] string q,
[FromQuery] int page,
[FromHeader(Name = "X-Api-Version")] string version,
[FromBody] SearchFilters filters,
AppDbContext db) =>
{
// q and page from query string
// version from request header
// filters from JSON body
return Results.Ok();
});Benutzerdefinierte Parameterbindung mit TryParse
Für benutzerdefinierte Typen, die als Routen- oder Query-Parameter verwendet werden, implementieren Sie eine statische TryParse-Methode. Das Framework ruft sie automatisch auf, um den Zeichenfolgenwert zu analysieren.
public record ProductFilter(string? Category, decimal? MinPrice)
{
public static bool TryParse(string value, out ProductFilter result)
{
var parts = value.Split(':');
result = new ProductFilter(
parts.Length > 0 ? parts[0] : null,
parts.Length > 1 && decimal.TryParse(parts[1], out var p) ? p : null);
return true;
}
}
// Usage: GET /products?filter=Electronics:50
app.MapGet("/products", ([FromQuery] ProductFilter filter) => filter);Validierung mit Data Annotations
Versehen Sie Ihre Request-DTOs mit Data-Annotations-Attributen. Verwenden Sie in Minimal APIs die Schnittstelle IValidatableObject oder einen Validierungsfilter, um die Validierung auszulösen.
using System.ComponentModel.DataAnnotations;
record CreateProductRequest
{
[Required, MaxLength(200)]
public string Name { get; init; } = "";
[Range(0.01, 999999)]
public decimal Price { get; init; }
[Range(0, int.MaxValue)]
public int Stock { get; init; }
}Endpoint-Filter zur Validierung
Endpunktfilter werden vor oder nach dem Handler ausgeführt. Verwenden Sie sie, um eine Modellvalidierung hinzuzufügen und ungültige Anfragen zurückzuweisen, bevor sie Ihre Geschäftslogik erreichen.
app.MapPost("/products", CreateProduct)
.AddEndpointFilter(async (ctx, next) =>
{
var req = ctx.GetArgument<CreateProductRequest>(0);
var errors = new List<ValidationResult>();
if (!Validator.TryValidateObject(req,
new ValidationContext(req), errors, true))
{
return Results.ValidationProblem(
errors.ToDictionary(e => e.MemberNames.First(),
e => new[] { e.ErrorMessage! }));
}
return await next(ctx);
});Integration von FluentValidation
Für komplexe Validierungsregeln können Sie FluentValidation zusammen mit dem Paket SharpGrip.FluentValidation.AutoValidation.Endpoints für eine automatische Validierung in Minimal APIs verwenden.
public class CreateProductValidator : AbstractValidator<CreateProductRequest>
{
public CreateProductValidator()
{
RuleFor(x => x.Name).NotEmpty().MaximumLength(200);
RuleFor(x => x.Price).GreaterThan(0);
RuleFor(x => x.Stock).GreaterThanOrEqualTo(0);
}
}
builder.Services.AddFluentValidationAutoValidation();
builder.Services.AddValidatorsFromAssemblyContaining<CreateProductValidator>();Verschachtelte Routengruppen
Routengruppen können verschachtelt werden, um hierarchische Ressourcen abzubilden, beispielsweise Bestellungen mit zugehörigen Bestellpositionen.
var api = app.MapGroup("/api").RequireAuthorization();
var orders = api.MapGroup("/orders");
orders.MapGet("/", GetAllOrders);
orders.MapGet("/{id:int}", GetOrder);
// Nested: /api/orders/{orderId}/lines
var lines = orders.MapGroup("/{orderId:int}/lines");
lines.MapGet("/", GetOrderLines);
lines.MapPost("/", AddOrderLine);
lines.MapDelete("/{id}", RemoveOrderLine);Praxisbeispiel: Versionierte API-Gruppe
Gruppieren Sie Endpunkte nach API-Version, um die Versionen parallel zu unterstützen, ohne die Konfiguration von Authentifizierung oder Tags zu duplizieren.
var v1 = app.MapGroup("/api/v1")
.RequireAuthorization()
.WithTags("v1");
var v2 = app.MapGroup("/api/v2")
.RequireAuthorization()
.WithTags("v2");
v1.MapGet("/products", GetProductsV1);
v2.MapGet("/products", GetProductsV2); // richer responseKurzer Check
Welchen Zweck erfüllt MapGroup() in Minimal APIs?
Zusammenfassung: Routengruppen, Parameter und Validierung
Wichtige Erkenntnisse:
MapGroup(): gemeinsames Präfix und gemeinsame Konfiguration für mehrere Endpunkte- Routenbeschränkungen (
:int,:guid,:min) weisen nicht übereinstimmende Routen automatisch zurück [FromQuery],[FromHeader],[FromBody]für eine explizite Bindungsquelle- Implementieren Sie
TryParsefür benutzerdefinierte Typen, um die automatische Routen-/Query-Bindung zu ermöglichen - Endpunktfilter ermöglichen querschnittliche Belange wie Validierung
Häufig gestellte Fragen
Ist die Lektion „Route-Gruppen, Parameter und Validierung“ kostenlos?
Ja — der vollständige Text von „Route-Gruppen, Parameter und Validierung“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des C# Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der C# Academy-Kurs umfasst insgesamt 4 Lektionen.
Was lerne ich in „Route-Gruppen, Parameter und Validierung“?
Organisieren Sie Endpunkte mit MapGroup, binden Sie Route-, Query- und Body-Parameter und validieren Sie sie mit Data Annotations. Du übst C# Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.
Brauche ich Erfahrung, um C# Academy zu starten?
Keine Vorkenntnisse erforderlich. C# Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.
Wie lange dauert die Lektion „Route-Gruppen, Parameter und Validierung“?
Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.
Kann ich in dieser C# Academy-Lektion Code schreiben und ausführen?
Ja. Jede C# Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.
Alle Lektionen in diesem Kurs
- Ihre erste Minimal API erstellen
- Route-Gruppen, Parameter und Validierung
- Middleware und Filter in Minimal APIs
- OpenAPI, Versionierung und Deployment