Model binding no ASP.NET CoreModel Binding in ASP.NET Core

Este artigo explica o que é model binding, como ele funciona e como personalizar seu comportamento.This article explains what model binding is, how it works, and how to customize its behavior.

Exibir ou baixar um código de exemplo (como baixar).View or download sample code (how to download).

O que é o model bindingWhat is Model binding

Controladores e Razor Pages funcionam com os dados provenientes de solicitações HTTP.Controllers and Razor pages work with data that comes from HTTP requests. Por exemplo, dados de rota podem fornecer uma chave de registro e campos de formulário postados podem fornecer valores para as propriedades do modelo.For example, route data may provide a record key, and posted form fields may provide values for the properties of the model. Escrever código para recuperar cada um desses valores e convertê-los de cadeias de caracteres em tipos .NET seria uma tarefa entediante e propensa a erro.Writing code to retrieve each of these values and convert them from strings to .NET types would be tedious and error-prone. O model binding automatiza esse processo.Model binding automates this process. O sistema de model binding:The model binding system:

  • Recupera dados de várias fontes, como dados de rota, campos de formulário e cadeias de caracteres de consulta.Retrieves data from various sources such as route data, form fields, and query strings.
  • Fornece os dados a controladores e Razor Pages em parâmetros de método e propriedades públicas.Provides the data to controllers and Razor pages in method parameters and public properties.
  • Converte dados de cadeia de caracteres em tipos .NET.Converts string data to .NET types.
  • Atualiza as propriedades de tipos complexos.Updates properties of complex types.

ExemploExample

Suponha que você tenha o seguinte método de ação:Suppose you have the following action method:

[HttpGet("{id}")]
public ActionResult<Pet> GetById(int id, bool dogsOnly)

E o aplicativo receba uma solicitação com esta URL:And the app receives a request with this URL:

http://contoso.com/api/pets/2?DogsOnly=true

O model binding passa pelas etapas a seguir depois que o sistema de roteamento seleciona o método de ação:Model binding goes though the following steps after the routing system selects the action method:

  • Localiza o primeiro parâmetro de GetByID, um número inteiro denominado id.Finds the first parameter of GetByID, an integer named id.
  • Examina as fontes disponíveis na solicitação HTTP e localiza id = "2" em dados de rota.Looks through the available sources in the HTTP request and finds id = "2" in route data.
  • Converte a cadeia de caracteres "2" em inteiro 2.Converts the string "2" into integer 2.
  • Localiza o próximo parâmetro de GetByID, um booliano chamado dogsOnly.Finds the next parameter of GetByID, a boolean named dogsOnly.
  • Examina as fontes e localiza "DogsOnly=true" na cadeia de consulta.Looks through the sources and finds "DogsOnly=true" in the query string. A correspondência de nomes não diferencia maiúsculas de minúsculas.Name matching is not case-sensitive.
  • Converte a cadeia de caracteres "true" no booliano true.Converts the string "true" into boolean true.

A estrutura então chama o método GetById, passando 2 para o parâmetro id e true para o parâmetro dogsOnly.The framework then calls the GetById method, passing in 2 for the id parameter, and true for the dogsOnly parameter.

No exemplo anterior, os destinos do model binding são parâmetros de método que são tipos simples.In the preceding example, the model binding targets are method parameters that are simple types. Destinos também podem ser as propriedades de um tipo complexo.Targets may also be the properties of a complex type. Depois de cada propriedade ser associada com êxito, a validação do modelo ocorre para essa propriedade.After each property is successfully bound, model validation occurs for that property. O registro de quais dados estão associados ao modelo, além de quaisquer erros de validação ou de associação, é armazenado em ControllerBase.ModelState ou PageModel.ModelState.The record of what data is bound to the model, and any binding or validation errors, is stored in ControllerBase.ModelState or PageModel.ModelState. Para descobrir se esse processo foi bem-sucedido, o aplicativo verifica o sinalizador ModelState.IsValid.To find out if this process was successful, the app checks the ModelState.IsValid flag.

DestinosTargets

O model binding tenta encontrar valores para os seguintes tipos de destinos:Model binding tries to find values for the following kinds of targets:

  • Parâmetros do método de ação do controlador para o qual uma solicitação é roteada.Parameters of the controller action method that a request is routed to.
  • Os parâmetros do método do manipulador do Razor Pages para o qual uma solicitação é roteada.Parameters of the Razor Pages handler method that a request is routed to.
  • Propriedades públicas de um controlador ou classe PageModel, se especificadas por atributos.Public properties of a controller or PageModel class, if specified by attributes.

Atributo [BindProperty][BindProperty] attribute

Pode ser aplicado a uma propriedade pública de um controlador ou classe PageModel para fazer o model binding ter essa propriedade como destino:Can be applied to a public property of a controller or PageModel class to cause model binding to target that property:

public class EditModel : InstructorsPageModel
{
    public EditModel() : base()
    {
    }

    [BindProperty]
    public Instructor Instructor { get; set; }

Atributo [BindProperties][BindProperties] attribute

Disponível no ASP.NET Core 2.1 e posteriores.Available in ASP.NET Core 2.1 and later. Pode ser aplicado a um controlador ou classe PageModel para informar o model binding para ter todas as propriedades públicas da classe como destino:Can be applied to a controller or PageModel class to tell model binding to target all public properties of the class:

[BindProperties(SupportsGet=true)]
public class CreateModel : InstructorsPageModel
{
    public CreateModel() : base()
    {
    }

    public Instructor Instructor { get; set; }

Model binding para solicitações HTTP GETModel binding for HTTP GET requests

Por padrão, as propriedades não são vinculadas para solicitações HTTP GET.By default, properties are not bound for HTTP GET requests. Normalmente, tudo o que você precisa para uma solicitação GET é um parâmetro de ID de registro.Typically, all you need for a GET request is a record ID parameter. A ID do registro é usada para pesquisar o item no banco de dados.The record ID is used to look up the item in the database. Portanto, não é necessário associar uma propriedade que contém uma instância do modelo.Therefore, there is no need to bind a property that holds an instance of the model. Em cenários em que você deseja associar propriedades a dados de solicitações GET, defina a propriedade SupportsGet como true:In scenarios where you do want properties bound to data from GET requests, set the SupportsGet property to true:

[BindProperty(Name ="ai_user", SupportsGet = true)]
public string ApplicationInsightsCookie { get; set; }

OrigensSources

Por padrão, o model binding obtém dados na forma de pares chave-valor das seguintes fontes em uma solicitação HTTP:By default, model binding gets data in the form of key-value pairs from the following sources in an HTTP request:

  1. Campos de formulárioForm fields
  2. O corpo da solicitação (para controladores que têm o atributo [ApiController]).The request body (For controllers that have the [ApiController] attribute.)
  3. Dados de rotaRoute data
  4. Parâmetros de cadeia de caracteres de consultaQuery string parameters
  5. Arquivos carregadosUploaded files

Para cada propriedade ou parâmetro de destino, as fontes são verificadas na ordem indicada nesta lista.For each target parameter or property, the sources are scanned in the order indicated in this list. Há algumas exceções:There are a few exceptions:

  • Os valores de cadeia de caracteres de consulta e dados de rota são usados apenas para tipos simples.Route data and query string values are used only for simple types.
  • Arquivos carregados são associados apenas a tipos de destino que implementam IFormFile ou IEnumerable<IFormFile>.Uploaded files are bound only to target types that implement IFormFile or IEnumerable<IFormFile>.

Se o comportamento padrão não obtiver os resultados certos, você poderá usar um dos seguintes atributos para especificar a origem a ser usada para qualquer determinado destino.If the default behavior doesn't give the right results, you can use one of the following attributes to specify the source to use for any given target.

Esses atributos:These attributes:

  • São adicionados às propriedades de modelo individualmente (não à classe de modelo), como no exemplo a seguir:Are added to model properties individually (not to the model class), as in the following example:

    public class Instructor
    {
        public int ID { get; set; }
    
        [FromQuery(Name ="Note")]
        public string NoteFromQueryString { get; set; }
    
  • Opcionalmente, aceite um valor de nome de modelo no construtor.Optionally accept a model name value in the constructor. Essa opção é fornecida caso o nome da propriedade não corresponda ao valor na solicitação.This option is provided in case the property name doesn't match the value in the request. Por exemplo, o valor na solicitação pode ser um cabeçalho com um hífen em seu nome, como no exemplo a seguir:For instance, the value in the request might be a header with a hyphen in its name, as in the following example:

    public void OnGet([FromHeader(Name="Accept-Language")] string language)
    

Atributo [FromBody][FromBody] attribute

Os dados do corpo da solicitação são analisados usando formatadores de entrada específicos do tipo de conteúdo da solicitação.The request body data is parsed by using input formatters specific to the content type of the request. O formatadores de entrada são explicados posteriormente neste artigo.Input formatters are explained later in this article.

Não aplique [FromBody] a mais de um parâmetro por método de ação.Don't apply [FromBody] to more than one parameter per action method. O tempo de execução do ASP.NET Core delega a responsabilidade de ler o fluxo da solicitação ao formatador de entrada.The ASP.NET Core runtime delegates the responsibility of reading the request stream to the input formatter. Depois que o fluxo da solicitação é lido, ele não fica mais disponível para ser lido novamente para associar outros parâmetros [FromBody].Once the request stream is read, it's no longer available to be read again for binding other [FromBody] parameters.

Fontes adicionaisAdditional sources

Os dados de origem são fornecidos ao sistema de model binding pelos provedores de valor.Source data is provided to the model binding system by value providers. Você pode escrever e registrar provedores de valor personalizados que obtêm dados para model binding de outras fontes.You can write and register custom value providers that get data for model binding from other sources. Por exemplo, talvez você queira dados de cookies ou estado de sessão.For example, you might want data from cookies or session state. Para obter dados de uma nova fonte:To get data from a new source:

  • Crie uma classe que implementa IValueProvider.Create a class that implements IValueProvider.
  • Crie uma classe que implementa IValueProviderFactory.Create a class that implements IValueProviderFactory.
  • Registre a classe de alocador em Startup.ConfigureServices.Register the factory class in Startup.ConfigureServices.

O aplicativo de exemplo inclui um provedor de valor e um exemplo de alocador que obtém valores de cookies.The sample app includes a value provider and factory example that gets values from cookies. Aqui está o código de registro em Startup.ConfigureServices:Here's the registration code in Startup.ConfigureServices:

services.AddMvc(options =>
{
    options.ValueProviderFactories.Add(new CookieValueProviderFactory());
    options.ModelMetadataDetailsProviders.Add(
        new ExcludeBindingMetadataProvider(typeof(System.Version)));
    options.ModelMetadataDetailsProviders.Add(
        new SuppressChildValidationMetadataProvider(typeof(System.Guid)));
})
.AddXmlSerializerFormatters()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

O código mostrado coloca o provedor de valor personalizado depois de todos os provedores de valor internos.The code shown puts the custom value provider after all the built-in value providers. Para torná-lo o primeiro na lista, chame Insert(0, new CookieValueProviderFactory()), em vez de Add.To make it the first in the list, call Insert(0, new CookieValueProviderFactory()) instead of Add.

Nenhuma fonte para uma propriedade de modeloNo source for a model property

Por padrão, um erro de estado de modelo não será criado se nenhum valor for encontrado para uma propriedade de modelo.By default, a model state error isn't created if no value is found for a model property. A propriedade é definida como null ou um valor padrão:The property is set to null or a default value:

  • Tipos simples anuláveis definidos como null.Nullable simple types are set to null.
  • Tipos de valor não anuláveis são definidos como default(T).Non-nullable value types are set to default(T). Por exemplo, um parâmetro int id é definido como 0.For example, a parameter int id is set to 0.
  • Para tipos complexos, o model binding cria uma instância usando o construtor padrão sem definir propriedades.For complex Types, model binding creates an instance by using the default constructor, without setting properties.
  • As matrizes são definidas como Array.Empty<T>(), exceto que matrizes byte[] são definidas como null.Arrays are set to Array.Empty<T>(), except that byte[] arrays are set to null.

Se o estado do modelo precisar ser invalidado quando nada for encontrado em campos de formulário para uma propriedade de modelo, use o atributo [BindRequired].If model state should be invalidated when nothing is found in form fields for a model property, use the [BindRequired] attribute.

Observe que este comportamento [BindRequired] se aplica ao model binding de dados de formulário postados, não a dados JSON ou XML em um corpo da solicitação.Note that this [BindRequired] behavior applies to model binding from posted form data, not to JSON or XML data in a request body. Dados do corpo da solicitação são tratados pelos formatadores de entrada.Request body data is handled by input formatters.

Erros de conversão de tiposType conversion errors

Se uma fonte for encontrada, mas não puder ser convertida no tipo de destino, o estado do modelo será sinalizado como inválido.If a source is found but can't be converted into the target type, model state is flagged as invalid. O parâmetro ou a propriedade de destino é definido como nulo ou um valor padrão, conforme observado na seção anterior.The target parameter or property is set to null or a default value, as noted in the previous section.

Em um controlador de API que tem o atributo [ApiController], um estado de modelo inválido resulta em uma resposta HTTP 400 automática.In an API controller that has the [ApiController] attribute, invalid model state results in an automatic HTTP 400 response.

Em uma Razor Page, exiba novamente a página com uma mensagem de erro:In a Razor page, redisplay the page with an error message:

public IActionResult OnPost()
{
    if (!ModelState.IsValid)
    {
        return Page();
    }

    _instructorsInMemoryStore.Add(Instructor);
    return RedirectToPage("./Index");
}

Validação no lado do cliente captura a maioria dos dados inválidos que de outra forma seriam enviados a um formulário do Razor Pages.Client-side validation catches most bad data that would otherwise be submitted to a Razor Pages form. Essa validação torna difícil disparar o código realçado anterior.This validation makes it hard to trigger the preceding highlighted code. O aplicativo de exemplo inclui um botão Enviar com Data Inválida que coloca os dados inválidos no campo Data de Contratação e envia o formulário.The sample app includes a Submit with Invalid Date button that puts bad data in the Hire Date field and submits the form. Esse botão mostra como o código para exibir novamente a página funciona quando ocorrem erros de conversão de dados.This button shows how the code for redisplaying the page works when data conversion errors occur.

Quando a página é exibida novamente pelo código anterior, a entrada inválida não é mostrada no campo de formulário.When the page is redisplayed by the preceding code, the invalid input is not shown in the form field. Isso ocorre porque a propriedade do modelo foi definida como nulo ou um valor padrão.This is because the model property has been set to null or a default value. A entrada inválida aparece em uma mensagem de erro.The invalid input does appear in an error message. Porém, se você quiser exibir novamente os dados inválidos no campo de formulário, considere tornar a propriedade do modelo uma cadeia de caracteres e fazer a conversão de dados manualmente.But if you want to redisplay the bad data in the form field, consider making the model property a string and doing the data conversion manually.

A mesma estratégia será recomendada se você não desejar que erros de conversão de tipo resultem em erros de estado de modelo.The same strategy is recommended if you don't want type conversion errors to result in model state errors. Nesse caso, torne a propriedade de modelo uma cadeia de caracteres.In that case, make the model property a string.

Tipos simplesSimple types

Os tipos simples em que o associador de modelos pode converter cadeias de caracteres de origem incluem os seguintes:The simple types that the model binder can convert source strings into include the following:

Tipos complexosComplex types

Um tipo complexo deve ter um construtor padrão público e propriedades públicas graváveis para associar.A complex type must have a public default constructor and public writable properties to bind. Quando ocorre model binding, a classe é instanciada usando o construtor padrão público.When model binding occurs, the class is instantiated using the public default constructor.

Para cada propriedade do tipo complexo, o model binding examina as fontes em busca do nome padrão prefix.property_name.For each property of the complex type, model binding looks through the sources for the name pattern prefix.property_name. Se nada for encontrado, ela procurará apenas property_name sem o prefixo.If nothing is found, it looks for just property_name without the prefix.

Para associação a um parâmetro, o prefixo é o nome do parâmetro.For binding to a parameter, the prefix is the parameter name. Para associação a uma propriedade pública PageModel, o prefixo é o nome da propriedade pública.For binding to a PageModel public property, the prefix is the public property name. Alguns atributos têm uma propriedade Prefix que permite substituir o uso padrão do nome da propriedade ou do parâmetro.Some attributes have a Prefix property that lets you override the default usage of parameter or property name.

Por exemplo, suponha que o tipo complexo seja a seguinte classe Instructor:For example, suppose the complex type is the following Instructor class:

public class Instructor
{
    public int ID { get; set; }
    public string LastName { get; set; }
    public string FirstName { get; set; }
}

Prefixo = nome do parâmetroPrefix = parameter name

Se o modelo a ser associado for um parâmetro chamado instructorToUpdate:If the model to be bound is a parameter named instructorToUpdate:

public IActionResult OnPost(int? id, Instructor instructorToUpdate)

O model binding começa examinando as fontes para a chave instructorToUpdate.ID.Model binding starts by looking through the sources for the key instructorToUpdate.ID. Se ela não for encontrada, procurará ID sem um prefixo.If that isn't found, it looks for ID without a prefix.

Prefixo = nome da propriedadePrefix = property name

Se o modelo a ser associado for uma propriedade chamada Instructor do controlador ou da classe PageModel:If the model to be bound is a property named Instructor of the controller or PageModel class:

[BindProperty]
public Instructor Instructor { get; set; }

O model binding começa examinando as fontes para a chave Instructor.ID.Model binding starts by looking through the sources for the key Instructor.ID. Se ela não for encontrada, procurará ID sem um prefixo.If that isn't found, it looks for ID without a prefix.

Prefixo personalizadoCustom prefix

Se o modelo a ser associado for um parâmetro denominado instructorToUpdate e um atributo Bind especificar Instructor como o prefixo:If the model to be bound is a parameter named instructorToUpdate and a Bind attribute specifies Instructor as the prefix:

public IActionResult OnPost(
    int? id, [Bind(Prefix = "Instructor")] Instructor instructorToUpdate)

O model binding começa examinando as fontes para a chave Instructor.ID.Model binding starts by looking through the sources for the key Instructor.ID. Se ela não for encontrada, procurará ID sem um prefixo.If that isn't found, it looks for ID without a prefix.

Atributos para destinos de tipo complexoAttributes for complex type targets

Vários atributos internos estão disponíveis para controlar o model binding de tipos complexos:Several built-in attributes are available for controlling model binding of complex types:

  • [BindRequired]
  • [BindNever]
  • [Bind]

Observação

Esses atributos afetam o model binding quando os dados de formulário postados são a origem dos valores.These attributes affect model binding when posted form data is the source of values. Eles não afetam os formatadores de entrada, que processam corpos de solicitação XML e JSON postados.They do not affect input formatters, which process posted JSON and XML request bodies. O formatadores de entrada são explicados posteriormente neste artigo.Input formatters are explained later in this article.

Veja também a discussão sobre o atributo [Required] em Validação do modelo.See also the discussion of the [Required] attribute in Model validation.

Atributo [BindRequired][BindRequired] attribute

Somente pode ser aplicado às propriedades de modelo, não aos parâmetros do método.Can only be applied to model properties, not to method parameters. Faz com que o model binding adicione um erro de estado de modelo se a associação não puder ocorrer para a propriedade de um modelo.Causes model binding to add a model state error if binding cannot occur for a model's property. Veja um exemplo:Here's an example:

public class InstructorWithCollection
{
    public int ID { get; set; }

    [DataType(DataType.Date)]
    [DisplayFormat(DataFormatString = "{0:yyyy-MM-dd}", ApplyFormatInEditMode = true)]
    [Display(Name = "Hire Date")]
    [BindRequired]
    public DateTime HireDate { get; set; }

Atributo [BindNever][BindNever] attribute

Somente pode ser aplicado às propriedades de modelo, não aos parâmetros do método.Can only be applied to model properties, not to method parameters. Impede que o model binding configure a propriedade de um modelo.Prevents model binding from setting a model's property. Veja um exemplo:Here's an example:

public class InstructorWithDictionary
{
    [BindNever]
    public int ID { get; set; }

Atributo [Bind][Bind] attribute

Pode ser aplicado a uma classe ou a um parâmetro de método.Can be applied to a class or a method parameter. Especifica quais propriedades de um modelo devem ser incluídas no model binding.Specifies which properties of a model should be included in model binding.

No exemplo a seguir, somente as propriedades especificadas do modelo Instructor são associadas quando qualquer método de ação ou o manipulador é chamado:In the following example, only the specified properties of the Instructor model are bound when any handler or action method is called:

[Bind("LastName,FirstMidName,HireDate")]
public class Instructor

No exemplo a seguir, somente as propriedades especificadas do modelo Instructor são associadas quando o método OnPost é chamado:In the following example, only the specified properties of the Instructor model are bound when the OnPost method is called:

[HttpPost]
public IActionResult OnPost([Bind("LastName,FirstMidName,HireDate")] Instructor instructor)

O atributo [Bind] pode ser usado para proteção contra o excesso de postagem cenários de criar.The [Bind] attribute can be used to protect against overposting in create scenarios. Ele não funciona bem em cenários de edição, pois as propriedades excluídas são definidas como nulas ou um valor padrão, em vez de serem deixadas inalteradas.It doesn't work well in edit scenarios because excluded properties are set to null or a default value instead of being left unchanged. Para defesa contra o excesso de postagem, são recomendados modelos de exibição, em vez do atributo [Bind].For defense against overposting, view models are recommended rather than the [Bind] attribute. Para obter mais informações, veja Observação de segurança sobre o excesso de postagem.For more information, see Security note about overposting.

ColeçõesCollections

Para destinos que são coleções de tipos simples, o model binding procura correspondências para parameter_name ou property_name.For targets that are collections of simple types, model binding looks for matches to parameter_name or property_name. Se nenhuma correspondência for encontrada, procurará um dos formatos compatíveis sem o prefixo.If no match is found, it looks for one of the supported formats without the prefix. Por exemplo:For example:

  • Suponha que o parâmetro a ser associado seja uma matriz chamada selectedCourses:Suppose the parameter to be bound is an array named selectedCourses:

    public IActionResult OnPost(int? id, int[] selectedCourses)
    
  • Dados de cadeia de caracteres de consulta ou formulário podem estar em um dos seguintes formatos:Form or query string data can be in one of the following formats:

    selectedCourses=1050&selectedCourses=2000 
    
    selectedCourses[0]=1050&selectedCourses[1]=2000
    
    [0]=1050&[1]=2000
    
    selectedCourses[a]=1050&selectedCourses[b]=2000&selectedCourses.index=a&selectedCourses.index=b
    
    [a]=1050&[b]=2000&index=a&index=b
    
  • O formato a seguir é compatível apenas com os dados de formulário:The following format is supported only in form data:

    selectedCourses[]=1050&selectedCourses[]=2000
    
  • Para todos os formatos do exemplo anterior, o model binding passa uma matriz de dois itens para o parâmetro selectedCourses:For all of the preceding example formats, model binding passes an array of two items to the selectedCourses parameter:

    • selectedCourses[0]=1050selectedCourses[0]=1050
    • selectedCourses[1]=2000selectedCourses[1]=2000

    Formatos de dados que usam números subscritos (... [0]... [1]...) devem garantir que eles estejam numerados em sequência, começando com zero.Data formats that use subscript numbers (... [0] ... [1] ...) must ensure that they are numbered sequentially starting at zero. Se houver quaisquer intervalos na numeração de subscrito, todos os itens após o intervalo serão ignorados.If there are any gaps in subscript numbering, all items after the gap are ignored. Por exemplo, se os subscritos forem 0 e 2, em vez de 0 e 1, o segundo item será ignorado.For example, if the subscripts are 0 and 2 instead of 0 and 1, the second item is ignored.

DicionáriosDictionaries

Para destinos Dictionary, o model binding procura correspondências para parameter_name ou property_name.For Dictionary targets, model binding looks for matches to parameter_name or property_name. Se nenhuma correspondência for encontrada, procurará um dos formatos compatível sem o prefixo.If no match is found, it looks for one of the supported formats without the prefix. Por exemplo:For example:

  • Suponha que o parâmetro de destino seja um Dictionary<int, string> chamado selectedCourses:Suppose the target parameter is a Dictionary<int, string> named selectedCourses:

    public IActionResult OnPost(int? id, Dictionary<int, string> selectedCourses)
    
  • Os dados de cadeia de caracteres de consulta ou formulário postados podem se parecer com um dos exemplos a seguir:The posted form or query string data can look like one of the following examples:

    selectedCourses[1050]=Chemistry&selectedCourses[2000]=Economics
    
    [1050]=Chemistry&selectedCourses[2000]=Economics
    
    selectedCourses[0].Key=1050&selectedCourses[0].Value=Chemistry&
    selectedCourses[1].Key=2000&selectedCourses[1].Value=Economics
    
    [0].Key=1050&[0].Value=Chemistry&[1].Key=2000&[1].Value=Economics
    
  • Para todos os formatos do exemplo anterior, o model binding passa um dicionário de dois itens para o parâmetro selectedCourses:For all of the preceding example formats, model binding passes a dictionary of two items to the selectedCourses parameter:

    • selectedCourses["1050"]="Chemistry"selectedCourses["1050"]="Chemistry"
    • selectedCourses["2000"]="Economics"selectedCourses["2000"]="Economics"

Tipos de dados especiaisSpecial data types

Há alguns tipos de dados especiais com o model binding pode lidar.There are some special data types that model binding can handle.

IFormFile e IFormFileCollectionIFormFile and IFormFileCollection

Um arquivo carregado incluído na solicitação HTTP.An uploaded file included in the HTTP request. Também compatível com IEnumerable<IFormFile> para vários arquivos.Also supported is IEnumerable<IFormFile> for multiple files.

CancellationTokenCancellationToken

usado para cancelar a atividade em controladores assíncronos.Used to cancel activity in asynchronous controllers.

FormCollectionFormCollection

Usado para recuperar todos os valores dos dados de formulário postados.Used to retrieve all the values from posted form data.

Formatadores de entradaInput formatters

Dados no corpo da solicitação podem estar em JSON, XML ou algum outro formato.Data in the request body can be in JSON, XML, or some other format. Para analisar esses dados, o model binding usa um formatador de entrada configurado para lidar com um determinado tipo de conteúdo.To parse this data, model binding uses an input formatter that is configured to handle a particular content type. Por padrão, o ASP.NET Core inclui formatadores de entrada baseados em JSON para lidar com os dados JSON.By default, ASP.NET Core includes JSON based input formatters for handling JSON data. Você pode adicionar outros formatadores para outros tipos de conteúdo.You can add other formatters for other content types.

O ASP.NET Core seleciona formatadores de entrada com base no atributo Consome.ASP.NET Core selects input formatters based on the Consumes attribute. Se nenhum atributo estiver presente, ele usará o cabeçalho Content-Type.If no attribute is present, it uses the Content-Type header.

Para usar os formatadores de entrada XML internos:To use the built-in XML input formatters:

  • Instale o pacote do NuGet Microsoft.AspNetCore.Mvc.Formatters.Xml.Install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

  • Em Startup.ConfigureServices, chame AddXmlSerializerFormatters ou AddXmlDataContractSerializerFormatters.In Startup.ConfigureServices, call AddXmlSerializerFormatters or AddXmlDataContractSerializerFormatters.

    services.AddMvc(options =>
    {
        options.ValueProviderFactories.Add(new CookieValueProviderFactory());
        options.ModelMetadataDetailsProviders.Add(
            new ExcludeBindingMetadataProvider(typeof(System.Version)));
        options.ModelMetadataDetailsProviders.Add(
            new SuppressChildValidationMetadataProvider(typeof(System.Guid)));
    })
    .AddXmlSerializerFormatters()
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    
  • Aplique o atributo Consumes às classes de controlador ou aos métodos de ação que devem esperar XML no corpo da solicitação.Apply the Consumes attribute to controller classes or action methods that should expect XML in the request body.

    [HttpPost]
    [Consumes("application/xml")]
    public ActionResult<Pet> Create(Pet pet)
    

    Para obter mais informações, veja Introdução à serialização XML.For more information, see Introducing XML Serialization.

Excluir tipos especificados do model bindingExclude specified types from model binding

O comportamento do sistema de validação e model binding é orientado pelo ModelMetadata.The model binding and validation systems' behavior is driven by ModelMetadata. Você pode personalizar ModelMetadata adicionando um provedor de detalhes MvcOptions.ModelMetadataDetailsProviders.You can customize ModelMetadata by adding a details provider to MvcOptions.ModelMetadataDetailsProviders. Provedores de detalhes internos estão disponíveis para desabilitar o model binding ou a validação para tipos especificados.Built-in details providers are available for disabling model binding or validation for specified types.

Para desabilitar o model binding em todos os modelos de um tipo especificado, adicione um ExcludeBindingMetadataProvider em Startup.ConfigureServices.To disable model binding on all models of a specified type, add an ExcludeBindingMetadataProvider in Startup.ConfigureServices. Por exemplo, para desabilitar o model binding em todos os modelos do tipo System.Version:For example, to disable model binding on all models of type System.Version:

services.AddMvc(options =>
{
    options.ValueProviderFactories.Add(new CookieValueProviderFactory());
    options.ModelMetadataDetailsProviders.Add(
        new ExcludeBindingMetadataProvider(typeof(System.Version)));
    options.ModelMetadataDetailsProviders.Add(
        new SuppressChildValidationMetadataProvider(typeof(System.Guid)));
})
.AddXmlSerializerFormatters()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

Para desabilitar a validação nas propriedades de um tipo especificado, adicione um SuppressChildValidationMetadataProvider em Startup.ConfigureServices.To disable validation on properties of a specified type, add a SuppressChildValidationMetadataProvider in Startup.ConfigureServices. Por exemplo, para desabilitar a validação nas propriedades do tipo System.Guid:For example, to disable validation on properties of type System.Guid:

services.AddMvc(options =>
{
    options.ValueProviderFactories.Add(new CookieValueProviderFactory());
    options.ModelMetadataDetailsProviders.Add(
        new ExcludeBindingMetadataProvider(typeof(System.Version)));
    options.ModelMetadataDetailsProviders.Add(
        new SuppressChildValidationMetadataProvider(typeof(System.Guid)));
})
.AddXmlSerializerFormatters()
.SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

Associadores de modelos personalizadosCustom model binders

Você pode estender o model binding escrevendo um associador de modelos personalizado e usando o atributo [ModelBinder] para selecioná-la para um determinado destino.You can extend model binding by writing a custom model binder and using the [ModelBinder] attribute to select it for a given target. Saiba mais sobre o model binding personalizado.Learn more about custom model binding.

Model binding manualManual model binding

O model binding pode ser invocado manualmente usando o método TryUpdateModelAsync.Model binding can be invoked manually by using the TryUpdateModelAsync method. O método é definido nas classes ControllerBase e PageModel.The method is defined on both ControllerBase and PageModel classes. Sobrecargas de método permitem que você especifique o provedor de valor e prefixo a ser usado.Method overloads let you specify the prefix and value provider to use. O método retornará false se o model binding falhar.The method returns false if model binding fails. Veja um exemplo:Here's an example:

if (await TryUpdateModelAsync<InstructorWithCollection>(
    newInstructor,
    "Instructor",
    i => i.FirstMidName, i => i.LastName, i => i.HireDate))
{
    _instructorsInMemoryStore.Add(newInstructor);
    return RedirectToPage("./Index");
}
PopulateAssignedCourseData(newInstructor);
return Page();

Atributo [FromServices][FromServices] attribute

O nome do atributo segue o padrão dos atributos de model binding que especificam uma fonte de dados.This attribute's name follows the pattern of model binding attributes that specify a data source. Porém, não se trata de associar dados de um provedor de valor.But it's not about binding data from a value provider. Ele obtém uma instância de um tipo do contêiner de injeção de dependência.It gets an instance of a type from the dependency injection container. Sua finalidade é oferecer uma alternativa à injeção de construtor para quando você precisa de um serviço somente se um determinado método for chamado.Its purpose is to provide an alternative to constructor injection for when you need a service only if a particular method is called.

Recursos adicionaisAdditional resources