3. O modelo da action
Uma action precisa de informações enviadas pelo navegador: os parâmetros da URL ([?name=martin&age=42]), os campos de formulário e os parâmetros de rota. O curso de origem se refere a todas essas informações como o modelo da action. Este capítulo mostra como o [ASP.NET Core] fornece essas informações à action, as converte para o tipo correto e as valida. Esse processo se chama model binding ([model binding]).
3.1. Exemplo 07: Parâmetros da URL
O arquivo [Controllers/ParametersController.cs]:
| using Microsoft.AspNetCore.Mvc;
namespace Example07.Controllers;
[Route("parameters")]
public class ParametersController : Controller
{
// /parameters/action01?name=martin: o parâmetro de URL [name] -> o parâmetro de action [name]
[HttpGet("action01")]
public string Action01(string? name)
{
return $"name = [{name}], of type {name?.GetType().Name ?? "null"}";
}
// /parameters/action02?age=42: o valor é CONVERTIDO para o tipo do 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 um parâmetro ausente (null) de um zero
[HttpGet("action03")]
public string Action03(int? age)
{
return $"age = [{age?.ToString() ?? "null"}], ModelState.IsValid = {ModelState.IsValid}";
}
// /parameters/action04?page=2: um valor padrão se o parâmetro estiver ausente
[HttpGet("action04")]
public string Action04(int page = 1)
{
return $"page = [{page}]";
}
// /parameters/action05?q=nest: [FromQuery(Name = ...)] quando os nomes diferem
[HttpGet("action05")]
public string Action05([FromQuery(Name = "q")] string? search)
{
return $"search = [{search}]";
}
// /parameters/action06?name=martin&age=42: todos os parâmetros de uma vez
[HttpGet("action06")]
public Dictionary<string, string> Action06()
{
return Request.Query.ToDictionary(p => p.Key, p => p.Value.ToString());
}
}
|
Vamos analisar este código:
- linhas 10–12: o model binding associa os parâmetros da action aos dados da requisição pelo nome: o parâmetro [name] da action recebe o valor do parâmetro [name] da URL (a parte que vem após o [?], chamada de query string ou [query string]). O tipo [string?] indica que o valor pode estar ausente; nesse caso, ele é [null]. [name?.GetType().Name ?? "null"]: o nome do tipo do valor ou a string ["null"] se o valor for [null] (o operador [??] fornece um valor de substituição);
- linhas 17–19: o parâmetro é declarado com o tipo [int]: o model binding converte a string recebida (["42"]) em um número. Se a conversão falhar ([?age=abc]), a action é executada mesmo assim, usando o valor padrão do tipo (0 para um [int]), e a falha é registrada em [ModelState]; o estado do model binding — [ModelState.IsValid]— passa então a ser [false];
- linhas 24–26: com o tipo [int?] (um inteiro “anulável”), um parâmetro ausente é representado como [null], e não como 0: isso permite distinguir entre “sem idade” e “idade 0”;
- linhas 31–33: um valor padrão de [C#] substitui um parâmetro ausente;
- linhas 38–40: o atributo [[FromQuery(Name = "q")]] especifica onde procurar o valor (na URL) e sob qual nome: o parâmetro [search] da action recebe o parâmetro [q] da URL;
- linhas 45–47: [Request.Query] dá acesso a todos os parâmetros da URL, sem nenhum mapeamento ou conversão. [ToDictionary] ([LINQ]) cria a partir deles um dicionário, serializado em JSON.
Os 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"}
|
As aspas em torno da URL são necessárias quando ela contém o caractere [&], que tem um significado específico para o console. Observe que:
- um parâmetro é vinculado pelo nome, independentemente de maiúsculas e minúsculas ([?NAME=martin] também é válido);
- seu valor é convertido para o tipo declarado. Essa é uma diferença importante em relação ao [NestJS], no qual o tipo de um parâmetro era apenas uma declaração ([TypeScript]) removida em tempo de compilação;
- uma conversão impossível não causa erro: a action é executada com um valor padrão, e cabe a ela verificar [ModelState.IsValid]. Um tipo “anulável” ([int?]) evita que um valor ausente ou inválido seja confundido com 0.
Caracteres acentuados e espaços são codificados em uma URL ([%C3%A9] para [é] etc.): o [ASP.NET Core] os decodifica antes do binding.

3.2. Exemplo 08: Um modelo de action descrito por uma classe
Quando uma action tem vários parâmetros, eles são descritos por uma classe. Cada propriedade da classe carrega atributos de validação fornecidos pelo namespace padrão [System.ComponentModel.DataAnnotations]. Isso equivale aos decoradores da biblioteca [class-validator] do [NestJS].
O arquivo [Models/PersonModel.cs]:
| using System.ComponentModel.DataAnnotations;
namespace Example08.Models;
// o modelo da action: uma classe em que cada propriedade carrega suas restrições
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: sem [Required]
[EmailAddress(ErrorMessage = "invalid email address")]
public string? Email { get; set; }
}
|
Vamos comentar este código:
- linha 1: o namespace dos atributos de validação;
- linha 10: cada parâmetro esperado é uma propriedade pública ([{ get; set; }]: ela pode ser lida e gravada). O model binding cria um objeto [PersonModel] e depois preenche cada propriedade com o parâmetro de mesmo nome;
- linhas 8–9: o nome é obrigatório ([[Required]]) e deve ter entre 2 e 20 caracteres ([[StringLength]]). Cada atributo aceita uma mensagem de erro personalizada ([ErrorMessage]). As propriedades são declaradas “anuláveis” ([string?], [int?]): um parâmetro pode estar ausente de uma requisição, e [[Required]] impõe essa obrigatoriedade;
- linhas 12–14: a idade é convertida em um inteiro, é obrigatória e deve estar entre 0 e 150 ([[Range]]);
- linha 17: o título deve pertencer a uma lista de valores ([[AllowedValues]], introduzido com o [.NET] 8);
- linha 21: o endereço de e-mail é opcional (sem [[Required]]); se informado, deve ser válido.
O arquivo [Controllers/PersonsController.cs]:
| using Example08.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example08.Controllers;
// [ApiController]: uma requisição cujo modelo é inválido é rejeitada
// AUTOMATICAMENTE (erro 400), antes mesmo de a action ser executada
[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 };
}
}
|
- linha 6: o atributo [[ApiController]] direciona o controller para um servidor JSON (uma API). Ele altera vários comportamentos, entre eles este: uma requisição com um modelo inválido é automaticamente rejeitada com um erro 400 antes mesmo de a action ser executada. Isso equivale ao [ValidationPipe] global do [NestJS];
- linha 14: a action recebe um [PersonModel], preenchido a partir dos parâmetros da URL. Com [[ApiController]], um parâmetro de tipo classe é procurado por padrão no corpo da requisição (em JSON): [[FromQuery]] especifica que ele deve ser procurado na URL;
- linha 16: a action devolve a pessoa recebida e o tipo da idade dela.
Uma requisição válida com um parâmetro [pirate] que não corresponde a nenhuma propriedade:
| 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"}
|
A idade é de fato um número, e o parâmetro [pirate] foi ignorado: o binding preenche apenas as propriedades da classe. Uma requisição inválida (o JSON da resposta foi formatado para facilitar a leitura):
| 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]] rejeitou a requisição com um erro 400; o corpo dele, em JSON, no formato padrão [Problem Details] (RFC 9110), lista os erros por campo. A action não foi executada. O erro de conversão da idade tem uma mensagem em inglês, fornecida pelo [ASP.NET Core]; veremos como substituí-la. O mesmo vale quando não há nenhum 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"
}
|
Esse comportamento é adequado a um servidor JSON, consultado por um cliente [JavaScript] que exibe os erros à sua maneira. Para uma aplicação HTML, um código de erro como o JSON não faz sentido: queremos reexibir o formulário junto com seus erros. O exemplo seguinte mostra como assumir o controle.
3.3. Exemplo 09: Validação realizada pela action
O Exemplo 09 não usa [[ApiController]]. A classe [PersonModel] é idêntica; só o controller muda. O arquivo [Controllers/PersonsController.cs]:
| using System.Net;
using Example09.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example09.Controllers;
// sem [ApiController]: a action é SEMPRE executada, e é ela que
// decide o que fazer com um modelo inválido
[Route("persons")]
public class PersonsController : Controller
{
[HttpGet("action01")]
public ContentResult Action01(PersonModel person)
{
// ModelState: o resultado do binding E da validação do modelo
if (ModelState.IsValid)
{
return Page($"<p>Welcome {person.Title} {person.Name} ({person.Age} years old)</p>");
}
// os erros, campo a 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>");
}
// uma página HTML (código 200 nos dois casos)
private ContentResult Page(string html) => Content(html, "text/html; charset=utf-8");
}
|
Vamos comentar este código:
- linha 9: sem [[ApiController]], a action é executada sempre, quer o modelo seja válido ou não. Um parâmetro de tipo classe é procurado em todos os lugares: na URL, nos campos do formulário e na rota;
- linha 13: o model binding e a validação foram realizados antes da execução da action: o objeto [person] está preenchido, e [ModelState] contém os eventuais erros;
- linhas 16–18: sem erros: uma página de boas-vindas;
- linhas 21–23: caso contrário, a lista de erros. [ModelState] é um dicionário em que cada chave é o nome de um campo ([Name], [Age]...) e cada valor é o estado desse campo, junto com sua lista de erros ([Errors]). Os métodos [LINQ], [Where] (filtrar) e [Select] (transformar) mantêm os campos com erros e geram uma linha HTML por campo. [!] informa ao compilador que um valor não é [null];
- linha 24: uma página que lista os erros;
- linha 28: nos dois casos, a resposta é uma página HTML, com código de status 200.


Um erro de conversão aparece em [ModelState] como um erro de validação:
| 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 é a técnica que todos os formulários do estudo de caso usarão (veja o Exemplo 19): a action verifica [ModelState.IsValid] e reexibe o formulário se houver erros.
3.4. Exemplo 10: Parâmetros múltiplos
Um mesmo parâmetro pode aparecer várias vezes em uma requisição: é o caso das caixas de seleção de um formulário ou de uma lista de seleção múltipla ([?color=red&color=green]).
O arquivo [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: um parâmetro simples
[HttpGet("action01")]
public object Action01(string? color)
{
return new { color };
}
// /arrays/action02?color=red&color=green: um array
[HttpGet("action02")]
public object Action02(string[] color)
{
return new { color, count = color.Length };
}
// /arrays/action03?color=red: uma 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),
};
}
}
|
A action [Action01] (linhas 11–13) mostra o que um parâmetro simples recebe:
| 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"}
|
Um parâmetro do tipo [string] recebe apenas o primeiro valor. Um parâmetro do tipo array ([Action02], linhas 18–20) recebe todos eles, sejam zero, um ou mais:
| 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}
|
O [ASP.NET Core] evita, assim, uma armadilha comum no [NestJS] ([Express]), em que a mesma variável era uma string para um único valor e um array para vários valores. A lista ainda precisa ser validada. O arquivo [Models/ChoiceModel.cs]:
| using System.ComponentModel.DataAnnotations;
namespace Example10.Models;
// IValidatableObject: uma validação escrita em C#, para o que os atributos
// não conseguem expressar (aqui: CADA elemento da 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: o método retorna os erros um a um
yield return new ValidationResult($"unknown color: {color}", [nameof(Color)]);
}
}
}
|
Vamos comentar este código:
- linha 7: a classe implementa a interface [IValidatableObject]: uma validação escrita em [C#] para o que os atributos não conseguem expressar;
- linha 11: [[MinLength(1)]]: a lista deve ter pelo menos um elemento;
- linhas 14–18: o método [Validate], chamado pela validação depois dos atributos, verifica cada cor. Ele devolve um erro ([ValidationResult]) para cada cor desconhecida, indicando o campo em questão. [yield return] devolve os erros um a um, sem criar uma lista.
A action [Action03] do controller recebe um [ChoiceModel] e devolve o conteúdo dele junto com o estado da validação:
| 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. Exemplo 11: Parâmetros de uma requisição POST
Um formulário HTML enviado pelo método POST coloca seus campos no corpo da requisição, não na URL. O arquivo [Controllers/PostController.cs]:
| using System.Text.Json;
using Example11.Models;
using Microsoft.AspNetCore.Mvc;
namespace Example11.Controllers;
[Route("post")]
public class PostController : Controller
{
// os campos de um formulário HTML (corpo 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()),
};
}
// um corpo JSON: [FromBody] o desserializa
[HttpPost("action02")]
public object Action02([FromBody] JsonElement body)
{
return new { receivedType = Request.ContentType, body };
}
// um único campo do formulário: [FromForm]
[HttpPost("action03")]
public string Action03([FromForm] string? name)
{
return $"name = [{name}]";
}
// os campos do formulário, vinculados e validados pela classe 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),
};
}
}
|
Vamos analisar este código:
- linhas 12–17: [Request.Form] contém os campos de um formulário HTML (corpo do tipo [application/x-www-form-urlencoded]), sem nenhum binding ou conversão. [Request.ContentType] é o tipo do corpo;
- linhas 23–25: [[FromBody]] instrui o sistema a ler o corpo da requisição como um documento JSON (é isso que um cliente [JavaScript] envia). [JsonElement] representa qualquer documento JSON; poderia ter sido declarada uma classe;
- linhas 30–32: [[FromForm]]: um campo do formulário;
- linhas 37–43: o formulário inteiro, vinculado e validado pela classe [PersonModel] do Exemplo 08.
A opção [-d] do [curl] envia uma requisição POST com um corpo no formato de um formulário 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"}}
|
O mesmo conteúdo no 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}}
|
(no [Windows], digite [-d "{\"name\":\"martin\",\"age\":42}"] no prompt de comando). A idade é uma string no primeiro caso (um formulário HTML transporta apenas texto) e um número no segundo. Uma action [[FromBody]] rejeita um corpo que não esteja no formato JSON, devolvendo um erro 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
|
As outras duas 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"]}
|
Uma action POST devolve o código de status 200, assim como uma action GET (o [NestJS], por outro lado, devolvia 201 por padrão). Em uma aplicação HTML, uma action POST responde com uma página (o formulário reexibido) ou com um redirecionamento (veja o Exemplo 20).
3.6. Exemplo 12: Binding e validação personalizados
É possível estender o model binding e a validação. O estudo de caso faz uso moderado desses recursos, mas entendê-los ajuda a compreender como o [ASP.NET Core] funciona.
| 12-custom-binding/
├── Binding/
│ ├── DateFrBinder.cs
│ ├── LanguageBinder.cs
│ └── NoSpaceAttribute.cs
├── Controllers/
│ └── ExamplesController.cs
├── appsettings.json
├── Example12.csproj
└── Program.cs
|
3.6.1. Um model binder: DateFrBinder
Um model binder é o objeto que constrói o valor de um parâmetro a partir da requisição. O [ASP.NET Core] fornece model binders para todos os tipos comuns; você pode escrever os seus. O arquivo [Binding/DateFrBinder.cs]:
| using System.Globalization;
using Microsoft.AspNetCore.Mvc.ModelBinding;
namespace Example12.Binding;
// um "model binder": transforma uma data francesa "23/09/2026" em um DateOnly
public class DateFrBinder : IModelBinder
{
public Task BindModelAsync(ModelBindingContext context)
{
// o valor bruto, encontrado na URL, no formulário, na rota...
var raw = context.ValueProvider.GetValue(context.ModelName).FirstValue;
if (DateOnly.TryParseExact(raw, "dd/MM/yyyy", CultureInfo.InvariantCulture, DateTimeStyles.None, out var date))
{
// sucesso: o valor que a action receberá
context.Result = ModelBindingResult.Success(date);
}
else
{
// falha: um erro no ModelState ("31/02/2026" também é rejeitada)
context.ModelState.AddModelError(context.ModelName, $"[{raw}] is not a valid dd/mm/yyyy date");
}
return Task.CompletedTask;
}
}
|
- linha 7: um model binder implementa a interface [IModelBinder];
- linha 9: o método [BindModelAsync] recebe o contexto de binding: o nome do parâmetro ([ModelName]), as fontes de valores ([ValueProvider]: a URL, o formulário, a rota...), [ModelState]...;
- linha 12: o valor bruto do parâmetro ([FirstValue]: o primeiro, se houver vários);
- linhas 13–16: [DateOnly.TryParseExact] converte uma string no formato [dd/mm/yyyy] para [DateOnly] (uma data sem hora) e devolve [false] se isso for impossível, inclusive para uma data que não existe (31/02/2026). Em caso de sucesso, [ModelBindingResult.Success(date)] fornece o valor que a action receberá;
- linha 21: se a operação falhar, um erro é adicionado a [ModelState];
- linha 23: o método é assíncrono por natureza ([Task]), mas não há nada a esperar: ele devolve uma tarefa que já foi concluída.
3.6.2. Um segundo model binder: LanguageBinder
Um parâmetro pode vir de outro lugar que não a URL ou o formulário. O arquivo [Binding/LanguageBinder.cs]:
| using Microsoft.AspNetCore.Mvc.ModelBinding;
namespace Example12.Binding;
// o idioma preferido do navegador, lido do cabeçalho
// "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;
}
}
|
- linha 11: o cabeçalho [Accept-Language], que especifica os idiomas preferidos do usuário;
- linhas 12–13: as duas primeiras letras do primeiro idioma. [first[..2]] é um intervalo ([range]): os caracteres de índices 0 e 1.
3.6.3. Um atributo de validação: [NoSpace]
O arquivo [Binding/NoSpaceAttribute.cs]:
| using System.ComponentModel.DataAnnotations;
namespace Example12.Binding;
// um atributo de validação "caseiro": [NoSpace]
public class NoSpaceAttribute : ValidationAttribute
{
public NoSpaceAttribute() : base("the {0} field must not contain any space")
{
}
public override bool IsValid(object? value)
{
// null é aceito: exigi-lo é tarefa de [Required]
return value is not string text || !text.Contains(' ');
}
}
|
- linha 6: um atributo de validação herda de [ValidationAttribute]. Por convenção, o nome de uma classe de atributo termina com [Attribute], sufixo que é omitido na prática: [[NoSpace]];
- linha 8: a mensagem de erro padrão, passada à classe pai. [{0}] será substituído pelo nome do campo;
- linhas 12–15: a regra. [value is not string text]: se o valor não for uma string ([null], por exemplo), ele é aceito; caso contrário, é atribuído à variável [text], que não deve conter nenhum espaço. O estudo de caso tem um atributo desse tipo: [[OneOf]].
3.6.4. O controller
O arquivo [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: um 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: um parâmetro que não vem da URL, mas de um cabeçalho
[HttpGet("hello")]
public string Hello([ModelBinder(typeof(LanguageBinder))] string language)
{
return language == "en" ? "Hello!" : "Bonjour !";
}
// /examples/search?keyword=aspnet: um atributo de validação 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}]");
}
}
|
- linha 11: o atributo [[ModelBinder]] especifica o model binder a ser usado para esse parâmetro;
- linha 15: uma data inválida resulta em um erro 400, com a mensagem do model binder;
- linha 22: o parâmetro [language] é fornecido pelo segundo model binder;
- linha 29: um atributo de validação também pode ser aplicado diretamente a um parâmetro de action.
Os 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!
|
(A opção [-H] do [curl] adiciona um cabeçalho à requisição)
| 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 um espaço em uma URL)
3.6.5. Conclusão
O modelo da action é construído pelo model binding a partir da requisição: parâmetros de rota, URL, campos de formulário, corpo JSON e cabeçalhos. Os valores são convertidos para os tipos dos parâmetros e depois validados com base nos atributos. O resultado dessas duas etapas é armazenado em [ModelState]. Para um servidor JSON, [[ApiController]] rejeita automaticamente um modelo inválido; para uma aplicação HTML, a própria action testa [ModelState.IsValid] (exemplo 09) para que o formulário possa ser reexibido. Esse é o assunto do próximo capítulo.