3. El modelo de la acción
Una acción necesita información enviada por el navegador: los parámetros de la URL ([?name=martin&age=42]), los campos de un formulario y los parámetros de ruta. El curso original designa todo este conjunto de información como el modelo de la acción. Este capítulo muestra cómo [ASP.NET Core] proporciona esta información a la acción, la convierte al tipo correcto y la valida. Este proceso se denomina enlace de modelos ([model binding]).
3.1. Ejemplo 07: Parámetros de la URL
El archivo [Controllers/ParametersController.cs]:
| using Microsoft.AspNetCore.Mvc;
namespace Example07.Controllers;
[Route("parameters")]
public class ParametersController : Controller
{
// /parameters/action01?name=martin: el parámetro de URL [name] -> el parámetro de acción [name]
[HttpGet("action01")]
public string Action01(string? name)
{
return $"name = [{name}], of type {name?.GetType().Name ?? "null"}";
}
// /parameters/action02?age=42: el valor se CONVIERTE al tipo del parámetro
[HttpGet("action02")]
public string Action02(int age)
{
return $"age = [{age}], of type {age.GetType().Name}, ModelState.IsValid = {ModelState.IsValid}";
}
// /parameters/action03?age=42: int? distingue un parámetro ausente (null) de un cero
[HttpGet("action03")]
public string Action03(int? age)
{
return $"age = [{age?.ToString() ?? "null"}], ModelState.IsValid = {ModelState.IsValid}";
}
// /parameters/action04?page=2: un valor por defecto si falta el parámetro
[HttpGet("action04")]
public string Action04(int page = 1)
{
return $"page = [{page}]";
}
// /parameters/action05?q=nest: [FromQuery(Name = ...)] cuando los nombres difieren
[HttpGet("action05")]
public string Action05([FromQuery(Name = "q")] string? search)
{
return $"search = [{search}]";
}
// /parameters/action06?name=martin&age=42: todos los parámetros a la vez
[HttpGet("action06")]
public Dictionary<string, string> Action06()
{
return Request.Query.ToDictionary(p => p.Key, p => p.Value.ToString());
}
}
|
Analicemos este código:
- líneas 10–12: el enlace de modelos asocia los parámetros de la acción con los datos de la consulta por nombre: el parámetro [name] de la acción recibe el valor del parámetro [name] de la URL (la parte que sigue a [?], llamada cadena de consulta o [query string]). El tipo [string?] indica que el valor puede faltar; en ese caso, es [null]. [name?.GetType().Name ?? "null"]: el nombre del tipo del valor, o la cadena ["null"] si el valor es [null] (el operador [??] proporciona un valor de reemplazo);
- líneas 17–19: el parámetro se declara de tipo [int]: el enlace de modelos convierte la cadena recibida (["42"]) en un número. Si la conversión falla ([?age=abc]), la acción se ejecuta de todos modos, con el valor predeterminado del tipo (0 para un [int]), y el fallo se registra en [ModelState]; el estado del enlace de modelos —[ModelState.IsValid]— pasa entonces a ser [false];
- líneas 24–26: con el tipo [int?] (un entero “anulable”), un parámetro ausente se representa como [null], no como 0: esto permite distinguir entre “sin edad” y “edad 0”;
- líneas 31–33: un valor predeterminado de [C#] reemplaza a un parámetro ausente;
- líneas 38–40: el atributo [[FromQuery(Name = "q")]] especifica dónde buscar el valor (en la URL) y con qué nombre: el parámetro [search] de la acción recibe el parámetro [q] de la URL;
- líneas 45–47: [Request.Query] proporciona acceso a todos los parámetros de la URL, sin ningún enlace ni conversión. [ToDictionary] ([LINQ]) crea a partir de ellos un diccionario, que se serializa en JSON.
Los resultados:
| 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"}
|
Las comillas alrededor de la URL son necesarias cuando esta contiene el carácter [&], que tiene un significado específico para la consola. Observe que:
- un parámetro se enlaza por su nombre, sin distinguir mayúsculas de minúsculas ([?NAME=martin] también es válido);
- su valor se convierte al tipo declarado. Esta es una diferencia importante con respecto a [NestJS], donde el tipo de un parámetro era solo una declaración ([TypeScript]) que se eliminaba en la compilación;
- una conversión imposible no provoca un error: la acción se ejecuta con un valor predeterminado, y le corresponde a la acción comprobar [ModelState.IsValid]. Un tipo “anulable” ([int?]) evita que un valor ausente o inválido se confunda con 0.
Los caracteres acentuados y los espacios se codifican en una URL ([%C3%A9] para [é], etc.): [ASP.NET Core] los decodifica antes del enlace.

3.2. Ejemplo 08: Un modelo de acción descrito por una clase
Cuando una acción tiene varios parámetros, estos se describen mediante una clase. Cada propiedad de la clase lleva atributos de validación proporcionados por el espacio de nombres estándar [System.ComponentModel.DataAnnotations]. Esto equivale a los decoradores de la biblioteca [class-validator] de [NestJS].
El archivo [Models/PersonModel.cs]:
| using System.ComponentModel.DataAnnotations;
namespace Example08.Models;
// el modelo de la acción: una clase en la que cada propiedad lleva sus restricciones
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; }
// opcional: sin [Required]
[EmailAddress(ErrorMessage = "invalid email address")]
public string? Email { get; set; }
}
|
Comentemos este código:
- línea 1: el espacio de nombres de los atributos de validación;
- línea 10: cada parámetro esperado es una propiedad pública ([{ get; set; }]: se puede leer y escribir). El enlace de modelos crea un objeto [PersonModel] y luego rellena cada propiedad con el parámetro del mismo nombre;
- líneas 8–9: el nombre es obligatorio ([[Required]]) y debe tener entre 2 y 20 caracteres ([[StringLength]]). Cada atributo acepta un mensaje de error personalizado ([ErrorMessage]). Las propiedades se declaran “anulables” ([string?], [int?]): un parámetro puede omitirse en una consulta, y [[Required]] impone esta exigencia;
- líneas 12–14: la edad se convierte a entero, es obligatoria y debe estar entre 0 y 150 ([[Range]]);
- línea 17: el tratamiento (título) debe pertenecer a una lista de valores ([[AllowedValues]], introducido con [.NET] 8);
- línea 21: el correo electrónico es opcional (sin [[Required]]); si se proporciona, debe ser válido.
El archivo [Controllers/PersonsController.cs]:
| using Example08.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example08.Controllers;
// [ApiController]: una solicitud cuyo modelo es inválido se rechaza
// AUTOMÁTICAMENTE (error 400), incluso antes de que se ejecute la acción
[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 };
}
}
|
- línea 6: el atributo [[ApiController]] orienta el controlador a un servidor JSON (una API). Cambia varios comportamientos, entre ellos este: una solicitud con un modelo inválido se rechaza automáticamente con un error 400 antes incluso de que se ejecute la acción. Esto equivale al [ValidationPipe] global de [NestJS];
- línea 14: la acción recibe un [PersonModel], rellenado a partir de los parámetros de la URL. Con [[ApiController]], un parámetro de tipo clase se busca de forma predeterminada en el cuerpo de la solicitud (en JSON): [[FromQuery]] especifica que debe buscarse en la URL;
- Línea 16: la acción devuelve la persona recibida y el tipo de su edad.
Una solicitud válida con un parámetro [pirate] que no corresponde a ninguna propiedad:
| 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"}
|
La edad es, en efecto, un número, y el parámetro [pirate] se ignoró: el enlace rellena solo las propiedades de la clase. Una solicitud inválida (la respuesta JSON se ha formateado para facilitar la lectura):
| 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]] rechazó la solicitud con un error 400; su cuerpo, JSON, en el formato estándar [Problem Details] (RFC 9110), enumera los errores por campo. La acción no se ejecutó. El error de conversión de la edad tiene un mensaje en inglés, proporcionado por [ASP.NET Core]; veremos cómo reemplazarlo. Lo mismo ocurre sin ningún parámetro:
| 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"
}
|
Este comportamiento es adecuado para un servidor JSON consultado por un cliente [JavaScript] que muestra los errores a su manera. Para una aplicación HTML, un código de error con JSON no tiene sentido: queremos volver a mostrar el formulario junto con sus errores. El siguiente ejemplo muestra cómo tomar el control.
3.3. Ejemplo 09: Validación realizada por la acción
El ejemplo 09 no usa [[ApiController]]. La clase [PersonModel] es idéntica; solo cambia el controlador. El archivo [Controllers/PersonsController.cs]:
| using System.Net;
using Example09.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example09.Controllers;
// sin [ApiController]: la acción se ejecuta SIEMPRE, y es la acción la que
// decide qué hacer con un modelo inválido
[Route("persons")]
public class PersonsController : Controller
{
[HttpGet("action01")]
public ContentResult Action01(PersonModel person)
{
// ModelState: el resultado del enlace Y de la validación del modelo
if (ModelState.IsValid)
{
return Page($"<p>Welcome {person.Title} {person.Name} ({person.Age} years old)</p>");
}
// los errores, campo por campo
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>");
}
// una página HTML (código 200 en ambos casos)
private ContentResult Page(string html) => Content(html, "text/html; charset=utf-8");
}
|
Comentemos este código:
- línea 9: sin [[ApiController]], la acción se ejecuta siempre, sea o no válido el modelo. Un parámetro de tipo clase se busca en todas partes: en la URL, en los campos del formulario y en la ruta;
- línea 13: el enlace de modelos y la validación se realizaron antes de ejecutar la acción: el objeto [person] está rellenado, y [ModelState] contiene los errores, si los hay;
- líneas 16–18: sin errores: una página de bienvenida;
- líneas 21–23: en caso contrario, la lista de errores. [ModelState] es un diccionario en el que cada clave es el nombre de un campo ([Name], [Age]...) y cada valor es el estado de ese campo, junto con su lista de errores ([Errors]). Los métodos [LINQ], [Where] (filtrar) y [Select] (transformar) conservan los campos con errores y generan una línea HTML por campo. [!] informa al compilador de que un valor no es [null];
- línea 24: una página que enumera los errores;
- línea 28: en ambos casos, la respuesta es una página HTML, con código de estado 200.


Un error de conversión aparece en [ModelState] como un error de validación:
| 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>
|
Esta es la técnica que usarán todos los formularios del caso de estudio (véase el ejemplo 19): la acción comprueba [ModelState.IsValid] y vuelve a mostrar el formulario si hay errores.
3.4. Ejemplo 10: Parámetros múltiples
Un mismo parámetro puede aparecer varias veces en una consulta: es el caso de las casillas de verificación de un formulario o de una lista de selección múltiple ([?color=red&color=green]).
El archivo [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: un parámetro simple
[HttpGet("action01")]
public object Action01(string? color)
{
return new { color };
}
// /arrays/action02?color=red&color=green: un arreglo
[HttpGet("action02")]
public object Action02(string[] color)
{
return new { color, count = color.Length };
}
// /arrays/action03?color=red: una lista, validada por 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),
};
}
}
|
La acción [Action01] (líneas 11–13) muestra lo que recibe un parámetro simple:
| 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"}
|
Un parámetro de tipo [string] recibe solo el primer valor. Un parámetro de tipo arreglo ([Action02], líneas 18–20) los recibe todos, sean cero, uno o más:
| 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] evita así una trampa habitual en [NestJS] ([Express]), donde la misma variable era una cadena para un solo valor y un arreglo para varios valores. Aun así, la lista debe validarse. El archivo [Models/ChoiceModel.cs]:
| using System.ComponentModel.DataAnnotations;
namespace Example10.Models;
// IValidatableObject: una validación escrita en C#, para lo que los atributos
// no pueden expresar (aquí: CADA elemento de la lista)
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: el método devuelve los errores uno por uno
yield return new ValidationResult($"unknown color: {color}", [nameof(Color)]);
}
}
}
|
Comentemos este código:
- línea 7: la clase implementa la interfaz [IValidatableObject]: una validación escrita en [C#] para lo que los atributos no pueden expresar;
- línea 11: [[MinLength(1)]]: la lista debe tener al menos un elemento;
- líneas 14–18: el método [Validate], invocado por la validación después de los atributos, comprueba cada color. Devuelve un error ([ValidationResult]) por cada color desconocido, indicando el campo correspondiente. [yield return] devuelve los errores uno por uno, sin crear una lista.
La acción [Action03] del controlador recibe un [ChoiceModel] y devuelve su contenido junto con el estado de la validación:
| 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. Ejemplo 11: Parámetros de una solicitud POST
Un formulario HTML enviado con el método POST coloca sus campos en el cuerpo de la solicitud, no en la URL. El archivo [Controllers/PostController.cs]:
| using System.Text.Json;
using Example11.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example11.Controllers;
[Route("post")]
public class PostController : Controller
{
// los campos de un formulario HTML (cuerpo 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()),
};
}
// un cuerpo JSON: [FromBody] lo deserializa
[HttpPost("action02")]
public object Action02([FromBody] JsonElement body)
{
return new { receivedType = Request.ContentType, body };
}
// un único campo del formulario: [FromForm]
[HttpPost("action03")]
public string Action03([FromForm] string? name)
{
return $"name = [{name}]";
}
// los campos del formulario, enlazados y validados por la clase 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),
};
}
}
|
Analicemos este código:
- líneas 12–17: [Request.Form] contiene los campos de un formulario HTML (cuerpo de tipo [application/x-www-form-urlencoded]), sin ningún enlace ni conversión. [Request.ContentType] es el tipo del cuerpo;
- líneas 23–25: [[FromBody]] indica al sistema que lea el cuerpo de la solicitud como un documento JSON (esto es lo que envía un cliente [JavaScript]). [JsonElement] representa cualquier documento JSON; también se habría podido declarar una clase;
- líneas 30–32: [[FromForm]]: un campo del formulario;
- líneas 37–43: el formulario completo, enlazado y validado por la clase [PersonModel] del ejemplo 08.
La opción [-d] de [curl] envía una solicitud POST con un cuerpo en formato de formulario HTML ([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"}}
|
El mismo contenido en formato JSON:
| 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}}
|
(en [Windows], introduzca [-d "{\"name\":\"martin\",\"age\":42}"] en el símbolo del sistema). La edad es una cadena en el primer caso (un formulario HTML solo transporta texto) y un número en el segundo. Una acción con [[FromBody]] rechaza un cuerpo que no esté en formato JSON, devolviendo un error 415 ([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
|
Las otras dos acciones:
| 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"]}
|
Una acción POST devuelve un código de estado 200, igual que una acción GET ([NestJS], en cambio, devolvía un 201 de forma predeterminada). En una aplicación HTML, una acción POST responde con una página (el formulario vuelto a mostrar) o con una redirección (véase el ejemplo 20).
3.6. Ejemplo 12: Enlace y validación personalizados
Es posible extender el enlace de modelos y la validación. El caso de estudio hace un uso moderado de estas funciones, pero entenderlas ayuda a comprender cómo funciona [ASP.NET Core].
| 12-custom-binding/
├── Binding/
│ ├── DateFrBinder.cs
│ ├── LanguageBinder.cs
│ └── NoSpaceAttribute.cs
├── Controllers/
│ └── ExamplesController.cs
├── appsettings.json
├── Example12.csproj
└── Program.cs
|
3.6.1. Un enlazador de modelos: DateFrBinder
Un enlazador de modelos es el objeto que construye el valor de un parámetro a partir de la solicitud. [ASP.NET Core] proporciona enlazadores para todos los tipos comunes; usted puede escribir los suyos. El archivo [Binding/DateFrBinder.cs]:
| using System.Globalization;
using Microsoft.AspNetCore.Mvc.ModelBinding;
namespace Example12.Binding;
// un "model binder": convierte una fecha francesa "23/09/2026" en un DateOnly
public class DateFrBinder : IModelBinder
{
public Task BindModelAsync(ModelBindingContext context)
{
// el valor sin procesar, tomado de la URL, el formulario, la ruta...
var raw = context.ValueProvider.GetValue(context.ModelName).FirstValue;
if (DateOnly.TryParseExact(raw, "dd/MM/yyyy", CultureInfo.InvariantCulture, DateTimeStyles.None, out var date))
{
// éxito: el valor que recibirá la acción
context.Result = ModelBindingResult.Success(date);
}
else
{
// falla: un error en ModelState ("31/02/2026" también se rechaza)
context.ModelState.AddModelError(context.ModelName, $"[{raw}] is not a valid dd/mm/yyyy date");
}
return Task.CompletedTask;
}
}
|
- línea 7: un enlazador de modelos implementa la interfaz [IModelBinder];
- línea 9: su método [BindModelAsync] recibe el contexto de enlace: el nombre del parámetro ([ModelName]), las fuentes de valores ([ValueProvider]: la URL, el formulario, la ruta...), [ModelState]...;
- línea 12: el valor sin procesar del parámetro ([FirstValue]: el primero, si hay varios);
- líneas 13–16: [DateOnly.TryParseExact] convierte una cadena en el formato [dd/mm/yyyy] a [DateOnly] (una fecha sin hora), y devuelve [false] si es imposible, incluso para una fecha que no existe (31/02/2026). Si tiene éxito, [ModelBindingResult.Success(date)] proporciona el valor que recibirá la acción;
- línea 21: si la operación falla, se agrega un error a [ModelState];
- línea 23: el método es asíncrono por naturaleza ([Task]), pero no hay nada que esperar: devuelve una tarea que ya se completó.
3.6.2. Un segundo enlazador de modelos: LanguageBinder
Un parámetro puede provenir de un lugar distinto de la URL o del formulario. El archivo [Binding/LanguageBinder.cs]:
| using Microsoft.AspNetCore.Mvc.ModelBinding;
namespace Example12.Binding;
// el idioma preferido del navegador, leído del encabezado
// "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;
}
}
|
- línea 11: el encabezado [Accept-Language], que especifica los idiomas preferidos del usuario;
- líneas 12–13: las dos primeras letras del primer idioma. [first[..2]] es un rango ([range]): los caracteres con índices 0 y 1.
3.6.3. Un atributo de validación: [NoSpace]
El archivo [Binding/NoSpaceAttribute.cs]:
| using System.ComponentModel.DataAnnotations;
namespace Example12.Binding;
// un atributo de validación "casero": [NoSpace]
public class NoSpaceAttribute : ValidationAttribute
{
public NoSpaceAttribute() : base("the {0} field must not contain any space")
{
}
public override bool IsValid(object? value)
{
// se acepta null: exigirlo es tarea de [Required]
return value is not string text || !text.Contains(' ');
}
}
|
- línea 6: un atributo de validación hereda de [ValidationAttribute]. Por convención, el nombre de una clase de atributo termina en [Attribute], sufijo que en la práctica se omite: [[NoSpace]];
- línea 8: el mensaje de error predeterminado, que se pasa a la clase padre. [{0}] se reemplazará por el nombre del campo;
- líneas 12–15: la regla. [value is not string text]: si el valor no es una cadena ([null], por ejemplo), se acepta; en caso contrario, se asigna a la variable [text], que no debe contener ningún espacio. El caso de estudio tiene un atributo de este tipo: [[OneOf]].
3.6.4. El controlador
El archivo [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: un model binder personalizado
[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: un parámetro que no proviene de la URL sino de un encabezado
[HttpGet("hello")]
public string Hello([ModelBinder(typeof(LanguageBinder))] string language)
{
return language == "en" ? "Hello!" : "Bonjour !";
}
// /examples/search?keyword=aspnet: un atributo de validación personalizado
[HttpGet("search")]
public IActionResult Search([NoSpace] string? keyword)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState[nameof(keyword)]!.Errors[0].ErrorMessage);
}
return Ok($"search for [{keyword}]");
}
}
|
- línea 11: el atributo [[ModelBinder]] especifica el enlazador de modelos que se usará para este parámetro;
- línea 15: una fecha inválida produce un error 400, con el mensaje del enlazador de modelos;
- línea 22: el parámetro [language] lo proporciona el segundo enlazador de modelos;
- línea 29: un atributo de validación también se puede aplicar directamente a un parámetro de acción.
Los resultados:
| 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!
|
(La opción [-H] de [curl] agrega un encabezado a la solicitud)
| 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] codifica un espacio en una URL)
3.6.5. Conclusión
El modelo de la acción se construye mediante el enlace de modelos a partir de la solicitud: parámetros de ruta, URL, campos de formulario, cuerpo JSON y encabezados. Los valores se convierten a los tipos de los parámetros y luego se validan según los atributos. El resultado de estos dos pasos se almacena en [ModelState]. En un servidor JSON, [[ApiController]] rechaza automáticamente un modelo inválido; en una aplicación HTML, la propia acción comprueba [ModelState.IsValid] (ejemplo 09) para poder volver a mostrar el formulario. De eso trata el próximo capítulo.