Enlace de modelos en ASP.NET CoreModel Binding in ASP.NET Core

En este artículo se explica qué es el enlace de modelos, cómo funciona y cómo personalizar su comportamiento.This article explains what model binding is, how it works, and how to customize its behavior.

Vea o descargue el código de ejemplo (cómo descargarlo).View or download sample code (how to download).

Qué es el enlace de modelosWhat is Model binding

Los controladores y Razor Pages trabajan con datos procedentes de solicitudes HTTP.Controllers and Razor pages work with data that comes from HTTP requests. Por ejemplo, los datos de ruta pueden proporcionar una clave de registro y los campos de formulario publicados pueden proporcionar valores para las propiedades del modelo.For example, route data may provide a record key, and posted form fields may provide values for the properties of the model. La escritura de código para recuperar cada uno de estos valores y convertirlos de cadenas a tipos de .NET sería tediosa y propensa a errores.Writing code to retrieve each of these values and convert them from strings to .NET types would be tedious and error-prone. El enlace de modelos automatiza este proceso.Model binding automates this process. El sistema de enlace de modelos:The model binding system:

  • Recupera datos de diversos orígenes, como datos de ruta, campos de formulario y cadenas de consulta.Retrieves data from various sources such as route data, form fields, and query strings.
  • Proporciona los datos a los controladores y Razor Pages en parámetros de método y propiedades públicas.Provides the data to controllers and Razor pages in method parameters and public properties.
  • Convierte datos de cadena en tipos de .NET.Converts string data to .NET types.
  • Actualiza las propiedades de tipos complejos.Updates properties of complex types.

EjemploExample

Imagine que tiene el siguiente método de acción:Suppose you have the following action method:

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

Y que la aplicación recibe una solicitud con esta dirección URL:And the app receives a request with this URL:

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

El enlace de modelos realiza los pasos siguientes después de que el sistema de enrutamiento selecciona el método de acción:Model binding goes though the following steps after the routing system selects the action method:

  • Busca el primer parámetro de GetByID, un entero denominado id.Finds the first parameter of GetByID, an integer named id.
  • Examina los orígenes disponibles en la solicitud HTTP y busca id = "2" en los datos de ruta.Looks through the available sources in the HTTP request and finds id = "2" in route data.
  • Convierte la cadena "2" en el entero 2.Converts the string "2" into integer 2.
  • Busca el siguiente parámetro de GetByID, un valor booleano denominado dogsOnly.Finds the next parameter of GetByID, a boolean named dogsOnly.
  • Examina los orígenes y busca "DogsOnly=true" en la cadena de consulta.Looks through the sources and finds "DogsOnly=true" in the query string. La coincidencia de nombres no distingue mayúsculas de minúsculas.Name matching is not case-sensitive.
  • Convierte la cadena "true" en un valor booleano true.Converts the string "true" into boolean true.

Después, el marco llama al método GetById y pasa 2 para el parámetro id y true para el parámetro dogsOnly.The framework then calls the GetById method, passing in 2 for the id parameter, and true for the dogsOnly parameter.

En el ejemplo anterior, los destinos de enlace de modelos son parámetros de método que son tipos simples.In the preceding example, the model binding targets are method parameters that are simple types. Los destinos también pueden ser las propiedades de un tipo complejo.Targets may also be the properties of a complex type. Después de que cada propiedad se haya enlazado correctamente, se produce la validación de modelos para esa propiedad.After each property is successfully bound, model validation occurs for that property. El registro de qué datos se han enlazado al modelo y los errores de enlace o validación se almacenan en ControllerBase.ModelState o 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 averiguar si este proceso se ha realizado correctamente, la aplicación comprueba la marca ModelState.IsValid.To find out if this process was successful, the app checks the ModelState.IsValid flag.

DestinosTargets

El enlace de modelos intenta encontrar valores para los tipos de destinos siguientes:Model binding tries to find values for the following kinds of targets:

  • Parámetros del método de acción de controlador al que se enruta una solicitud.Parameters of the controller action method that a request is routed to.
  • Parámetros del método de controlador de Razor Pages al que se enruta una solicitud.Parameters of the Razor Pages handler method that a request is routed to.
  • Propiedades públicas de un controlador o una clase PageModel, si se especifican mediante atributos.Public properties of a controller or PageModel class, if specified by attributes.

Atributo [BindProperty][BindProperty] attribute

Se puede aplicar a una propiedad pública de un controlador o una clase PageModel para hacer que el enlace de modelos tenga esa propiedad 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

Disponible en ASP.NET 2.1 Core y versiones posteriores.Available in ASP.NET Core 2.1 and later. Se pueden aplicar a un controlador o una clase PageModel para indicar al enlace de modelos que seleccione como destino todas las propiedades públicas de la clase: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; }

Enlace de modelos para solicitudes HTTP GETModel binding for HTTP GET requests

De forma predeterminada, las propiedades no se enlazan para las solicitudes HTTP GET.By default, properties are not bound for HTTP GET requests. Normalmente, todo lo que necesita para una solicitud GET es un parámetro de id. de registro.Typically, all you need for a GET request is a record ID parameter. El id. de registro se usa para buscar el elemento en la base de datos.The record ID is used to look up the item in the database. Por tanto, no es necesario enlazar una propiedad que contiene una instancia del modelo.Therefore, there is no need to bind a property that holds an instance of the model. En escenarios donde quiera propiedades enlazadas a datos de las solicitudes GET, establezca la propiedad SupportsGet en 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; }

OrígenesSources

De forma predeterminada, el enlace de modelos obtiene datos en forma de pares clave-valor de los siguientes orígenes de una solicitud 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 formularioForm fields
  2. El cuerpo de la solicitud (para controladores que tienen el atributo [ApiController]).The request body (For controllers that have the [ApiController] attribute.)
  3. Datos de rutaRoute data
  4. Parámetros de cadena de consultaQuery string parameters
  5. Archivos cargadosUploaded files

Para cada parámetro o propiedad de destino, se examinan los orígenes en el orden indicado en esta lista.For each target parameter or property, the sources are scanned in the order indicated in this list. Hay algunas excepciones:There are a few exceptions:

  • Los datos de ruta y los valores de cadena de consulta solo se usan para tipos simples.Route data and query string values are used only for simple types.
  • Los archivos cargados solo se enlazan a tipos de destino que implementan IFormFile o IEnumerable<IFormFile>.Uploaded files are bound only to target types that implement IFormFile or IEnumerable<IFormFile>.

Si el comportamiento predeterminado no proporciona los resultados adecuados, puede usar uno de los atributos siguientes para especificar el origen que se va a usar para cualquier destino dado.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.

Estos atributos:These attributes:

  • Se agregan de forma individual a las propiedades del modelo (no a la clase de modelo), como en el ejemplo siguiente: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, acepte un valor de nombre de modelo en el constructor.Optionally accept a model name value in the constructor. Esta opción se proporciona en caso de que el nombre de la propiedad no coincida con el valor de la solicitud.This option is provided in case the property name doesn't match the value in the request. Por ejemplo, es posible que el valor de la solicitud sea un encabezado con un guion en el nombre, como en el ejemplo siguiente: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

Los datos del cuerpo de la solicitud se analizan mediante formateadores de entrada específicos para el tipo de contenido de la solicitud.The request body data is parsed by using input formatters specific to the content type of the request. Los formateadores de entrada se explican más adelante en este artículo.Input formatters are explained later in this article.

No aplique [FromBody] a más de un parámetro por método de acción.Don't apply [FromBody] to more than one parameter per action method. El runtime de ASP.NET Core delega la responsabilidad de leer la secuencia de solicitudes al formateador de entrada.The ASP.NET Core runtime delegates the responsibility of reading the request stream to the input formatter. Una vez que se ha leído la secuencia de solicitudes, deja de estar disponible para una nueva lectura con el fin de enlazar otros parámetros [FromBody].Once the request stream is read, it's no longer available to be read again for binding other [FromBody] parameters.

Orígenes adicionalesAdditional sources

Los proveedores de valores proporcionan datos de origen al sistema de enlace de modelos.Source data is provided to the model binding system by value providers. Puede escribir y registrar proveedores de valores personalizados que obtienen datos de otros orígenes para el enlace de modelos.You can write and register custom value providers that get data for model binding from other sources. Por ejemplo, es posible que le interesen datos de cookies o del estado de sesión.For example, you might want data from cookies or session state. Para obtener datos desde un origen nuevo:To get data from a new source:

  • Cree una clase que implemente IValueProvider.Create a class that implements IValueProvider.
  • Cree una clase que implemente IValueProviderFactory.Create a class that implements IValueProviderFactory.
  • Registre la clase de generador en Startup.ConfigureServices.Register the factory class in Startup.ConfigureServices.

En la aplicación de ejemplo se incluye un proveedor de valores y un generador que obtiene valores de cookies.The sample app includes a value provider and factory example that gets values from cookies. Este es el código de registro de 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);

En el código mostrado, el proveedor de valor personalizado se coloca después de todos los proveedores de valor integrados.The code shown puts the custom value provider after all the built-in value providers. Para que sea el primero en la lista, llame a Insert(0, new CookieValueProviderFactory()) en lugar de a Add.To make it the first in the list, call Insert(0, new CookieValueProviderFactory()) instead of Add.

No hay origen para una propiedad de modeloNo source for a model property

De forma predeterminada, si no se encuentra ningún valor para una propiedad de modelo no se crea un error de estado del modelo.By default, a model state error isn't created if no value is found for a model property. La propiedad se establece en NULL o en un valor predeterminado:The property is set to null or a default value:

  • Los tipos simples que aceptan valores NULL se establecen en null.Nullable simple types are set to null.
  • Los tipos de valor que no aceptan valores NULL se establecen en default(T).Non-nullable value types are set to default(T). Por ejemplo, un parámetro int id se establece en 0.For example, a parameter int id is set to 0.
  • Para los tipos complejos, el enlace de modelos crea una instancia mediante el constructor predeterminado, sin establecer propiedades.For complex Types, model binding creates an instance by using the default constructor, without setting properties.
  • Las matrices se establecen en Array.Empty<T>(), salvo las matrices byte[], que se establecen en null.Arrays are set to Array.Empty<T>(), except that byte[] arrays are set to null.

Si el estado del modelo se debe invalidar cuando no se encuentra nada en los campos de formulario para una propiedad de modelo, use el atributo [BindRequired].If model state should be invalidated when nothing is found in form fields for a model property, use the [BindRequired] attribute.

Tenga en cuenta que este comportamiento de [BindRequired] se aplica al enlace de modelos desde datos de formulario publicados, no a los datos JSON o XML del cuerpo de una solicitud.Note that this [BindRequired] behavior applies to model binding from posted form data, not to JSON or XML data in a request body. Los datos del cuerpo de la solicitud se controlan mediante formateadores de entrada.Request body data is handled by input formatters.

Errores de la conversión de tiposType conversion errors

Si se encuentra un origen pero no se puede convertir al tipo de destino, el estado del modelo se marca como no válido.If a source is found but can't be converted into the target type, model state is flagged as invalid. El parámetro o la propiedad de destino se establece en NULL o en un valor predeterminado, como se ha indicado en la sección anterior.The target parameter or property is set to null or a default value, as noted in the previous section.

En un controlador de API que tenga el atributo [ApiController], el estado de modelo no válido genera una respuesta HTTP 400 automática.In an API controller that has the [ApiController] attribute, invalid model state results in an automatic HTTP 400 response.

En una página de Razor, se vuelve a mostrar la página con un mensaje de error: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");
}

La validación del lado cliente detecta la mayoría de los datos incorrectos que en otros casos se enviarían a un formulario de Razor Pages.Client-side validation catches most bad data that would otherwise be submitted to a Razor Pages form. Esta validación dificulta que se pueda desencadenar el código resaltado anterior.This validation makes it hard to trigger the preceding highlighted code. En la aplicación de ejemplo se incluye un botón Submit with Invalid Date (Enviar con fecha no válida) que agrega datos incorrectos al campo Hire Date (Fecha de contratación) y envía el formulario.The sample app includes a Submit with Invalid Date button that puts bad data in the Hire Date field and submits the form. Este botón muestra cómo funciona el código para volver a mostrar la página cuando se producen errores de conversión de datos.This button shows how the code for redisplaying the page works when data conversion errors occur.

Cuando el código anterior vuelve a mostrar la página, no se muestra la entrada no válida en el campo de formulario.When the page is redisplayed by the preceding code, the invalid input is not shown in the form field. El motivo es que la propiedad de modelo se ha establecido en NULL o en un valor predeterminado.This is because the model property has been set to null or a default value. La entrada no válida sí aparece en un mensaje de error.The invalid input does appear in an error message. Pero si quiere volver a mostrar los datos incorrectos en el campo de formulario, considere la posibilidad de convertir la propiedad de modelo en una cadena y realizar la conversión de datos de forma manual.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.

Se recomienda la misma estrategia si no quiere que los errores de conversión de tipo generen errores de estado de modelo.The same strategy is recommended if you don't want type conversion errors to result in model state errors. En ese caso, convierta la propiedad de modelo en una cadena.In that case, make the model property a string.

Tipos simplesSimple types

Los tipos simples a los que el enlazador de modelos puede convertir las cadenas de origen incluyen los siguientes:The simple types that the model binder can convert source strings into include the following:

Tipos complejosComplex types

Un tipo complejo debe tener un constructor público predeterminado y propiedades grabables públicas para enlazar.A complex type must have a public default constructor and public writable properties to bind. Cuando se produce el enlace de modelos, se crea una instancia de la clase con el constructor predeterminado público.When model binding occurs, the class is instantiated using the public default constructor.

Para cada propiedad del tipo complejo, el enlace de modelos busca entre los orígenes el patrón de nombre prefijo.nombre_de_propiedad.For each property of the complex type, model binding looks through the sources for the name pattern prefix.property_name. Si no se encuentra nada, solo busca nombre_de_propiedad sin el prefijo.If nothing is found, it looks for just property_name without the prefix.

Para el enlace a un parámetro, el prefijo es el nombre del parámetro.For binding to a parameter, the prefix is the parameter name. Para el enlace a una propiedad pública PageModel, el prefijo es el nombre de la propiedad pública.For binding to a PageModel public property, the prefix is the public property name. Algunos atributos tienen una propiedad Prefix que permite invalidar el uso predeterminado del nombre de parámetro o propiedad.Some attributes have a Prefix property that lets you override the default usage of parameter or property name.

Por ejemplo, imagine que el tipo complejo es la clase Instructor siguiente: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; }
}

Prefijo = nombre del parámetroPrefix = parameter name

Si el modelo que se va a enlazar es un parámetro denominado instructorToUpdate:If the model to be bound is a parameter named instructorToUpdate:

public IActionResult OnPost(int? id, Instructor instructorToUpdate)

El enlace de modelos se inicia mediante el examen de los orígenes para la clave instructorToUpdate.ID.Model binding starts by looking through the sources for the key instructorToUpdate.ID. Si no se encuentra, busca ID sin un prefijo.If that isn't found, it looks for ID without a prefix.

Prefijo = nombre de propiedadPrefix = property name

Si el modelo que se va a enlazar es una propiedad denominada Instructor del controlador o la clase PageModel:If the model to be bound is a property named Instructor of the controller or PageModel class:

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

El enlace de modelos se inicia mediante el examen de los orígenes para la clave Instructor.ID.Model binding starts by looking through the sources for the key Instructor.ID. Si no se encuentra, busca ID sin un prefijo.If that isn't found, it looks for ID without a prefix.

Prefijo personalizadoCustom prefix

Si el modelo que se va a enlazar es un parámetro denominado instructorToUpdate y un atributo Bind, especifica Instructor como el prefijo: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)

El enlace de modelos se inicia mediante el examen de los orígenes para la clave Instructor.ID.Model binding starts by looking through the sources for the key Instructor.ID. Si no se encuentra, busca ID sin un prefijo.If that isn't found, it looks for ID without a prefix.

Atributos para destinos de tipo complejoAttributes for complex type targets

Existen varios atributos integrados para controlar el enlace de modelos de tipos complejos:Several built-in attributes are available for controlling model binding of complex types:

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

Nota

Estos atributos afectan al enlace de modelos cuando el origen de los valores son datos de formulario publicados.These attributes affect model binding when posted form data is the source of values. No afectan a los formateadores de entrada, que procesan los cuerpos de la solicitud JSON y XML publicados.They do not affect input formatters, which process posted JSON and XML request bodies. Los formateadores de entrada se explican más adelante en este artículo.Input formatters are explained later in this article.

Vea también la explicación del atributo [Required] en Validación de modelos.See also the discussion of the [Required] attribute in Model validation.

Atributo [BindRequired][BindRequired] attribute

Solo se puede aplicar a propiedades del modelo, no a parámetros de método.Can only be applied to model properties, not to method parameters. Hace que el enlace de modelos agregue un error de estado de modelo si no se puede realizar el enlace para la propiedad de un modelo.Causes model binding to add a model state error if binding cannot occur for a model's property. Por ejemplo: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

Solo se puede aplicar a propiedades del modelo, no a parámetros de método.Can only be applied to model properties, not to method parameters. Impide que el enlace de modelos establezca la propiedad de un modelo.Prevents model binding from setting a model's property. Por ejemplo:Here's an example:

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

Atributo [Bind][Bind] attribute

Se puede aplicar a una clase o un parámetro de método.Can be applied to a class or a method parameter. Especifica qué propiedades de un modelo se deben incluir en el enlace de modelos.Specifies which properties of a model should be included in model binding.

En el ejemplo siguiente, solo se enlazan las propiedades especificadas del modelo Instructor cuando se llama a cualquier método de acción o controlador: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

En el ejemplo siguiente, solo se enlazan las propiedades especificadas del modelo Instructor cuando se llama al método OnPost: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)

El atributo [Bind] se puede usar para protegerse de la publicación excesiva en escenarios de creación.The [Bind] attribute can be used to protect against overposting in create scenarios. No funciona bien en escenarios de edición porque las propiedades excluidas se establecen en NULL o en un valor predeterminado en lugar de mantenerse sin cambios.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 defenderse de la publicación excesiva, se recomiendan modelos de vista en lugar del atributo [Bind].For defense against overposting, view models are recommended rather than the [Bind] attribute. Para más información, vea Nota de seguridad sobre la publicación excesiva.For more information, see Security note about overposting.

ColeccionesCollections

Para los destinos que son colecciones de tipos simples, el enlace de modelos busca coincidencias con nombre_de_parámetro o nombre_de_propiedad.For targets that are collections of simple types, model binding looks for matches to parameter_name or property_name. Si no se encuentra ninguna coincidencia, busca uno de los formatos admitidos sin el prefijo.If no match is found, it looks for one of the supported formats without the prefix. Por ejemplo:For example:

  • Imagine que el parámetro que se va a enlazar es una matriz llamada selectedCourses:Suppose the parameter to be bound is an array named selectedCourses:

    public IActionResult OnPost(int? id, int[] selectedCourses)
    
  • Los datos de cadena de consulta o formulario pueden estar en uno de los formatos siguientes: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
    
  • El formato siguiente solo se admite en datos de formulario:The following format is supported only in form data:

    selectedCourses[]=1050&selectedCourses[]=2000
    
  • Para todos los formatos de ejemplo anteriores, el enlace de modelos pasa una matriz de dos elementos al 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

    Los formatos de datos que usan números de subíndice (... [0] ... [1] ...) deben asegurarse de que se numeran de forma secuencial a partir de cero.Data formats that use subscript numbers (... [0] ... [1] ...) must ensure that they are numbered sequentially starting at zero. Si hay algún hueco en la numeración de los subíndices, se omiten todos los elementos que aparecen después del hueco.If there are any gaps in subscript numbering, all items after the gap are ignored. Por ejemplo, si los subíndices son 0 y 2 en lugar de 0 y 1, se omite el segundo elemento.For example, if the subscripts are 0 and 2 instead of 0 and 1, the second item is ignored.

DiccionariosDictionaries

Para los destinos Dictionary, el enlace de modelos busca coincidencias con nombre_de_parámetro o nombre_de_propiedad.For Dictionary targets, model binding looks for matches to parameter_name or property_name. Si no se encuentra ninguna coincidencia, busca uno de los formatos admitidos sin el prefijo.If no match is found, it looks for one of the supported formats without the prefix. Por ejemplo:For example:

  • Imagine que el parámetro de destino es un elemento Dictionary<int, string> denominado selectedCourses:Suppose the target parameter is a Dictionary<int, string> named selectedCourses:

    public IActionResult OnPost(int? id, Dictionary<int, string> selectedCourses)
    
  • Los datos de cadena de consulta o de formulario publicados pueden ser similares a uno de los ejemplos siguientes: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 los formatos de ejemplo anteriores, el enlace de modelos pasa un diccionario de dos elementos al 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 datos especialesSpecial data types

Hay algunos tipos de datos especiales que el enlace de modelos puede controlar.There are some special data types that model binding can handle.

IFormFile e IFormFileCollectionIFormFile and IFormFileCollection

Un archivo cargado incluido en la solicitud HTTP.An uploaded file included in the HTTP request. También se admite IEnumerable<IFormFile> para varios archivos.Also supported is IEnumerable<IFormFile> for multiple files.

CancellationTokenCancellationToken

se usa para cancelar la actividad en controladores asincrónicos.Used to cancel activity in asynchronous controllers.

FormCollectionFormCollection

Se usa para recuperar todos los valores de los datos de formulario publicados.Used to retrieve all the values from posted form data.

Formateadores de entradaInput formatters

Los datos del cuerpo de la solicitud pueden estar en XML, JSON u otro formato.Data in the request body can be in JSON, XML, or some other format. Para analizar estos datos, el enlace de modelos usa un formateador de entrada configurado para controlar un tipo de contenido determinado.To parse this data, model binding uses an input formatter that is configured to handle a particular content type. De forma predeterminada, en ASP.NET Core se incluyen formateadores de entrada basados en JSON para el control de los datos JSON.By default, ASP.NET Core includes JSON based input formatters for handling JSON data. Puede agregar otros formateadores para otros tipos de contenido.You can add other formatters for other content types.

ASP.NET Core selecciona los formateadores de entrada en función del atributo Consumes.ASP.NET Core selects input formatters based on the Consumes attribute. Si no hay ningún atributo, usa el encabezado Content-Type.If no attribute is present, it uses the Content-Type header.

Para usar los formateadores de entrada XML integrados:To use the built-in XML input formatters:

  • Instale el paquete NuGet Microsoft.AspNetCore.Mvc.Formatters.Xml.Install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

  • En Startup.ConfigureServices, llame a AddXmlSerializerFormatters o a 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 el atributo Consumes a las clases de controlador o los métodos de acción que deben esperar XML en el cuerpo de la solicitud.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 más información, vea Introducción de la serialización XML.For more information, see Introducing XML Serialization.

Exclusión de tipos especificados del enlace de modelosExclude specified types from model binding

El comportamiento del enlace de modelos y los sistemas de validación se controla mediante ModelMetadata.The model binding and validation systems' behavior is driven by ModelMetadata. Puede personalizar ModelMetadata mediante la adición de un proveedor de detalles a MvcOptions.ModelMetadataDetailsProviders.You can customize ModelMetadata by adding a details provider to MvcOptions.ModelMetadataDetailsProviders. Los proveedores de detalles integrados están disponibles para deshabilitar el enlace de modelos o la validación para tipos especificados.Built-in details providers are available for disabling model binding or validation for specified types.

Para deshabilitar el enlace de modelos en todos los modelos de un tipo especificado, agregue una instancia de ExcludeBindingMetadataProvider en Startup.ConfigureServices.To disable model binding on all models of a specified type, add an ExcludeBindingMetadataProvider in Startup.ConfigureServices. Por ejemplo, para deshabilitar el enlace de modelos en todos los modelos del 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 deshabilitar la validación en propiedades de un tipo especificado, agregue una instancia de SuppressChildValidationMetadataProvider en Startup.ConfigureServices.To disable validation on properties of a specified type, add a SuppressChildValidationMetadataProvider in Startup.ConfigureServices. Por ejemplo, para deshabilitar la validación en las propiedades de 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);

Enlazadores de modelos personalizadosCustom model binders

Puede ampliar el enlace de modelos si escribe un enlazador de modelos personalizado y usa el atributo [ModelBinder] para seleccionarlo para un destino concreto.You can extend model binding by writing a custom model binder and using the [ModelBinder] attribute to select it for a given target. Más información sobre el enlace de modelos personalizados.Learn more about custom model binding.

Enlace de modelos manualManual model binding

El enlace de modelos se puede invocar de forma manual mediante el método TryUpdateModelAsync.Model binding can be invoked manually by using the TryUpdateModelAsync method. El método se define en las clases ControllerBase y PageModel.The method is defined on both ControllerBase and PageModel classes. Las sobrecargas de método permiten especificar el prefijo y el proveedor de valores que se van a usar.Method overloads let you specify the prefix and value provider to use. El método devuelve false si se produce un error en el enlace de modelos.The method returns false if model binding fails. Por ejemplo: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

El nombre de este atributo sigue el patrón de los atributos de enlace de modelos que especifican un origen de datos.This attribute's name follows the pattern of model binding attributes that specify a data source. Pero no se trata de enlazar datos desde un proveedor de valores.But it's not about binding data from a value provider. Obtiene una instancia de un tipo desde el contenedor de inserción de dependencias.It gets an instance of a type from the dependency injection container. Su objetivo es proporcionar una alternativa a la inserción de constructores cuando se necesita un servicio solo si se llama a un método concreto.Its purpose is to provide an alternative to constructor injection for when you need a service only if a particular method is called.

Recursos adicionalesAdditional resources