Liaison de données dans ASP.NET CoreModel Binding in ASP.NET Core

Cet article explique ce qu’est la liaison de modèle, comment elle fonctionne et comment personnaliser son comportement.This article explains what model binding is, how it works, and how to customize its behavior.

Affichez ou téléchargez un exemple de code (procédure de téléchargement).View or download sample code (how to download).

Description de la liaison de modèleWhat is Model binding

Les contrôleurs et Razor Pages utilisent des données provenant de requêtes HTTP.Controllers and Razor pages work with data that comes from HTTP requests. Par exemple, les données de routage peuvent fournir une clé d’enregistrement, et les champs de formulaire posté peuvent fournir des valeurs pour les propriétés du modèle.For example, route data may provide a record key, and posted form fields may provide values for the properties of the model. L’écriture du code permettant de récupérer chacune de ces valeurs et de les convertir en types .NET à partir de chaînes est fastidieuse et source d’erreurs.Writing code to retrieve each of these values and convert them from strings to .NET types would be tedious and error-prone. La liaison de modèle automatise ce processus.Model binding automates this process. Le système de liaison de modèle :The model binding system:

  • Récupère les données de diverses sources telles que les données de routage, les champs de formulaire et les chaînes de requêteRetrieves data from various sources such as route data, form fields, and query strings.
  • Fournit les données aux contrôleurs et à Razor Pages dans les paramètres de méthode et les propriétés publiquesProvides the data to controllers and Razor pages in method parameters and public properties.
  • Convertit les données de chaîne en types .NETConverts string data to .NET types.
  • Met à jour les propriétés des types complexesUpdates properties of complex types.

ExemplesExample

Supposons que vous ayez la méthode d’action suivante :Suppose you have the following action method:

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

Et que l’application reçoive une requête avec l’URL suivante :And the app receives a request with this URL:

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

La liaison de modèle suit les étapes ci-après une fois que le système de routage a sélectionné la méthode d’action :Model binding goes though the following steps after the routing system selects the action method:

  • Elle recherche le premier paramètre de GetByID, un entier nommé id.Finds the first parameter of GetByID, an integer named id.
  • Elle parcourt les sources disponibles dans la requête HTTP et trouve id = « 2 » dans les données de routage.Looks through the available sources in the HTTP request and finds id = "2" in route data.
  • Elle convertit la chaîne « 2 » en entier 2.Converts the string "2" into integer 2.
  • Elle recherche le paramètre suivant de GetByID, un booléen nommé dogsOnly.Finds the next parameter of GetByID, a boolean named dogsOnly.
  • Elle parcourt les sources et trouve « DogsOnly=true » dans la chaîne de requête.Looks through the sources and finds "DogsOnly=true" in the query string. La mise en correspondance des noms ne respecte pas la casse.Name matching is not case-sensitive.
  • Elle convertit la chaîne « true » en booléen true.Converts the string "true" into boolean true.

Le framework appelle ensuite la méthode GetById, en passant 2 pour le paramètre id, et true pour le paramètre dogsOnly.The framework then calls the GetById method, passing in 2 for the id parameter, and true for the dogsOnly parameter.

Dans l’exemple précédent, les cibles de liaison de modèle sont des paramètres de méthode qui sont des types simples.In the preceding example, the model binding targets are method parameters that are simple types. Les cibles peuvent être également les propriétés d’un type complexe.Targets may also be the properties of a complex type. Une fois chaque propriété correctement liée, la validation du modèle est effectuée pour la propriété concernée.After each property is successfully bound, model validation occurs for that property. L’enregistrement des données liées au modèle (ainsi que des erreurs de liaison ou de validation) est stocké dans 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. Pour savoir si ce processus a abouti, l’application vérifie l’indicateur ModelState.IsValid.To find out if this process was successful, the app checks the ModelState.IsValid flag.

CiblesTargets

La liaison de modèle tente de trouver des valeurs pour les genres de cible suivants :Model binding tries to find values for the following kinds of targets:

  • Paramètres de la méthode d’action de contrôleur vers laquelle une requête est routée.Parameters of the controller action method that a request is routed to.
  • Paramètres de la méthode de gestionnaire Razor Pages vers laquelle une requête est routée.Parameters of the Razor Pages handler method that a request is routed to.
  • Propriétés publiques d’un contrôleur ou d’une classe PageModel, si elles sont spécifiées par des attributs.Public properties of a controller or PageModel class, if specified by attributes.

Attribut [BindProperty][BindProperty] attribute

Peut être appliqué à une propriété publique d’un contrôleur ou à une classe PageModel pour que la liaison de modèle cible cette propriété :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; }

Attribut [BindProperties][BindProperties] attribute

Disponible avec ASP.NET Core 2.1 et les versions ultérieures.Available in ASP.NET Core 2.1 and later. Peut être appliqué à un contrôleur ou à une classe PageModel pour indiquer à la liaison de modèle de cibler toutes les propriétés publiques de la classe :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; }

Liaison de modèle pour les requêtes HTTP GETModel binding for HTTP GET requests

Par défaut, les propriétés ne sont pas liées pour les requêtes HTTP GET.By default, properties are not bound for HTTP GET requests. En règle générale, le paramètre ID d’un enregistrement est tout ce dont vous avez besoin pour une requête GET.Typically, all you need for a GET request is a record ID parameter. L’ID d’enregistrement est utilisé pour rechercher l’élément dans la base de données.The record ID is used to look up the item in the database. Il n’est donc pas nécessaire de lier une propriété qui contient une instance du modèle.Therefore, there is no need to bind a property that holds an instance of the model. Pour les scénarios dans lesquels vous souhaitez que les propriétés soient liées aux données provenant de requêtes GET, affectez à la propriété SupportsGet la valeur 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; }

SourcesSources

Par défaut, la liaison de modèle obtient des données sous la forme de paires clé-valeur à partir des sources suivantes dans une requête HTTP :By default, model binding gets data in the form of key-value pairs from the following sources in an HTTP request:

  1. Champs de formulaireForm fields
  2. Corps de la requête (pour les contrôleurs ayant l’attribut [ApiController].)The request body (For controllers that have the [ApiController] attribute.)
  3. Données de routeRoute data
  4. Paramètres de la chaîne de requêteQuery string parameters
  5. Fichiers chargésUploaded files

Pour chaque paramètre ou propriété cible, les sources sont analysées dans l’ordre indiqué dans cette liste.For each target parameter or property, the sources are scanned in the order indicated in this list. Il existe quelques exceptions :There are a few exceptions:

  • Les données de routage et les valeurs de chaîne de requête sont utilisées uniquement pour les types simples.Route data and query string values are used only for simple types.
  • Les fichiers chargés sont liés uniquement aux types cibles qui implémentent IFormFile ou IEnumerable<IFormFile>.Uploaded files are bound only to target types that implement IFormFile or IEnumerable<IFormFile>.

Si le comportement par défaut ne donne pas les bons résultats, vous pouvez vous servir de l’un des attributs suivants pour spécifier la source à utiliser pour une cible donnée.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.

  • [FromQuery] - Obtient les valeurs à partir de la chaîne de requête.[FromQuery] - Gets values from the query string.
  • [FromRoute] - Obtient les valeurs à partir des données de routage.[FromRoute] - Gets values from route data.
  • [FromForm] - Obtient les valeurs à partir des champs de formulaire postés.[FromForm] - Gets values from posted form fields.
  • [FromBody] - Obtient les valeurs à partir du corps de la requête.[FromBody] - Gets values from the request body.
  • [FromHeader] - Obtient les valeurs à partir des en-têtes HTTP.[FromHeader] - Gets values from HTTP headers.

Ces attributs :These attributes:

  • Sont ajoutés aux propriétés du modèle individuellement (et non à la classe de modèle), comme dans l’exemple suivant :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; }
    
  • Acceptent éventuellement une valeur de nom de modèle dans le constructeur.Optionally accept a model name value in the constructor. Cette option est fournie au cas où le nom de propriété ne correspondrait pas à la valeur de la requête.This option is provided in case the property name doesn't match the value in the request. Par exemple, la valeur de la requête peut être un en-tête avec un trait d’union dans son nom, comme dans l’exemple suivant :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)
    

Attribut [FromBody][FromBody] attribute

Les données du corps de la requête sont analysées à l’aide de formateurs d’entrée spécifiques au type de contenu de la requête.The request body data is parsed by using input formatters specific to the content type of the request. Les formateurs d’entrée sont décrits plus loin dans cet article.Input formatters are explained later in this article.

N’appliquez pas [FromBody] à plus d’un paramètre par méthode d’action.Don't apply [FromBody] to more than one parameter per action method. Le runtime ASP.NET Core délègue la responsabilité de la lecture du flux de requête au formateur d’entrée.The ASP.NET Core runtime delegates the responsibility of reading the request stream to the input formatter. Une fois le flux de requête lu, il ne peut plus être relu pour lier d’autres paramètres [FromBody].Once the request stream is read, it's no longer available to be read again for binding other [FromBody] parameters.

Sources supplémentairesAdditional sources

Les données sources sont fournies au système de liaison de modèle par les fournisseurs de valeurs.Source data is provided to the model binding system by value providers. Vous pouvez écrire et inscrire des fournisseurs de valeurs personnalisés qui obtiennent des données de liaison de modèle à partir d’autres sources.You can write and register custom value providers that get data for model binding from other sources. Par exemple, vous pouvez obtenir des données provenant de cookies ou de l’état de session.For example, you might want data from cookies or session state. Pour obtenir des données provenant d’une nouvelle source :To get data from a new source:

  • Créez une classe qui implémente IValueProvider.Create a class that implements IValueProvider.
  • Créez une classe qui implémente IValueProviderFactory.Create a class that implements IValueProviderFactory.
  • Inscrivez la classe de fabrique dans Startup.ConfigureServices.Register the factory class in Startup.ConfigureServices.

L’exemple d’application comprend un exemple de fournisseur de valeurs et de fabrique, qui permet de récupérer les valeurs provenant des cookies.The sample app includes a value provider and factory example that gets values from cookies. Voici le code d’inscription dans 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);

Le code affiché place le fournisseur de valeurs personnalisé après tous les fournisseurs de valeurs intégrés.The code shown puts the custom value provider after all the built-in value providers. Pour en faire le premier fournisseur de la liste, appelez Insert(0, new CookieValueProviderFactory()) à la place de Add.To make it the first in the list, call Insert(0, new CookieValueProviderFactory()) instead of Add.

Aucune source pour une propriété de modèleNo source for a model property

Par défaut, aucune erreur d’état de modèle n’est créée, s’il n’existe aucune valeur de propriété de modèle.By default, a model state error isn't created if no value is found for a model property. La propriété a une valeur null ou une valeur par défaut :The property is set to null or a default value:

  • Les types simples Nullable ont une valeur null.Nullable simple types are set to null.
  • Les types valeur non Nullable ont la valeur default(T).Non-nullable value types are set to default(T). Par exemple, un paramètre int id a la valeur 0.For example, a parameter int id is set to 0.
  • Pour les types complexes, la liaison de modèle crée une instance à l’aide du constructeur par défaut, sans définir de propriétés.For complex Types, model binding creates an instance by using the default constructor, without setting properties.
  • Les tableaux ont la valeur Array.Empty<T>(), sauf les tableaux byte[] qui ont une valeur null.Arrays are set to Array.Empty<T>(), except that byte[] arrays are set to null.

Si l’état de modèle doit être rendu non valide quand les champs de formulaire d’une propriété de modèle ne contiennent rien, utilisez l’attribut [BindRequired].If model state should be invalidated when nothing is found in form fields for a model property, use the [BindRequired] attribute.

Notez que ce comportement de [BindRequired] s’applique à la liaison de modèle des données de formulaire postées, et non aux données JSON ou XML d’un corps de requête.Note that this [BindRequired] behavior applies to model binding from posted form data, not to JSON or XML data in a request body. Les données du corps de requête sont prises en charge par les formateurs d’entrée.Request body data is handled by input formatters.

Erreurs de conversion de typeType conversion errors

Si une source est localisée mais qu’elle ne peut pas être convertie vers le type cible, l’état du modèle est marqué comme étant non valide.If a source is found but can't be converted into the target type, model state is flagged as invalid. Le paramètre ou la propriété cible a une valeur null ou une valeur par défaut, comme indiqué dans la section précédente.The target parameter or property is set to null or a default value, as noted in the previous section.

Dans un contrôleur d’API ayant l’attribut [ApiController], un état de modèle non valide entraîne une réponse HTTP 400 automatique.In an API controller that has the [ApiController] attribute, invalid model state results in an automatic HTTP 400 response.

Dans une page Razor Pages, réaffichez la page avec un message d’erreur :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 validation côté client intercepte la plupart des données incorrectes qui sont envoyées à un formulaire Razor Pages.Client-side validation catches most bad data that would otherwise be submitted to a Razor Pages form. Cette validation rend difficile le déclenchement du code en surbrillance indiqué plus haut.This validation makes it hard to trigger the preceding highlighted code. L’exemple d’application comprend un bouton Submit with Invalid Date (Envoyer avec une date non valide), qui place les données incorrectes dans le champ Hire Date (Date d’embauche) et envoie le formulaire.The sample app includes a Submit with Invalid Date button that puts bad data in the Hire Date field and submits the form. Ce bouton montre comment fonctionne le code permettant de réafficher la page quand des erreurs de conversion de données se produisent.This button shows how the code for redisplaying the page works when data conversion errors occur.

Quand la page est réaffichée par le code précédent, l’entrée non valide n’est pas visible dans le champ de formulaire.When the page is redisplayed by the preceding code, the invalid input is not shown in the form field. En effet, la propriété de modèle à une valeur null ou une valeur par défaut.This is because the model property has been set to null or a default value. L’entrée non valide apparaît dans un message d’erreur.The invalid input does appear in an error message. Toutefois, si vous souhaitez réafficher les données incorrectes dans le champ de formulaire, transformez la propriété de modèle en chaîne et procédez à la conversion des données manuellement.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.

La même stratégie est recommandée si vous ne souhaitez pas que les erreurs de conversion de type entraînent des erreurs d’état de modèle.The same strategy is recommended if you don't want type conversion errors to result in model state errors. Dans ce cas, transformez la propriété de modèle en chaîne.In that case, make the model property a string.

Types simplesSimple types

Les types simples que le lieur de modèle peut convertir en chaînes sources sont les suivants :The simple types that the model binder can convert source strings into include the following:

Types complexesComplex types

Un type complexe doit avoir un constructeur public par défaut et des propriétés publiques accessibles en écriture à lier.A complex type must have a public default constructor and public writable properties to bind. Quand la liaison de modèle se produit, la classe est instanciée à l’aide du constructeur public par défaut.When model binding occurs, the class is instantiated using the public default constructor.

Pour chaque propriété du type complexe, la liaison de modèle recherche dans les sources le modèle de nom préfixe.nom_propriété.For each property of the complex type, model binding looks through the sources for the name pattern prefix.property_name. Si rien n’est trouvé, elle recherche uniquement nom_propriété sans le préfixe.If nothing is found, it looks for just property_name without the prefix.

Dans le cas d’une liaison à un paramètre, le préfixe représente le nom du paramètre.For binding to a parameter, the prefix is the parameter name. Dans le cas d’une liaison à une propriété publique PageModel, le préfixe représente le nom de la propriété publique.For binding to a PageModel public property, the prefix is the public property name. Certains attributs ont une propriété Prefix qui vous permet de remplacer l’utilisation par défaut du nom de paramètre ou de propriété.Some attributes have a Prefix property that lets you override the default usage of parameter or property name.

Par exemple, supposons que le type complexe corresponde à la classe Instructor suivante :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; }
}

Préfixe = nom de paramètrePrefix = parameter name

Si le modèle à lier est un paramètre nommé instructorToUpdate :If the model to be bound is a parameter named instructorToUpdate:

public IActionResult OnPost(int? id, Instructor instructorToUpdate)

La liaison de modèle commence par rechercher dans les sources la clé instructorToUpdate.ID.Model binding starts by looking through the sources for the key instructorToUpdate.ID. Si elle est introuvable, elle recherche ID sans préfixe.If that isn't found, it looks for ID without a prefix.

Préfixe = nom de propriétéPrefix = property name

Si le modèle à lier est une propriété nommée Instructor du contrôleur ou de la 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; }

La liaison de modèle commence par rechercher dans les sources la clé Instructor.ID.Model binding starts by looking through the sources for the key Instructor.ID. Si elle est introuvable, elle recherche ID sans préfixe.If that isn't found, it looks for ID without a prefix.

Préfixe personnaliséCustom prefix

Si le modèle à lier est un paramètre nommé instructorToUpdate et si un attribut Bind spécifie Instructor en tant que préfixe :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)

La liaison de modèle commence par rechercher dans les sources la clé Instructor.ID.Model binding starts by looking through the sources for the key Instructor.ID. Si elle est introuvable, elle recherche ID sans préfixe.If that isn't found, it looks for ID without a prefix.

Attributs des cibles de type complexeAttributes for complex type targets

Plusieurs attributs intégrés sont disponibles pour contrôler la liaison de modèle des types complexes :Several built-in attributes are available for controlling model binding of complex types:

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

Notes

Ces attributs affectent la liaison de modèle quand les données de formulaire postées représentent la source des valeurs.These attributes affect model binding when posted form data is the source of values. Ils n’affectent pas les formateurs d’entrée, qui traitent les corps de requête JSON et XML postés.They do not affect input formatters, which process posted JSON and XML request bodies. Les formateurs d’entrée sont décrits plus loin dans cet article.Input formatters are explained later in this article.

Consultez également la discussion sur l’attribut [Required] dans Validation de modèle.See also the discussion of the [Required] attribute in Model validation.

Attribut [BindRequired][BindRequired] attribute

Il s’applique uniquement aux propriétés de modèle, pas aux paramètres de méthode.Can only be applied to model properties, not to method parameters. Il oblige la liaison de modèle à ajouter une erreur d’état de modèle si la liaison est impossible pour la propriété d’un modèle.Causes model binding to add a model state error if binding cannot occur for a model's property. Voici un exemple :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; }

Attribut [BindNever][BindNever] attribute

Il s’applique uniquement aux propriétés de modèle, pas aux paramètres de méthode.Can only be applied to model properties, not to method parameters. Il empêche la liaison de modèle de définir la propriété d’un modèle.Prevents model binding from setting a model's property. Voici un exemple :Here's an example:

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

Attribut [Bind][Bind] attribute

Il peut être appliqué à une classe ou à un paramètre de méthode.Can be applied to a class or a method parameter. Il spécifie les propriétés d’un modèle à inclure dans la liaison de modèle.Specifies which properties of a model should be included in model binding.

Dans l’exemple suivant, seules les propriétés spécifiées du modèle Instructor sont liées quand une méthode de gestionnaire ou une méthode d’action est appelée :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

Dans l’exemple suivant, seules les propriétés spécifiées du modèle Instructor sont liées quand la méthode OnPost est appelée :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)

Vous pouvez utiliser l’attribut [Bind] pour éviter le surpostage dans les scénarios de création.The [Bind] attribute can be used to protect against overposting in create scenarios. Il ne fonctionne pas bien dans les scénarios de modification, car les propriétés exclues ont une valeur null ou une valeur par défaut au lieu de rester inchangées.It doesn't work well in edit scenarios because excluded properties are set to null or a default value instead of being left unchanged. Pour empêcher le surpostage, il est recommandé d’utiliser des modèles de vues à la place de l’attribut [Bind].For defense against overposting, view models are recommended rather than the [Bind] attribute. Pour plus d’informations, consultez Remarque sur la sécurité concernant le surpostage.For more information, see Security note about overposting.

CollectionsCollections

Pour les cibles qui sont des collections de types simples, la liaison de modèle recherche les correspondances avec nom_paramètre ou nom_propriété.For targets that are collections of simple types, model binding looks for matches to parameter_name or property_name. Si aucune correspondance n’est localisée, elle recherche l’un des formats pris en charge sans le préfixe.If no match is found, it looks for one of the supported formats without the prefix. Par exemple :For example:

  • Supposons que le paramètre à lier soit un tableau nommé selectedCourses :Suppose the parameter to be bound is an array named selectedCourses:

    public IActionResult OnPost(int? id, int[] selectedCourses)
    
  • Les données de formulaire ou de chaîne de requête peuvent avoir l’un des formats suivants :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
    
  • Le format suivant est pris en charge uniquement dans les données de formulaire :The following format is supported only in form data:

    selectedCourses[]=1050&selectedCourses[]=2000
    
  • Pour tous les exemples de formats précédents, la liaison de modèle passe un tableau de deux éléments au paramètre 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

    Les formats de données qui utilisent des nombres en indice (... [0] ... [1] ...) doivent être impérativement numérotés de manière séquentielle à partir de zéro.Data formats that use subscript numbers (... [0] ... [1] ...) must ensure that they are numbered sequentially starting at zero. S’il existe des vides dans la numérotation en indice, tous les éléments suivants sont ignorés.If there are any gaps in subscript numbering, all items after the gap are ignored. Par exemple, si les indices sont 0 et 2 au lieu de 0 et 1, le second élément est ignoré.For example, if the subscripts are 0 and 2 instead of 0 and 1, the second item is ignored.

DictionnairesDictionaries

Pour les cibles Dictionary, la liaison de modèle recherche les correspondances avec nom_paramètre ou nom_propriété.For Dictionary targets, model binding looks for matches to parameter_name or property_name. Si aucune correspondance n’est localisée, elle recherche l’un des formats pris en charge sans le préfixe.If no match is found, it looks for one of the supported formats without the prefix. Par exemple :For example:

  • Supposons que le paramètre cible soit un Dictionary<int, string> nommé selectedCourses :Suppose the target parameter is a Dictionary<int, string> named selectedCourses:

    public IActionResult OnPost(int? id, Dictionary<int, string> selectedCourses)
    
  • Les données de chaîne de requête ou de formulaire posté peuvent ressembler à l’un des exemples suivants :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
    
  • Pour tous les exemples de formats précédents, la liaison de modèle passe un dictionnaire de deux éléments au paramètre 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"

Types de données spéciauxSpecial data types

Certains types de données spéciaux peuvent être pris en charge par la liaison de modèle.There are some special data types that model binding can handle.

IFormFile et IFormFileCollectionIFormFile and IFormFileCollection

Fichier chargé inclus dans la requête HTTP.An uploaded file included in the HTTP request. IEnumerable<IFormFile> est également pris en charge pour plusieurs fichiers.Also supported is IEnumerable<IFormFile> for multiple files.

CancellationTokenCancellationToken

utilisé pour annuler l’activité dans les contrôleurs asynchrones.Used to cancel activity in asynchronous controllers.

FormCollectionFormCollection

Permet de récupérer toutes les valeurs des données de formulaire posté.Used to retrieve all the values from posted form data.

Formateurs d’entréeInput formatters

Les données contenues dans le corps de la requête peuvent être au format JSON, XML ou tout autre format.Data in the request body can be in JSON, XML, or some other format. Pour analyser ces données, la liaison de modèle utilise un formateur d’entrée configuré pour prendre en charge un type de contenu particulier.To parse this data, model binding uses an input formatter that is configured to handle a particular content type. Par défaut, ASP.NET Core inclut des formateurs d’entrée basés sur le format JSON pour prendre en charge les données JSON.By default, ASP.NET Core includes JSON based input formatters for handling JSON data. Vous pouvez ajouter d’autres formateurs pour d’autres types de contenu.You can add other formatters for other content types.

ASP.NET Core sélectionne les formateurs d’entrée en fonction de l’attribut Consumes.ASP.NET Core selects input formatters based on the Consumes attribute. Si aucun attribut n’est présent, il utilise l’en-tête Content-Type.If no attribute is present, it uses the Content-Type header.

Pour utiliser les formateurs d’entrée XML intégrés :To use the built-in XML input formatters:

  • Installez le package NuGet Microsoft.AspNetCore.Mvc.Formatters.Xml.Install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

  • Dans Startup.ConfigureServices, appelez 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);
    
  • Appliquez l’attribut Consumes aux classes de contrôleur ou aux méthodes d’action devant contenir des données XML dans le corps de la requête.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)
    

    Pour plus d’informations, consultez Introduction à la sérialisation XML.For more information, see Introducing XML Serialization.

Exclure les types spécifiés de la liaison de modèleExclude specified types from model binding

Le comportement de la liaison de modèle et du système de validation est régi par ModelMetadata.The model binding and validation systems' behavior is driven by ModelMetadata. Vous pouvez personnaliser ModelMetadata en ajoutant un fournisseur de détails à MvcOptions.ModelMetadataDetailsProviders.You can customize ModelMetadata by adding a details provider to MvcOptions.ModelMetadataDetailsProviders. Des fournisseurs de détails intégrés sont disponibles pour désactiver la liaison de modèle ou la validation des types spécifiés.Built-in details providers are available for disabling model binding or validation for specified types.

Pour désactiver la liaison de modèle sur tous les modèles d’un type spécifique, ajoutez ExcludeBindingMetadataProvider dans Startup.ConfigureServices.To disable model binding on all models of a specified type, add an ExcludeBindingMetadataProvider in Startup.ConfigureServices. Par exemple, pour désactiver la liaison de modèle sur tous les modèles de type 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);

Pour désactiver la validation des propriétés d’un type spécifique, ajoutez SuppressChildValidationMetadataProvider dans Startup.ConfigureServices.To disable validation on properties of a specified type, add a SuppressChildValidationMetadataProvider in Startup.ConfigureServices. Par exemple, pour désactiver la validation sur les propriétés de type 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);

Lieurs de modèles personnalisésCustom model binders

Vous pouvez étendre la liaison de modèle en écrivant un lieur de modèle personnalisé et en utilisant l’attribut [ModelBinder] afin de le sélectionner pour une cible donnée.You can extend model binding by writing a custom model binder and using the [ModelBinder] attribute to select it for a given target. Découvrez plus d’informations sur la liaison de modèle personnalisée.Learn more about custom model binding.

Liaison de modèle manuelleManual model binding

Vous pouvez appeler la liaison de modèle manuellement à l’aide de la méthode TryUpdateModelAsync.Model binding can be invoked manually by using the TryUpdateModelAsync method. La méthode est définie sur les classes ControllerBase et PageModel.The method is defined on both ControllerBase and PageModel classes. Les surcharges de méthode vous permettent de spécifier le préfixe et le fournisseur de valeurs à utiliser.Method overloads let you specify the prefix and value provider to use. La méthode retourne false en cas d’échec de la liaison de modèle.The method returns false if model binding fails. Voici un exemple :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();

Attribut [FromServices][FromServices] attribute

Le nom de cet attribut suit le modèle des attributs de liaison de modèle qui spécifient une source de données.This attribute's name follows the pattern of model binding attributes that specify a data source. Toutefois, il ne permet pas de lier les données d’un fournisseur de valeurs.But it's not about binding data from a value provider. Il obtient une instance d’un type à partir du conteneur d’injection de dépendances.It gets an instance of a type from the dependency injection container. Son objectif est de fournir une alternative à l’injection de constructeurs quand vous avez besoin d’un service uniquement si une méthode particulière est appelée.Its purpose is to provide an alternative to constructor injection for when you need a service only if a particular method is called.

Ressources supplémentairesAdditional resources