Descomplicando o Model Binding no ASP.NET Core

O que é model binding no ASP.NET Core

Controllers e Razor Pages trabalham com dados que chegam em requisições HTTP. Um id pode vir na rota, um filtro pode vir na query string e um cadastro inteiro pode vir em um formulário ou em um JSON.

Escrever código para ler cada valor e convertê-lo de string para o tipo certo seria tedioso e propenso a erros. Por isso, o model binding automatiza esse processo.

Segundo a documentação oficial de model binding, esse sistema realiza quatro tarefas:

• Recupera dados de várias fontes, como rota, campos de formulário e query string
• Entrega esses dados aos controllers e Razor Pages como parâmetros de métodos e propriedades públicas
• Converte strings em tipos .NET
• Atualiza as propriedades de tipos complexos

[HttpGet("{id}")]
public ActionResult<Product> GetById(int id, bool activeOnly)
    => throw new NotImplementedException();

Bind: obtendo propriedades específicas

Durante o desenvolvimento, pode surgir a necessidade de obter apenas algumas propriedades de um objeto e ignorar as outras. Para isso, usamos o atributo [Bind].

[HttpPost]
public IActionResult OnPost([Bind("Name,Email,IsActive")] User user)
    => throw new NotImplementedException();

No código acima, o método OnPost recebe um usuário como parâmetro. Como só temos interesse em três campos, declaramos esses nomes no [Bind].

Com isso, o model binding preenche apenas Name, Email e IsActive. As demais propriedades ficam nulas ou recebem o valor padrão do tipo.

O atributo também pode decorar a própria classe. Nesse caso, a restrição vale para qualquer action que receba aquele tipo.

[Bind("Name,Email,IsActive")]
public class User
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public bool IsActive { get; set; }
    public DateTime? LastUpdateDate { get; set; }
}

FromQuery: model binding com a query string

Antes de obter valores da query string, vale deixar claro o que ela é. A query string, ou cadeia de caracteres de consulta, é um modelo para atribuir valores a parâmetros diretamente na URL.

https://yourdomain.com/users/search?Name=John&Email=mail@mail.com&IsActive=false

[HttpGet("search")]
public IActionResult Search([FromQuery] User user)
    => throw new NotImplementedException();

FromRoute: valores dos dados de rota

Aqui também recuperamos dados da URL, mas de uma forma diferente do [FromQuery]. Em vez de pares de chave e valor, o dado faz parte do próprio caminho.

https://yourdomain.com/users/mail@mail.com

Para recuperar o endereço de e-mail informado nessa URL, usamos o [FromRoute].

[HttpGet("users/{email}")]
public IActionResult GetByEmail([FromRoute] string email)
    => throw new NotImplementedException();

O atributo [HttpGet] recebe um modelo de rota com o segmento {email}. Então, o model binding associa esse segmento ao parâmetro de mesmo nome.

Também é possível refinar a definição da rota com restrições, como {id:int} ou {slug:minlength(3)}. Esse assunto merece um artigo próprio, então aqui mantemos o foco no model binding.

FromForm: campos de formulários postados

Como o nome sugere, o [FromForm] recupera valores de um formulário enviado. Seguindo o mesmo padrão dos atributos anteriores, os nomes dos campos precisam coincidir com os nomes das propriedades.

[HttpPost]
public IActionResult Create([FromForm] User user)
    => throw new NotImplementedException();

No HTML, cada input precisa ter o atributo name igual à propriedade correspondente. Se quiser revisar esse lado da história, o artigo sobre formulários no HTML cobre os campos e seus atributos.

<form method="post" action="/users">
    <input name="Name" />
    <input name="Email" type="email" />
    <input name="IsActive" type="checkbox" value="true" />
    <button type="submit">Save</button>
</form>

O [FromForm] é característico de requisições que enviam o conteúdo como application/x-www-form-urlencoded ou multipart/form-data. Por isso, ele quase sempre acompanha o [HttpPost], porque formulários HTML só enviam dados no corpo com o método POST.

Além disso, o [FromForm] também recebe arquivos. Um parâmetro IFormFile avatar lê o arquivo enviado em um campo name="avatar" de um formulário multipart/form-data.

FromBody: model binding com o corpo da requisição

Quando a requisição envia o conteúdo em um formato como JSON, você usa o [FromBody] para recuperar as informações. Veja um exemplo de entrada:

{
  "name": "John Doe",
  "email": "mail@mail.com"
}

A declaração no código para ler esses valores fica assim:

[HttpPost]
public ActionResult<User> Create([FromBody] User user)
    => throw new NotImplementedException();

Nesse caso, o model binding delega a leitura do corpo a um input formatter. Por padrão, o ASP.NET Core usa o System.Text.Json para desserializar o JSON.

O ASP.NET Core configura o System.Text.Json com os padrões web. Na prática, isso significa nomes em camelCase e comparação de propriedades sem diferenciar maiúsculas de minúsculas.

Por isso, a chave name do JSON preenche a propriedade Name da classe sem nenhuma configuração extra. Se o cliente usar outro padrão de nomes, ajuste as opções do serializador ou use [JsonPropertyName] na propriedade.

Outras fontes do model binding

Além dos atributos clássicos, o ASP.NET Core oferece mais duas fontes muito usadas. O [FromHeader] lê valores de headers HTTP, e o [FromServices] injeta um serviço registrado no container.

[HttpGet]
public IActionResult GetGreeting(
    [FromHeader(Name = "Accept-Language")] string language,
    [FromServices] ILogger<UsersController> logger)
{
    logger.LogInformation("Requested language: {Language}", language);
    return Ok();
}

O parâmetro Name resolve casos em que o nome na requisição não pode virar um identificador C#. Um header com hífen, como Accept-Language, é o exemplo clássico.

Se as fontes nativas não bastam, você pode criar um value provider próprio. A documentação mostra, por exemplo, um provider que lê valores de cookies a partir das interfaces IValueProvider e IValueProviderFactory.

Model binding com ApiController

Em controllers marcados com [ApiController], você raramente precisa escrever esses atributos. Isso acontece porque o framework infere a fonte de cada parâmetro.

A inferência segue regras simples:

• Tipos complexos registrados no container de injeção de dependência viram [FromServices]
• Os demais tipos complexos viram [FromBody]
• Parâmetros IFormFile e IFormFileCollection viram [FromForm]
• Nomes que aparecem no template da rota viram [FromRoute]
• Os demais parâmetros simples viram [FromQuery]

Portanto, o model binding de uma API moderna costuma funcionar sem atributo algum. Ainda assim, declarar a fonte deixa o código explícito e evita surpresas quando alguém altera a rota.

Além disso, o [ApiController] devolve automaticamente um 400 quando o ModelState fica inválido. Dessa forma, erros de conversão e de validação chegam ao cliente antes de executar a action.

Model binding de tipos complexos e coleções

Até aqui, vimos de onde vêm os dados. Agora, vale entender como o model binding monta objetos e listas a partir de pares de chave e valor.

[HttpPost]
public IActionResult Update(int? id, User userToUpdate)
    => throw new NotImplementedException();

[HttpPost]
public IActionResult Enroll(int? id, int[] selectedCourses)
    => throw new NotImplementedException();

Quando o model binding não encontra valores

Por padrão, a ausência de um valor não gera erro no ModelState. Nesse caso, o model binding aplica valores padrão:

• Tipos simples anuláveis recebem null
• Um tipo de valor não anulável recebe default(T), então um int id vale 0
• Tipos complexos ganham uma instância criada pelo construtor padrão, sem propriedades preenchidas
• Arrays recebem Array.Empty<T>(), exceto byte[], que fica null

Quando um valor é obrigatório em formulários, use o [BindRequired]. Ele adiciona um erro ao ModelState se o model binding não encontrar a propriedade.

Por outro lado, quando o valor existe mas não pode ser convertido, o ModelState fica inválido. Um texto "abc" enviado para um int, por exemplo, gera um erro de conversão.

Já o [BindNever] faz o caminho oposto. Ele impede que o model binding preencha uma propriedade, o que protege campos como Id em cenários de formulário.

Conclusão

O model binding elimina boa parte do código repetitivo que lê e converte dados de requisições. Com os atributos certos, você define com precisão de onde cada valor vem.

Em resumo, o [Bind] limita propriedades em formulários, o [FromQuery] lê a query string e o [FromRoute] lê segmentos da URL. Já o [FromForm] atende formulários postados, e o [FromBody] cuida de JSON e XML.

Entender essas fontes também ajuda a diagnosticar bugs. Quando um parâmetro chega vazio, quase sempre o model binding está procurando o valor no lugar errado.

Continue lendo

Para seguir estudando ASP.NET Core, veja como configurar logs no ASP.NET com Serilog. Em seguida, pratique tudo isso criando uma API do zero com .NET Core 3.1 e EF Core.

FAQ

O que é model binding no ASP.NET Core?

É o mecanismo que lê dados da rota, da query string, de formulários, de headers e do corpo da requisição. Em seguida, ele converte esses dados em parâmetros e objetos .NET.

Qual a diferença entre FromQuery e FromRoute?

O [FromQuery] lê pares de chave e valor depois do ? na URL. Já o [FromRoute] lê segmentos do próprio caminho definidos no template da rota.

Por que o Bind não funciona com JSON?

O [Bind] atua sobre dados de formulário, e o JSON passa por input formatters que ignoram esse atributo. Para JSON, use um DTO com apenas os campos permitidos.

Posso usar FromBody em dois parâmetros?

Não, porque o corpo da requisição só pode ser lido uma vez. Agrupe os dados em um único objeto e receba esse objeto com [FromBody].

Preciso escrever FromBody em controllers com ApiController?

Não é obrigatório, já que o [ApiController] infere [FromBody] para tipos complexos. Mesmo assim, declarar a fonte deixa o código mais explícito.