3. Das Action-Modell
Eine Action benötigt Informationen, die der Browser sendet: die Parameter der URL ([?name=martin&age=42]), Formularfelder und Routenparameter. Der Quellkurs bezeichnet all diese Informationen als Action-Modell. Dieses Kapitel zeigt, wie [ASP.NET Core] diese Informationen an die Action übergibt, in den richtigen Typ konvertiert und validiert. Dieser Vorgang heißt Model Binding ([model binding]).
3.1. Beispiel 07: URL-Parameter
Die Datei [Controllers/ParametersController.cs]:
| using Microsoft.AspNetCore.Mvc;
namespace Example07.Controllers;
[Route("parameters")]
public class ParametersController : Controller
{
// /parameters/action01?name=martin: der URL-Parameter [name] -> der Action-Parameter [name]
[HttpGet("action01")]
public string Action01(string? name)
{
return $"name = [{name}], of type {name?.GetType().Name ?? "null"}";
}
// /parameters/action02?age=42: der Wert wird in den Parametertyp KONVERTIERT
[HttpGet("action02")]
public string Action02(int age)
{
return $"age = [{age}], of type {age.GetType().Name}, ModelState.IsValid = {ModelState.IsValid}";
}
// /parameters/action03?age=42: int? unterscheidet einen fehlenden Parameter (null) von einer Null
[HttpGet("action03")]
public string Action03(int? age)
{
return $"age = [{age?.ToString() ?? "null"}], ModelState.IsValid = {ModelState.IsValid}";
}
// /parameters/action04?page=2: ein Standardwert, falls der Parameter fehlt
[HttpGet("action04")]
public string Action04(int page = 1)
{
return $"page = [{page}]";
}
// /parameters/action05?q=nest: [FromQuery(Name = ...)], wenn die Namen verschieden sind
[HttpGet("action05")]
public string Action05([FromQuery(Name = "q")] string? search)
{
return $"search = [{search}]";
}
// /parameters/action06?name=martin&age=42: alle Parameter auf einmal
[HttpGet("action06")]
public Dictionary<string, string> Action06()
{
return Request.Query.ToDictionary(p => p.Key, p => p.Value.ToString());
}
}
|
Gehen wir diesen Code durch:
- Zeilen 10–12: Das Model Binding ordnet die Parameter der Action den Daten der Anfrage nach Namen zu: Der Parameter [name] der Action erhält den Wert des Parameters [name] aus der URL (dem Teil nach dem [?], der Query-String oder [query string] genannt wird). Der Typ [string?] zeigt an, dass der Wert fehlen kann; in diesem Fall ist er [null]. [name?.GetType().Name ?? "null"]: der Name des Werttyps oder die Zeichenkette ["null"] , wenn der Wert [null] ist (der Operator [??] liefert einen Ersatzwert);
- Zeilen 17–19: Der Parameter ist als Typ [int] deklariert: Das Model Binding konvertiert die empfangene Zeichenkette (["42"]) in eine Zahl. Schlägt die Konvertierung fehl ([?age=abc]), wird die Action dennoch mit dem Standardwert des Typs ausgeführt (0 für einen [int]), und der Fehler wird in [ModelState] festgehalten; der Status des Model Bindings – [ModelState.IsValid] – wird dann zu [false];
- Zeilen 24–26: Beim Typ [int?] (einer „nullable“ ganzen Zahl) wird ein fehlender Parameter als [null] dargestellt, nicht als 0: So lässt sich „kein Alter“ von „Alter 0“ unterscheiden;
- Zeilen 31–33: Ein [C#] -Standardwert ersetzt einen fehlenden Parameter;
- Zeilen 38–40: Das Attribut [[FromQuery(Name = "q")]] legt fest, wo der Wert zu suchen ist (in der URL) und unter welchem Namen: Der Parameter [search] der Action erhält den Parameter [q] aus der URL;
- Zeilen 45–47: [Request.Query] bietet Zugriff auf alle URL-Parameter, ohne Zuordnung oder Konvertierung. [ToDictionary] ([LINQ]) erzeugt daraus ein Dictionary, das in JSON serialisiert wird.
Die Ergebnisse:
| curl -i "http://localhost:5000/parameters/action01?name=martin"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
name = [martin], of type String
|
| curl -i "http://localhost:5000/parameters/action01"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
name = [], of type null
|
| curl -i "http://localhost:5000/parameters/action02?age=42"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
age = [42], of type Int32, ModelState.IsValid = True
|
| curl -i "http://localhost:5000/parameters/action02?age=abc"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
age = [0], of type Int32, ModelState.IsValid = False
|
| curl -i "http://localhost:5000/parameters/action02"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
age = [0], of type Int32, ModelState.IsValid = True
|
| curl -i "http://localhost:5000/parameters/action03?age=42"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
age = [42], ModelState.IsValid = True
|
| curl -i "http://localhost:5000/parameters/action03"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
age = [null], ModelState.IsValid = True
|
| curl -i "http://localhost:5000/parameters/action03?age=abc"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
age = [null], ModelState.IsValid = False
|
| curl -i "http://localhost:5000/parameters/action04"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
page = [1]
|
| curl -i "http://localhost:5000/parameters/action04?page=2"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
page = [2]
|
| curl -i "http://localhost:5000/parameters/action05?q=aspnet"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
search = [aspnet]
|
| curl -i "http://localhost:5000/parameters/action06?name=martin&age=42"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"name":"martin","age":"42"}
|
Die Anführungszeichen um die URL sind erforderlich, wenn sie das Zeichen [&] enthält, das für die Konsole eine besondere Bedeutung hat. Beachten Sie Folgendes:
- Ein Parameter wird unabhängig von der Groß- und Kleinschreibung über seinen Namen gebunden ([?NAME=martin] ist ebenfalls gültig);
- sein Wert wird konvertiert, und zwar in den deklarierten Typ. Das ist ein wichtiger Unterschied zu [NestJS], wo der Typ eines Parameters lediglich eine Deklaration war ([TypeScript]), die zur Kompilierzeit entfernt wurde;
- Eine nicht mögliche Konvertierung verursacht keinen Fehler: Die Action wird mit einem Standardwert ausgeführt, und es ist Sache der Action, [ModelState.IsValid] zu prüfen. Ein „nullable“ Typ ([int?]) verhindert, dass ein fehlender oder ungültiger Wert mit 0 verwechselt wird.
Akzentuierte Zeichen und Leerzeichen werden in einer URL codiert ([%C3%A9] für [é] usw.): [ASP.NET Core] decodiert sie vor dem Binding.

3.2. Beispiel 08: Ein durch eine Klasse beschriebenes Action-Modell
Wenn eine Action mehrere Parameter hat, werden sie durch eine Klasse beschrieben. Jede Eigenschaft der Klasse trägt Validierungsattribute aus dem Standard-Namespace [System.ComponentModel.DataAnnotations]. Das entspricht den Dekoratoren der Bibliothek [class-validator] von [NestJS].
Die Datei [Models/PersonModel.cs]:
| using System.ComponentModel.DataAnnotations;
namespace Example08.Models;
// das Action-Modell: eine Klasse, deren Eigenschaften jeweils ihre Einschränkungen tragen
public class PersonModel
{
[Required(ErrorMessage = "the name is required")]
[StringLength(20, MinimumLength = 2, ErrorMessage = "the name must have 2 to 20 characters")]
public string? Name { get; set; }
[Required(ErrorMessage = "the age is required")]
[Range(0, 150, ErrorMessage = "the age must be between 0 and 150")]
public int? Age { get; set; }
[Required(ErrorMessage = "the title is required")]
[AllowedValues("Mr", "Mme", "Melle", ErrorMessage = "unknown title")]
public string? Title { get; set; }
// optional: kein [Required]
[EmailAddress(ErrorMessage = "invalid email address")]
public string? Email { get; set; }
}
|
Kommentieren wir diesen Code:
- Zeile 1: der Namespace der Validierungsattribute;
- Zeile 10: Jeder erwartete Parameter ist eine öffentliche Eigenschaft ([{ get; set; }]: Sie kann gelesen und geschrieben werden). Das Model Binding erstellt ein [PersonModel]-Objekt und füllt dann jede Eigenschaft mit dem gleichnamigen Parameter;
- Zeilen 8–9: Der Name ist erforderlich ([[Required]]) und muss zwischen 2 und 20 Zeichen lang sein ([[StringLength]]). Jedes Attribut akzeptiert eine benutzerdefinierte Fehlermeldung ([ErrorMessage]). Die Eigenschaften werden als „nullable“ deklariert ([string?], [int?]): Ein Parameter kann in einer Anfrage fehlen, und [[Required]] erzwingt diese Anforderung;
- Zeilen 12–14: Das Alter wird in eine ganze Zahl konvertiert, die erforderlich ist und zwischen 0 und 150 liegen muss ([[Range]]);
- Zeile 17: Die Anrede muss zu einer Liste von Werten gehören ([[AllowedValues]], eingeführt mit [.NET] 8);
- Zeile 21: Die E-Mail-Adresse ist optional (kein [[Required]]); wenn sie angegeben wird, muss sie gültig sein.
Die Datei [Controllers/PersonsController.cs]:
| using Example08.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example08.Controllers;
// [ApiController]: eine Anfrage mit ungültigem Modell wird
// AUTOMATISCH abgewiesen (Fehler 400), noch bevor die Action läuft
[ApiController]
[Route("persons")]
public class PersonsController : Controller
{
// /persons/action01?name=martin&age=42&title=Mr
[HttpGet("action01")]
public object Action01([FromQuery] PersonModel person)
{
return new { person, ageType = person.Age?.GetType().Name };
}
}
|
- Zeile 6: Das Attribut [[ApiController]] macht den Controller zu einem JSON-Server (einer API). Es ändert mehrere Verhaltensweisen, unter anderem dieses: Eine Anfrage mit einem ungültigen Modell wird automatisch mit einem Fehler 400 abgelehnt, noch bevor die Action ausgeführt wird. Das entspricht der globalen [ValidationPipe] von [NestJS];
- Zeile 14: Die Action erhält ein [PersonModel], das aus den URL-Parametern gefüllt wird. Mit [[ApiController]] wird ein Parameter vom Typ einer Klasse standardmäßig im Body der Anfrage gesucht (in JSON): [[FromQuery]] legt fest, dass er in der URL gesucht werden soll;
- Zeile 16: Die Action gibt die empfangene Person und den Typ ihres Alters zurück.
Eine gültige Anfrage mit einem Parameter [pirate], der keiner Eigenschaft entspricht:
| curl -i "http://localhost:5000/persons/action01?name=martin&age=42&title=Mr&pirate=1"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"person":{"name":"martin","age":42,"title":"Mr","email":null},"ageType":"Int32"}
|
Das Alter ist tatsächlich eine Zahl, und der Parameter [pirate] wurde ignoriert: Das Binding füllt nur die Eigenschaften der Klasse. Eine ungültige Anfrage (die JSON-Antwort wurde zur besseren Lesbarkeit formatiert):
| curl -i "http://localhost:5000/persons/action01?name=m&age=abc&title=Dr&email=xx"
|
| HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Age": [
"The value 'abc' is not valid for Age."
],
"Name": [
"the name must have 2 to 20 characters"
],
"Email": [
"invalid email address"
],
"Title": [
"unknown title"
]
},
"traceId": "00-ea340e76f456fbefae537611139be71b-2db7a84085adc345-00"
}
|
[[ApiController]] hat die Anfrage mit einem Fehler 400 abgelehnt; ihr JSON-Body im Standardformat [Problem Details] (RFC 9110) listet die Fehler nach Feldern auf. Die Action wurde nicht ausgeführt. Der Fehler bei der Konvertierung des Alters hat eine englische Meldung, die von [ASP.NET Core] bereitgestellt wird; wir werden sehen, wie sie sich ersetzen lässt. Dasselbe gilt ganz ohne Parameter:
| curl -i http://localhost:5000/persons/action01
|
| HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Age": [
"the age is required"
],
"Name": [
"the name is required"
],
"Title": [
"the title is required",
"unknown title"
]
},
"traceId": "00-af1f22e662507d8f360028f71752ded1-4ff5a136398590da-00"
}
|
Dieses Verhalten ist für einen JSON-Server geeignet, der von einem [JavaScript]-Client abgefragt wird, der Fehler auf seine eigene Weise anzeigt. Für eine HTML-Anwendung ergibt ein Fehlercode wie bei JSON keinen Sinn: Wir möchten das Formular zusammen mit seinen Fehlern erneut anzeigen. Das folgende Beispiel zeigt, wie man die Kontrolle übernimmt.
3.3. Beispiel 09: Von der Action durchgeführte Validierung
Beispiel 09 verwendet kein [[ApiController]]. Die Klasse [PersonModel] ist identisch; nur der Controller ändert sich. Die Datei [Controllers/PersonsController.cs]:
| using System.Net;
using Example09.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example09.Controllers;
// kein [ApiController]: die Action wird IMMER ausgeführt, und sie ist es, die
// entscheidet, was bei einem ungültigen Modell zu tun ist
[Route("persons")]
public class PersonsController : Controller
{
[HttpGet("action01")]
public ContentResult Action01(PersonModel person)
{
// ModelState: das Ergebnis des Bindings UND der Validierung des Modells
if (ModelState.IsValid)
{
return Page($"<p>Welcome {person.Title} {person.Name} ({person.Age} years old)</p>");
}
// die Fehler, Feld für Feld
var items = ModelState
.Where(field => field.Value!.Errors.Count > 0)
.Select(field => $"<li>{field.Key}: {string.Join(", ", field.Value!.Errors.Select(e => e.ErrorMessage))}</li>");
return Page($"<p>The form contains errors:</p><ul>{string.Join("", items)}</ul>");
}
// eine HTML-Seite (in beiden Fällen Code 200)
private ContentResult Page(string html) => Content(html, "text/html; charset=utf-8");
}
|
Kommentieren wir diesen Code:
- Zeile 9: Ohne [[ApiController]] wird die Action immer ausgeführt, unabhängig davon, ob das Modell gültig ist oder nicht. Ein Parameter vom Typ einer Klasse wird überall gesucht: in der URL, in den Formularfeldern und in der Route;
- Zeile 13: Das Model Binding und die Validierung wurden vor der Ausführung der Action durchgeführt: Das Objekt [person] ist gefüllt, und [ModelState] enthält eventuelle Fehler;
- Zeilen 16–18: keine Fehler: eine Willkommensseite;
- Zeilen 21–23: andernfalls die Liste der Fehler. [ModelState] ist ein Dictionary, in dem jeder Schlüssel der Name eines Feldes ist ([Name], [Age] ...) und jeder Wert der Status dieses Feldes samt der Liste seiner Fehler ([Errors]). Die Methoden [LINQ], [Where] (filtern) und [Select] (transformieren) behalten die Felder mit Fehlern bei und erzeugen pro Feld eine HTML-Zeile. [!] teilt dem Compiler mit, dass ein Wert nicht [null] ist;
- Zeile 24: eine Seite, die die Fehler auflistet;
- Zeile 28: In beiden Fällen ist die Antwort eine HTML-Seite mit dem Statuscode 200.


Ein Konvertierungsfehler erscheint in [ModelState] als Validierungsfehler:
| curl -i "http://localhost:5000/persons/action01?name=martin&age=abc&title=Mr"
|
| HTTP/1.1 200 OK
Content-Length: 92
Content-Type: text/html; charset=utf-8
<p>The form contains errors:</p><ul><li>Age: The value 'abc' is not valid for Age.</li></ul>
|
Das ist die Technik, die alle Formulare der Fallstudie verwenden werden (siehe Beispiel 19): Die Action prüft [ModelState.IsValid] und zeigt das Formular erneut an, falls Fehler vorliegen.
3.4. Beispiel 10: Mehrfachparameter
Ein einzelner Parameter kann in einer Anfrage mehrfach vorkommen: Das ist bei Kontrollkästchen eines Formulars oder einer Mehrfachauswahlliste der Fall ([?color=red&color=green]).
Die Datei [Controllers/ArraysController.cs]:
| using Example10.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example10.Controllers;
[Route("arrays")]
public class ArraysController : Controller
{
// /arrays/action01?color=red&color=green: ein einfacher Parameter
[HttpGet("action01")]
public object Action01(string? color)
{
return new { color };
}
// /arrays/action02?color=red&color=green: ein Array
[HttpGet("action02")]
public object Action02(string[] color)
{
return new { color, count = color.Length };
}
// /arrays/action03?color=red: eine Liste, validiert durch ChoiceModel
[HttpGet("action03")]
public object Action03(ChoiceModel choice)
{
return new
{
colors = choice.Color,
valid = ModelState.IsValid,
errors = ModelState.Values.SelectMany(v => v.Errors).Select(e => e.ErrorMessage),
};
}
}
|
Die Action [Action01] (Zeilen 11–13) zeigt, was ein einzelner Parameter erhält:
| curl -i "http://localhost:5000/arrays/action01?color=red"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"color":"red"}
|
| curl -i "http://localhost:5000/arrays/action01?color=red&color=green"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"color":"red"}
|
Ein Parameter vom Typ [string] erhält nur den ersten Wert. Ein Parameter vom Typ Array ([Action02], Zeilen 18–20) erhält alle, ob es null, einer oder mehrere sind:
| curl -i "http://localhost:5000/arrays/action02?color=red"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"color":["red"],"count":1}
|
| curl -i "http://localhost:5000/arrays/action02?color=red&color=green"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"color":["red","green"],"count":2}
|
| curl -i "http://localhost:5000/arrays/action02"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"color":[],"count":0}
|
[ASP.NET Core] vermeidet so eine häufige Falle von [NestJS] ([Express]), wo dieselbe Variable bei einem einzelnen Wert eine Zeichenkette und bei mehreren Werten ein Array war. Die Liste muss trotzdem noch validiert werden. Die Datei [Models/ChoiceModel.cs]:
| using System.ComponentModel.DataAnnotations;
namespace Example10.Models;
// IValidatableObject: eine in C# geschriebene Validierung für das, was die Attribute
// nicht ausdrücken können (hier: JEDES Element der Liste)
public class ChoiceModel : IValidatableObject
{
private static readonly string[] Colors = ["red", "green", "blue"];
[MinLength(1, ErrorMessage = "choose at least one color")]
public List<string> Color { get; set; } = [];
public IEnumerable<ValidationResult> Validate(ValidationContext context)
{
foreach (var color in Color.Where(c => !Colors.Contains(c)))
{
// yield return: die Methode gibt die Fehler einzeln zurück
yield return new ValidationResult($"unknown color: {color}", [nameof(Color)]);
}
}
}
|
Kommentieren wir diesen Code:
- Zeile 7: Die Klasse implementiert die Schnittstelle [IValidatableObject]: eine in [C#] geschriebene Validierung für das, was die Attribute nicht ausdrücken können;
- Zeile 11: [[MinLength(1)]]: Die Liste muss mindestens ein Element enthalten;
- Zeilen 14–18: Die Methode [Validate], die von der Validierung nach den Attributen aufgerufen wird, prüft jede Farbe. Für jede unbekannte Farbe gibt sie einen Fehler ([ValidationResult]) zurück und gibt dabei das betroffene Feld an. [yield return] gibt die Fehler einzeln zurück, ohne eine Liste zu erstellen.
Die Action [Action03] des Controllers erhält ein [ChoiceModel] und gibt dessen Inhalt zusammen mit dem Validierungsstatus zurück:
| curl -i "http://localhost:5000/arrays/action03?color=red&color=green"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"colors":["red","green"],"valid":true,"errors":[]}
|
| curl -i "http://localhost:5000/arrays/action03?color=red&color=black"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"colors":["red","black"],"valid":false,"errors":["unknown color: black"]}
|
| curl -i "http://localhost:5000/arrays/action03"
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"colors":[],"valid":false,"errors":["choose at least one color"]}
|
3.5. Beispiel 11: Parameter einer POST-Anfrage
Ein mit der Methode POST gesendetes HTML-Formular legt seine Felder in den Body der Anfrage, nicht in die URL. Die Datei [Controllers/PostController.cs]:
| using System.Text.Json;
using Example11.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example11.Controllers;
[Route("post")]
public class PostController : Controller
{
// die Felder eines HTML-Formulars (Body vom Typ application/x-www-form-urlencoded)
[HttpPost("action01")]
public object Action01()
{
return new
{
receivedType = Request.ContentType,
fields = Request.Form.ToDictionary(c => c.Key, c => c.Value.ToString()),
};
}
// ein JSON-Body: [FromBody] deserialisiert ihn
[HttpPost("action02")]
public object Action02([FromBody] JsonElement body)
{
return new { receivedType = Request.ContentType, body };
}
// ein einzelnes Feld des Formulars: [FromForm]
[HttpPost("action03")]
public string Action03([FromForm] string? name)
{
return $"name = [{name}]";
}
// die Formularfelder, gebunden und validiert durch die Klasse PersonModel
[HttpPost("action04")]
public object Action04([FromForm] PersonModel person)
{
return new
{
person,
valid = ModelState.IsValid,
errors = ModelState.Values.SelectMany(v => v.Errors).Select(e => e.ErrorMessage),
};
}
}
|
Gehen wir diesen Code durch:
- Zeilen 12–17: [Request.Form] enthält die Felder eines HTML-Formulars (Body-Typ [application/x-www-form-urlencoded]), ohne Binding oder Konvertierung. [Request.ContentType] ist der Typ des Bodys;
- Zeilen 23–25: [[FromBody]] weist das System an, den Body der Anfrage als JSON-Dokument zu lesen (das sendet ein [JavaScript]-Client). [JsonElement] stellt ein beliebiges JSON-Dokument dar; es hätte auch eine Klasse deklariert werden können;
- Zeilen 30–32: [[FromForm]]: ein Feld des Formulars;
- Zeilen 37–43: das gesamte Formular, gebunden und validiert durch die Klasse [PersonModel] aus Beispiel 08.
Die Option [-d] von [curl] sendet eine POST-Anfrage mit einem Body im HTML-Format ([application/x-www-form-urlencoded]):
| curl -i -d "name=martin&age=42" http://localhost:5000/post/action01
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"receivedType":"application/x-www-form-urlencoded","fields":{"name":"martin","age":"42"}}
|
Derselbe Inhalt im JSON-Format:
| curl -i -H "Content-Type: application/json" -d '{"name":"martin","age":42}' http://localhost:5000/post/action02
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"receivedType":"application/json","body":{"name":"martin","age":42}}
|
(Geben Sie unter [Windows] an der Eingabeaufforderung [-d "{\"name\":\"martin\",\"age\":42}"] ein). Das Alter ist im ersten Fall eine Zeichenkette (ein HTML-Formular überträgt nur Text) und im zweiten Fall eine Zahl. Eine [[FromBody]]-Action lehnt einen Body ab, der nicht im JSON-Format vorliegt, und gibt einen Fehler 415 zurück ([Unsupported Media Type]):
| curl -i -d "name=martin&age=42" http://localhost:5000/post/action02
|
| HTTP/1.1 415 Unsupported Media Type
Content-Length: 0
|
Die beiden anderen Actions:
| curl -i -d "name=martin&age=42" http://localhost:5000/post/action03
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
name = [martin]
|
| curl -i -d "name=martin&age=42&title=Mme" http://localhost:5000/post/action04
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"person":{"name":"martin","age":42,"title":"Mme","email":null},"valid":true,"errors":[]}
|
| curl -i -d "name=martin&age=200" http://localhost:5000/post/action04
|
| HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"person":{"name":"martin","age":200,"title":null,"email":null},"valid":false,"errors":["the age must be between 0 and 150","the title is required","unknown title"]}
|
Eine POST-Action gibt wie eine GET-Action den Statuscode 200 zurück ([NestJS] dagegen gab standardmäßig 201 zurück). Bei einer HTML-Anwendung antwortet eine POST-Action entweder mit einer Seite (dem erneut angezeigten Formular) oder mit einer Weiterleitung (siehe Beispiel 20).
3.6. Beispiel 12: Benutzerdefiniertes Binding und benutzerdefinierte Validierung
Sie können das Model Binding und die Validierung erweitern. Die Fallstudie nutzt diese Möglichkeiten nur mäßig, aber ihr Verständnis hilft, die Funktionsweise von [ASP.NET Core] zu begreifen.
| 12-custom-binding/
├── Binding/
│ ├── DateFrBinder.cs
│ ├── LanguageBinder.cs
│ └── NoSpaceAttribute.cs
├── Controllers/
│ └── ExamplesController.cs
├── appsettings.json
├── Example12.csproj
└── Program.cs
|
3.6.1. Ein Model Binder: DateFrBinder
Ein Model Binder ist das Objekt, das den Wert eines Parameters aus der Anfrage erzeugt. [ASP.NET Core] stellt sie für alle gängigen Typen bereit; Sie können eigene schreiben. Die Datei [Binding/DateFrBinder.cs]:
| using System.Globalization;
using Microsoft.AspNetCore.Mvc.ModelBinding;
namespace Example12.Binding;
// ein "Model Binder": wandelt ein französisches Datum "23/09/2026" in ein DateOnly um
public class DateFrBinder : IModelBinder
{
public Task BindModelAsync(ModelBindingContext context)
{
// der Rohwert aus der URL, dem Formular, der Route...
var raw = context.ValueProvider.GetValue(context.ModelName).FirstValue;
if (DateOnly.TryParseExact(raw, "dd/MM/yyyy", CultureInfo.InvariantCulture, DateTimeStyles.None, out var date))
{
// Erfolg: der Wert, den die Action erhält
context.Result = ModelBindingResult.Success(date);
}
else
{
// Fehler: ein Fehler in ModelState ("31/02/2026" wird ebenfalls abgelehnt)
context.ModelState.AddModelError(context.ModelName, $"[{raw}] is not a valid dd/mm/yyyy date");
}
return Task.CompletedTask;
}
}
|
- Zeile 7: Ein Model Binder implementiert die Schnittstelle [IModelBinder];
- Zeile 9: Seine Methode [BindModelAsync] erhält den Binding-Kontext: den Parameternamen ([ModelName]), die Wertquellen ([ValueProvider]: die URL, das Formular, die Route ...), [ModelState] ...;
- Zeile 12: der Rohwert des Parameters ([FirstValue]: der erste, falls es mehrere gibt);
- Zeilen 13–16: [DateOnly.TryParseExact] konvertiert eine Zeichenkette im Format [dd/mm/yyyy] in [DateOnly] (ein Datum ohne Uhrzeit) und gibt [false] zurück, wenn das nicht möglich ist, auch bei einem nicht existierenden Datum (31/02/2026). Bei Erfolg liefert [ModelBindingResult.Success(date)] den Wert, den die Action erhält;
- Zeile 21: Schlägt der Vorgang fehl, wird ein Fehler zu [ModelState] hinzugefügt;
- Zeile 23: Die Methode ist ihrer Natur nach asynchron ([Task]), aber es gibt nichts abzuwarten: Sie gibt einen bereits abgeschlossenen Task zurück.
3.6.2. Ein zweiter Model Binder: LanguageBinder
Ein Parameter kann auch von anderswo als aus der URL oder dem Formular stammen. Die Datei [Binding/LanguageBinder.cs]:
| using Microsoft.AspNetCore.Mvc.ModelBinding;
namespace Example12.Binding;
// die bevorzugte Sprache des Browsers, aus dem Header gelesen
// "Accept-Language: fr-FR,fr;q=0.9,en;q=0.8" -> "fr"
public class LanguageBinder : IModelBinder
{
public Task BindModelAsync(ModelBindingContext context)
{
var header = context.HttpContext.Request.Headers.AcceptLanguage.ToString();
var first = header.Split(',')[0].Trim();
var language = first.Length >= 2 ? first[..2].ToLowerInvariant() : "fr";
context.Result = ModelBindingResult.Success(language);
return Task.CompletedTask;
}
}
|
- Zeile 11: der Header [Accept-Language], der die bevorzugten Sprachen des Benutzers angibt;
- Zeilen 12–13: die ersten beiden Buchstaben der ersten Sprache. [first[..2]] ist ein Bereich ([range]): die Zeichen mit den Indizes 0 und 1.
3.6.3. Ein Validierungsattribut: [NoSpace]
Die Datei [Binding/NoSpaceAttribute.cs]:
| using System.ComponentModel.DataAnnotations;
namespace Example12.Binding;
// ein selbst geschriebenes Validierungsattribut: [NoSpace]
public class NoSpaceAttribute : ValidationAttribute
{
public NoSpaceAttribute() : base("the {0} field must not contain any space")
{
}
public override bool IsValid(object? value)
{
// null wird akzeptiert: die Pflicht dazu ist Sache von [Required]
return value is not string text || !text.Contains(' ');
}
}
|
- Zeile 6: Ein Validierungsattribut erbt von [ValidationAttribute]. Üblicherweise endet der Name einer Attributklasse auf [Attribute], was in der Praxis weggelassen wird: [[NoSpace]];
- Zeile 8: die Standardfehlermeldung, die an die Elternklasse übergeben wird. [{0}] wird durch den Feldnamen ersetzt;
- Zeilen 12–15: Die Regel. [value is not string text]: Wenn der Wert keine Zeichenkette ist ([null] zum Beispiel), wird er akzeptiert; andernfalls wird er der Variablen [text] zugewiesen, die keine Leerzeichen enthalten darf. Die Fallstudie enthält ein Attribut dieser Art: [[OneOf]].
3.6.4. Der Controller
Die Datei [Controllers/ExamplesController.cs]:
| using Example12.Binding;
using Microsoft.AspNetCore.Mvc;
namespace Example12.Controllers;
[Route("examples")]
public class ExamplesController : Controller
{
// /examples/schedule?day=23/09/2026: ein benutzerdefinierter Model Binder
[HttpGet("schedule")]
public IActionResult Schedule([ModelBinder(typeof(DateFrBinder))] DateOnly day)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState[nameof(day)]!.Errors[0].ErrorMessage);
}
return Ok($"schedule for the day [{day:yyyy-MM-dd}]");
}
// /examples/hello: ein Parameter, der nicht aus der URL, sondern aus einem Header stammt
[HttpGet("hello")]
public string Hello([ModelBinder(typeof(LanguageBinder))] string language)
{
return language == "en" ? "Hello!" : "Bonjour !";
}
// /examples/search?keyword=aspnet: ein benutzerdefiniertes Validierungsattribut
[HttpGet("search")]
public IActionResult Search([NoSpace] string? keyword)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState[nameof(keyword)]!.Errors[0].ErrorMessage);
}
return Ok($"search for [{keyword}]");
}
}
|
- Zeile 11: Das Attribut [[ModelBinder]] legt den Model Binder fest, der für diesen Parameter verwendet werden soll;
- Zeile 15: Ein ungültiges Datum führt zu einem Fehler 400 mit der Meldung des Model Binders;
- Zeile 22: Der Parameter [language] wird vom zweiten Model Binder bereitgestellt;
- Zeile 29: Ein Validierungsattribut kann auch direkt auf einen Action-Parameter angewendet werden.
Die Ergebnisse:
| curl -i "http://localhost:5000/examples/schedule?day=23/09/2026"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
schedule for the day [2026-09-23]
|
| curl -i "http://localhost:5000/examples/schedule?day=2026-09-23"
|
| HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
[2026-09-23] is not a valid dd/mm/yyyy date
|
| curl -i "http://localhost:5000/examples/schedule?day=31/02/2026"
|
| HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
[31/02/2026] is not a valid dd/mm/yyyy date
|
| curl -i -H "Accept-Language: fr-FR,fr;q=0.9" http://localhost:5000/examples/hello
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Bonjour !
|
| curl -i -H "Accept-Language: en-US,en;q=0.9" http://localhost:5000/examples/hello
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Hello!
|
(Die Option [-H] von [curl] fügt der Anfrage einen Header hinzu)
| curl -i "http://localhost:5000/examples/search?keyword=aspnet"
|
| HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
search for [aspnet]
|
| curl -i "http://localhost:5000/examples/search?keyword=asp%20net"
|
| HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
the keyword field must not contain any space
|
([%20] codiert ein Leerzeichen in einer URL)
3.6.5. Fazit
Das Action-Modell wird vom Model Binding anhand der Anfrage erstellt: Routenparameter, URL, Formularfelder, JSON-Body und Header. Die Werte werden in die Parametertypen konvertiert und dann anhand der Attribute validiert. Das Ergebnis dieser beiden Schritte wird in [ModelState] gespeichert. Bei einem JSON-Server lehnt [[ApiController]] ein ungültiges Modell automatisch ab; bei einer HTML-Anwendung prüft die Action selbst [ModelState.IsValid] (Beispiel 09), damit das Formular erneut angezeigt werden kann. Das ist das Thema des nächsten Kapitels.