Modellbindung in ASP.NET CoreModel Binding in ASP.NET Core

  • 30 Minuten Lesedauer

In diesem Artikel wird erläutert, was Modellbindung ist, wie sie funktioniert, und wie Sie ihr Verhalten anpassen können.This article explains what model binding is, how it works, and how to customize its behavior.

Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).View or download sample code (how to download).

Was ist Modellbindung?What is Model binding

Controller und Razor Seiten arbeiten mit Daten, die aus HTTP-Anforderungen stammen.Controllers and Razor pages work with data that comes from HTTP requests. Routendaten können beispielsweise einen Datensatzschlüssel enthalten, und bereitgestellte Formularfelder können Werte für die Eigenschaften des Modells bereitstellen.For example, route data may provide a record key, and posted form fields may provide values for the properties of the model. Das Schreiben von Code zum Abrufen jedes dieser Werte und deren Konvertierung aus Zeichenfolgen in .NET-Datentypen wäre mühsam und fehleranfällig.Writing code to retrieve each of these values and convert them from strings to .NET types would be tedious and error-prone. Modellbindung automatisiert diesen Vorgang.Model binding automates this process. Das Modellbindungssystem:The model binding system:

  • Ruft Daten aus verschiedenen Quellen ab, z. B. Routendaten, Formularfelder und Abfragezeichenfolgen.Retrieves data from various sources such as route data, form fields, and query strings.
  • Stellt die Daten für Controller und Razor Seiten in Methoden Parametern und öffentlichen Eigenschaften bereit.Provides the data to controllers and Razor pages in method parameters and public properties.
  • Konvertiert Zeichenfolgendaten in .NET-Typen.Converts string data to .NET types.
  • Aktualisiert Eigenschaften komplexer Typen.Updates properties of complex types.

BeispielExample

Angenommen Sie haben die folgende Aktionsmethode:Suppose you have the following action method:

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

Und die App empfängt eine Anforderung mit dieser URL:And the app receives a request with this URL:

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

Die Modellbindung durchläuft die folgenden Schritte, nachdem das Routingsystem die Aktionsmethode ausgewählt hat:Model binding goes through the following steps after the routing system selects the action method:

  • Findet den ersten Parameters von GetByID, eine ganze Zahl namens id.Finds the first parameter of GetByID, an integer named id.
  • Durchsucht die verfügbaren Quellen in der HTTP-Anforderung und findet id = „2“ in den Routendaten.Looks through the available sources in the HTTP request and finds id = "2" in route data.
  • Konvertiert der Zeichenfolge „2“ in die ganze Zahl 2.Converts the string "2" into integer 2.
  • Findet den nächsten Parameter von GetByID, einen booleschen Wert namens dogsOnly.Finds the next parameter of GetByID, a boolean named dogsOnly.
  • Durchsucht die Quellen und findet „DogsOnly=True“ in der Abfragezeichenfolge.Looks through the sources and finds "DogsOnly=true" in the query string. Beim Abgleich von Namen wird die Groß- und Kleinschreibung nicht berücksichtigt.Name matching is not case-sensitive.
  • Konvertiert die Zeichenfolge „true“ in den booleschen Wert true.Converts the string "true" into boolean true.

Das Framework ruft dann die GetById-Methode auf, und übergibt dabei als Eingabe „2“ für den id-Parameter und true für den dogsOnly-Parameter.The framework then calls the GetById method, passing in 2 for the id parameter, and true for the dogsOnly parameter.

Im vorherigen Beispiel sind die Ziele der Modellbindung Methodenparameter, die einfache Typen sind.In the preceding example, the model binding targets are method parameters that are simple types. Ziele können aber auch die Eigenschaften eines komplexen Typs sein.Targets may also be the properties of a complex type. Nachdem jede Eigenschaft erfolgreich gebunden wurde, erfolgt die Modellvalidierung für diese Eigenschaft.After each property is successfully bound, model validation occurs for that property. Der Datensatz darüber, welche Daten an das Modell gebunden sind, sowie mit allen Bindungs- oder Validierungsfehlern wird in ControllerBase.ModelState oder PageModel.ModelState gespeichert.The record of what data is bound to the model, and any binding or validation errors, is stored in ControllerBase.ModelState or PageModel.ModelState. Um herauszufinden, ob dieser Vorgang erfolgreich war, überprüft die App das Flag ModelState.IsValid.To find out if this process was successful, the app checks the ModelState.IsValid flag.

ZieleTargets

Die Modellbindung versucht, Werte für die folgenden Arten von Zielen zu finden:Model binding tries to find values for the following kinds of targets:

  • Parameter der Controlleraktionsmethode, zu der eine Anforderung weitergeleitet wird.Parameters of the controller action method that a request is routed to.
  • Parameter der Razor pages-Handlermethode, an die eine Anforderung weitergeleitet wird.Parameters of the Razor Pages handler method that a request is routed to.
  • Öffentliche Eigenschaften eines Controllers oder einer PageModel-Klasse, falls durch Attribute angegeben.Public properties of a controller or PageModel class, if specified by attributes.

[BindProperty]-Attribut[BindProperty] attribute

Kann auf eine öffentliche Eigenschaft eines Controllers oder einer PageModel-Klasse angewendet werden, um die Modellbindung anzuweisen, diese Eigenschaft als Ziel zu verwenden: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
{
    [BindProperty]
    public Instructor Instructor { get; set; }

[BindProperties]-Attribut[BindProperties] attribute

Verfügbar in ASP.NET Core 2.1 und höher.Available in ASP.NET Core 2.1 and later. Kann auf einen Controller oder eine PageModel-Klasse angewendet werden, um die Modellbindung anzuweisen, alle öffentlichen Eigenschaften dieser Klasse als Ziel zu verwenden: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 Instructor Instructor { get; set; }

Modellbindung für HTTP-GET-AnforderungenModel binding for HTTP GET requests

Standardmäßig sind Eigenschaften für HTTP GET-Anforderungen nicht gebunden.By default, properties are not bound for HTTP GET requests. In der Regel ist alles, was Sie für eine GET-Anforderung benötigen, ein Datensatz-ID-Parameter.Typically, all you need for a GET request is a record ID parameter. Die Datensatz-ID wird verwendet, um das Element in der Datenbank zu suchen.The record ID is used to look up the item in the database. Daher besteht keine Notwendigkeit, eine Eigenschaft zu binden, die eine Instanz des Modells enthält.Therefore, there is no need to bind a property that holds an instance of the model. In Szenarien, in denen Sie Eigenschaften an Daten aus GET-Anforderungen binden möchten, legen Sie die Eigenschaft SupportsGet auf true fest: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; }

QuellenSources

Standardmäßig ruft die Modellbindung Daten in Form von Schlüssel-Wert-Paaren aus den folgenden Quellen in einer HTTP-Anforderung ab:By default, model binding gets data in the form of key-value pairs from the following sources in an HTTP request:

  1. FormularfelderForm fields
  2. Der Anforderungstext (für Controller mit dem [ApiController]-Attribut)The request body (For controllers that have the [ApiController] attribute.)
  3. RoutendatenRoute data
  4. Abfragezeichenfolge-ParameterQuery string parameters
  5. Hochgeladene DateienUploaded files

Für jeden Zielparameter oder jede Zieleigenschaft werden die Quellen nach der oben aufgeführten Reihenfolge überprüft.For each target parameter or property, the sources are scanned in the order indicated in the preceding list. Es gibt ein paar Ausnahmen:There are a few exceptions:

  • Routendaten und Abfragezeichenfolgenwerte werden nur für einfache Typen verwendet.Route data and query string values are used only for simple types.
  • Hochgeladene Dateien werden nur an Zieltypen gebunden, die IFormFile oder IEnumerable<IFormFile> implementieren.Uploaded files are bound only to target types that implement IFormFile or IEnumerable<IFormFile>.

Wenn die Standardquelle nicht richtig ist, verwenden Sie eines der folgenden Attribute zum Festlegen der Quelle:If the default source is not correct, use one of the following attributes to specify the source:

Diese Attribute:These attributes:

  • Werden Modelleigenschaften einzeln hinzugefügt (nicht zur Modellklasse), wie im folgenden Beispiel gezeigt: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; }

  • Akzeptieren optional einen Modellnamenswert im Konstruktor.Optionally accept a model name value in the constructor. Diese Option wird für den Fall bereitgestellt, dass der Eigenschaftenname nicht mit dem Wert in der Anforderung übereinstimmt.This option is provided in case the property name doesn't match the value in the request. Beispielsweise könnte der Wert in der Anforderung ein Header mit einem Bindestrich in seinem Namen sein, wie im folgenden Beispiel gezeigt: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)

[FromBody]-Attribut[FromBody] attribute

Wenden Sie das [FromBody]-Attribut auf einen Parameter an, um dessen Eigenschaften über den Text einer HTTP-Anforderung aufzufüllen.Apply the [FromBody] attribute to a parameter to populate its properties from the body of an HTTP request. Die ASP.NET Core-Runtime delegiert die Verantwortung, für das Lesen des Texts an einen Eingabeformatierer.The ASP.NET Core runtime delegates the responsibility of reading the body to an input formatter. Eingabeformatierer werden später in diesem Artikel erklärt.Input formatters are explained later in this article.

Wenn [FromBody] auf einen komplexen Typparameter angewendet wird, werden alle Bindungsquellenattribute ignoriert, die auf die Eigenschaften angewendet werden.When [FromBody] is applied to a complex type parameter, any binding source attributes applied to its properties are ignored. Die folgende Create-Aktion legt beispielsweise fest, dass der pet-Parameter mithilfe des Texts aufgefüllt wird:For example, the following Create action specifies that its pet parameter is populated from the body:

public ActionResult<Pet> Create([FromBody] Pet pet)

Die Pet-Klasse legt fest, dass ihre Breed-Eigenschaft mithilfe eines Abfragezeichenfolgenparameters aufgefüllt wird:The Pet class specifies that its Breed property is populated from a query string parameter:

public class Pet
{
    public string Name { get; set; }

    [FromQuery] // Attribute is ignored.
    public string Breed { get; set; }
}

Im vorherigen Beispiel:In the preceding example:

  • Das [FromQuery]-Attribut wird ignoriert.The [FromQuery] attribute is ignored.
  • Die Breed-Eigenschaft wird nicht mithilfe eines Abfragezeichenfolgenparameters aufgefüllt.The Breed property is not populated from a query string parameter.

Eingabeformatierer lesen nur den Text und verstehen Bindungsquellenattribute nicht.Input formatters read only the body and don't understand binding source attributes. Wenn ein geeigneter Wert im Text gefunden wird, wird dieser Wert zum Auffüllen der Breed-Eigenschaft verwendet.If a suitable value is found in the body, that value is used to populate the Breed property.

Wenden Sie [FromBody] auf nicht mehr als einen Parameter pro Aktionsmethode an.Don't apply [FromBody] to more than one parameter per action method. Sobald der Anforderungsdatenstrom von einem Eingabeformatierer gelesen wurde, ist er nicht mehr verfügbar, um für die Bindung anderer [FromBody]-Parameter nochmal gelesen zu werden.Once the request stream is read by an input formatter, it's no longer available to be read again for binding other [FromBody] parameters.

Zusätzliche QuellenAdditional sources

Quelldaten werden dem Modellbindungssystem durch Wertanbieter bereitgestellt.Source data is provided to the model binding system by value providers. Sie können benutzerdefinierte Wertanbieter schreiben und registrieren, die Daten für die Modellbindung aus anderen Quellen abrufen.You can write and register custom value providers that get data for model binding from other sources. Angenommen, Sie möchten Daten aus cookie s oder dem Sitzungszustand.For example, you might want data from cookies or session state. So rufen Sie Daten aus einer neuen Quelle abTo get data from a new source:

  • Erstellen Sie eine Klasse, die das IValueProvider implementiert.Create a class that implements IValueProvider.
  • Erstellen Sie eine Klasse, die das IValueProviderFactory implementiert.Create a class that implements IValueProviderFactory.
  • Registrieren Sie die Factoryklasse in Startup.ConfigureServices.Register the factory class in Startup.ConfigureServices.

Die Beispiel-app enthält einen Wert Anbieter und ein Factory -Beispiel, mit dem Werte von s abgerufen werden cookie .The sample app includes a value provider and factory example that gets values from cookies. Dies ist der Registrierungscode in Startup.ConfigureServices:Here's the registration code in Startup.ConfigureServices:

services.AddRazorPages()
    .AddMvcOptions(options =>
{
    options.ValueProviderFactories.Add(new CookieValueProviderFactory());
    options.ModelMetadataDetailsProviders.Add(
        new ExcludeBindingMetadataProvider(typeof(System.Version)));
    options.ModelMetadataDetailsProviders.Add(
        new SuppressChildValidationMetadataProvider(typeof(System.Guid)));
})
.AddXmlSerializerFormatters();

Der angezeigte Code fügt den benutzerdefinierten Wertanbieter hinter allen integrierten Wertanbietern ein.The code shown puts the custom value provider after all the built-in value providers. Damit er der erste in der Liste wird, rufen Sie Insert(0, new CookieValueProviderFactory()) anstelle von Add auf.To make it the first in the list, call Insert(0, new CookieValueProviderFactory()) instead of Add.

Keine Quelle für eine ModelleigenschaftNo source for a model property

Standardmäßig wird kein Modellzustandsfehler erstellt, wenn kein Wert für eine Modelleigenschaft gefunden wird.By default, a model state error isn't created if no value is found for a model property. Die Eigenschaft wird auf „null“ oder einen Standardwert festgelegt:The property is set to null or a default value:

  • Einfache Nullable-Typen werden auf null festgelegt.Nullable simple types are set to null.
  • Nicht-Nullable-Werttypen werden auf default(T) festgelegt.Non-nullable value types are set to default(T). Beispiel: Ein Parameter int id wird auf „0“ festgelegt.For example, a parameter int id is set to 0.
  • Für komplexe Typen erstellt die Modellbindung eine Instanz, indem der Standardkonstruktor verwendet wird, ohne Eigenschaften festzulegen.For complex Types, model binding creates an instance by using the default constructor, without setting properties.
  • Arrays werden auf Array.Empty<T>() festgelegt, mit der Ausnahme, dass byte[]-Arrays auf null festgelegt werden.Arrays are set to Array.Empty<T>(), except that byte[] arrays are set to null.

Wenn der Modell Zustand für eine Modell Eigenschaft ungültig gemacht werden soll, wenn nichts gefunden wird, verwenden Sie das- [BindRequired] Attribut.If model state should be invalidated when nothing is found in form fields for a model property, use the [BindRequired] attribute.

Beachten Sie, dass dieses [BindRequired]-Verhalten für die Modellbindung von Daten aus bereitgestellten Formulardaten gilt, nicht für JSON- oder XML-Daten in einem Anforderungstext.Note that this [BindRequired] behavior applies to model binding from posted form data, not to JSON or XML data in a request body. Anforderungstextdaten werden von Eingabeformatierern verarbeitet.Request body data is handled by input formatters.

TypkonvertierungsfehlerType conversion errors

Wenn eine Quelle gefunden wird, aber nicht in den Zieltyp konvertiert werden kann, wird der Modellzustand als „ungültig“ gekennzeichnet.If a source is found but can't be converted into the target type, model state is flagged as invalid. Der Zielparameter oder die Zieleigenschaft wird auf „null“ oder einen Standardwert festgelegt, wie bereits im vorherigen Abschnitt erwähnt.The target parameter or property is set to null or a default value, as noted in the previous section.

In einem API-Controller, der über das [ApiController]-Attribut verfügt, führt ein ungültiger Modellzustand zu einer automatischen „HTTP 400“-Antwort.In an API controller that has the [ApiController] attribute, invalid model state results in an automatic HTTP 400 response.

Zeigen Sie auf einer Razor Seite die Seite erneut mit einer Fehlermeldung an: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");
}

Bei der Client seitigen Validierung werden die meisten ungültigen Daten abgefangen, die andernfalls an ein Seiten Formular übermittelt werden Razor .Client-side validation catches most bad data that would otherwise be submitted to a Razor Pages form. Diese Validierung erschwert es, den voranstehenden, hervorgehobenen Code auszulösen.This validation makes it hard to trigger the preceding highlighted code. Die Beispiel-App umfasst eine Schaltfläche Submit with Invalid Date (Mit ungültigem Datum absenden), die ungültige Daten in das Feld Hire Date (Einstellungsdatum) einfügt und das Formular absendet.The sample app includes a Submit with Invalid Date button that puts bad data in the Hire Date field and submits the form. Diese Schaltfläche zeigt, wie der Code zum erneuten Anzeigen der Seite funktioniert, wenn Datenkonvertierungsfehler auftreten.This button shows how the code for redisplaying the page works when data conversion errors occur.

Wenn die Seite von dem vorangehenden Code erneut angezeigt wird, wird die ungültige Eingabe nicht im Formularfeld angezeigt.When the page is redisplayed by the preceding code, the invalid input is not shown in the form field. Dies liegt daran, dass die Modelleigenschaft auf „null“ oder einen Standardwert festgelegt wurde.This is because the model property has been set to null or a default value. Die ungültige Eingabe wird jedoch in einer Fehlermeldung angezeigt.The invalid input does appear in an error message. Wenn Sie aber die ungültigen Daten im Formularfeld erneut anzeigen möchten, sollten Sie aus der Modelleigenschaft eine Zeichenfolge machen und die Datenkonvertierung manuell ausführen.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.

Dieselbe Strategie empfiehlt sich, wenn Sie nicht möchten, dass Typkonvertierungsfehler zu Modellzustandsfehlern führen.The same strategy is recommended if you don't want type conversion errors to result in model state errors. In diesem Fall machen Sie aus der Modelleigenschaft eine Zeichenfolge.In that case, make the model property a string.

Einfache TypenSimple types

Die einfachen Typen, in die die Modellbindung Quellzeichenfolgen konvertieren kann, sind unter anderem:The simple types that the model binder can convert source strings into include the following:

Komplexe TypenComplex types

Ein komplexer Typ muss einen öffentlichen Standardkonstruktor und öffentliche schreibbare Eigenschaften besitzen, die gebunden werden können.A complex type must have a public default constructor and public writable properties to bind. Wenn die Modellbindung erfolgt, wird die Klasse mit dem öffentlichen Standardkonstruktor instanziiert.When model binding occurs, the class is instantiated using the public default constructor.

Für jede Eigenschaft des komplexen Typs durchsucht die Modellbindung die Quellen für das Namensmuster prefix.property_name.For each property of the complex type, model binding looks through the sources for the name pattern prefix.property_name. Wenn nichts gefunden wird, sucht sie nur nach property_name ohne das Präfix.If nothing is found, it looks for just property_name without the prefix.

Beim Binden an einen Parameter ist das Präfix der Name des Parameters.For binding to a parameter, the prefix is the parameter name. Beim Binden an eine öffentliche Eigenschaft PageModel ist das Präfix der Name der öffentlichen Eigenschaft.For binding to a PageModel public property, the prefix is the public property name. Einige Attribute besitzen eine Eigenschaft Prefix, die es Ihnen gestattet, die Standardverwendung des Parameter- oder Eigenschaftennamens außer Kraft zu setzen.Some attributes have a Prefix property that lets you override the default usage of parameter or property name.

Nehmen Sie beispielsweise an, der komplexe Typ ist die folgende Instructor-Klasse: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äfix = ParameternamePrefix = parameter name

Wenn das zu bindende Modell ein Parameter namens instructorToUpdate ist:If the model to be bound is a parameter named instructorToUpdate:

public IActionResult OnPost(int? id, Instructor instructorToUpdate)

Die Modellbindung beginnt, indem sie die Quellen nach dem Schlüssel instructorToUpdate.ID durchsucht.Model binding starts by looking through the sources for the key instructorToUpdate.ID. Wenn dieser nicht gefunden wird, sucht sie nach ID ohne Präfix.If that isn't found, it looks for ID without a prefix.

Präfix = Name der EigenschaftPrefix = property name

Wenn das zu bindende Modell eine Eigenschaft des Controllers oder der PageModel-Klasse namens Instructor ist:If the model to be bound is a property named Instructor of the controller or PageModel class:

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

Die Modellbindung beginnt, indem sie die Quellen nach dem Schlüssel Instructor.ID durchsucht.Model binding starts by looking through the sources for the key Instructor.ID. Wenn dieser nicht gefunden wird, sucht sie nach ID ohne Präfix.If that isn't found, it looks for ID without a prefix.

Benutzerdefiniertes PräfixCustom prefix

Wenn das zu bindende Modell ein Parameter namens instructorToUpdate ist, und ein Bind-Attribut Instructor als Präfix angibt: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)

Die Modellbindung beginnt, indem sie die Quellen nach dem Schlüssel Instructor.ID durchsucht.Model binding starts by looking through the sources for the key Instructor.ID. Wenn dieser nicht gefunden wird, sucht sie nach ID ohne Präfix.If that isn't found, it looks for ID without a prefix.

Attribute für Ziele komplexen TypsAttributes for complex type targets

Mehrere integrierte Attribute stehen für die Kontrolle der Modellbindung komplexer Typen zur Verfügung:Several built-in attributes are available for controlling model binding of complex types:

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

Warnung

Diese Attribute wirken sich auf die Modellbindung aus, wenn bereitgestellte Formulardaten die Quelle der Wert sind.These attributes affect model binding when posted form data is the source of values. Sie wirken sich nicht auf Eingabe Formatierer aus, die gepostete JSON-und XML-Anforderungs Texte verarbeiten.They do not affect input formatters, which process posted JSON and XML request bodies. Eingabeformatierer werden später in diesem Artikel erklärt.Input formatters are explained later in this article.

[Bind]-Attribut[Bind] attribute

Kann auf eine Klasse oder einen Methodenparameter angewendet werden.Can be applied to a class or a method parameter. Gibt an, welche Eigenschaften eines Modells in die Modellbindung aufgenommen werden sollen.Specifies which properties of a model should be included in model binding. [Bind] wirkt sich nicht auf Eingabe Formatierer aus.[Bind] does not affect input formatters.

Im folgenden Beispiel werden nur die angegebenen Eigenschaften des Instructor-Modells gebunden, wenn ein Ereignishandler oder eine Aktionsmethode aufgerufen wird: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

Im folgenden Beispiel werden nur die angegebenen Eigenschaften des Instructor-Modells gebunden, wenn die OnPost-Methode aufgerufen wird: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)

Das [Bind]-Attribut kann zum Schutz vor Overposting in Erstellungs szenarien (create) verwendet werden.The [Bind] attribute can be used to protect against overposting in create scenarios. Es funktioniert nicht gut in Bearbeitungsszenarien (edit), weil ausgeschlossene Eigenschaften auf „null“ oder einen Standardwert festgelegt werden, anstatt unverändert zu bleiben.It doesn't work well in edit scenarios because excluded properties are set to null or a default value instead of being left unchanged. Zum Schutz vor Overposting werden Ansichtsmodelle empfohlen, anstelle des [Bind]-Attributs.For defense against overposting, view models are recommended rather than the [Bind] attribute. Weitere Informationen finden Sie unter Sicherheitshinweis zum Overposting.For more information, see Security note about overposting.

[Modelbinder]-Attribut[ModelBinder] attribute

ModelBinderAttribute kann auf Typen, Eigenschaften oder Parameter angewendet werden.ModelBinderAttribute can be applied to types, properties, or parameters. Es ermöglicht die Angabe des Typs des Modell Binders, der zum Binden der spezifischen Instanz oder des Typs verwendet wird.It allows specifying the type of model binder used to bind the specific instance or type. Beispiel:For example:

[HttpPost]
public IActionResult OnPost([ModelBinder(typeof(MyInstructorModelBinder))] Instructor instructor)

Das [ModelBinder] -Attribut kann auch verwendet werden, um den Namen einer Eigenschaft oder eines Parameters zu ändern, wenn er Modell gebunden ist:The [ModelBinder] attribute can also be used to change the name of a property or parameter when it's being model bound:

public class Instructor
{
    [ModelBinder(Name = "instructor_id")]
    public string Id { get; set; }

    public string Name { get; set; }
}

[BindRequired]-Attribut[BindRequired] attribute

Kann nur auf Modelleigenschaften angewendet werden, nicht auf Methodenparameter.Can only be applied to model properties, not to method parameters. Bewirkt, dass die Modellbindung einen Modellzustandsfehler hinzufügt, wenn die Bindung für die Eigenschaft eines Modells nicht erfolgen kann.Causes model binding to add a model state error if binding cannot occur for a model's property. Hier sehen Sie ein Beispiel: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; }

Lesen Sie auch die Diskussion des [Required]-Attributs in der Modellvalidierung.See also the discussion of the [Required] attribute in Model validation.

[BindNever]-Attribut[BindNever] attribute

Kann nur auf Modelleigenschaften angewendet werden, nicht auf Methodenparameter.Can only be applied to model properties, not to method parameters. Verhindert, dass die Modellbindung die Eigenschaft eines Modells festlegt.Prevents model binding from setting a model's property. Hier sehen Sie ein Beispiel:Here's an example:

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

AuflistungenCollections

Bei Zielen, die Sammlungen einfacher Typen sind, sucht die Modellbindung nach Übereinstimmungen mit parameter_name oder property_name.For targets that are collections of simple types, model binding looks for matches to parameter_name or property_name. Wird keine Übereinstimmung gefunden, sucht sie nach einem der unterstützten Formate ohne Präfix.If no match is found, it looks for one of the supported formats without the prefix. Beispiel:For example:

  • Angenommen, der zu bindende Parameter ist ein Array namens selectedCourses:Suppose the parameter to be bound is an array named selectedCourses:

    public IActionResult OnPost(int? id, int[] selectedCourses)

  • Formular- oder Abfragezeichenfolgendaten können eins der folgenden Formate haben: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

  • Das folgende Format wird nur für Formulardaten unterstützt:The following format is supported only in form data:

    selectedCourses[]=1050&selectedCourses[]=2000

  • Bei allen der vorangehenden Beispielformate übergibt die Modellbindung ein Array von zwei Elementen an den selectedCourses-Parameter: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

    Datenformate, die Indexnummern verwenden(... [0]... [1] ...), müssen sicherstellen, dass sie fortlaufend nummeriert sind, beginnend mit 0 (null).Data formats that use subscript numbers (... [0] ... [1] ...) must ensure that they are numbered sequentially starting at zero. Treten bei der Indexnummerierung Lücken auf, werden alle Elemente, die auf die Lücke folgen, ignoriert.If there are any gaps in subscript numbering, all items after the gap are ignored. Wenn die Indizes beispielsweise 0 und 2 anstelle von 0 und 1 sind, wird beispielsweise das zweite Element ignoriert.For example, if the subscripts are 0 and 2 instead of 0 and 1, the second item is ignored.

WörterbücherDictionaries

Bei Dictionary-Zielen sucht die Modellbindung nach Übereinstimmungen mit parameter_name oder property_name.For Dictionary targets, model binding looks for matches to parameter_name or property_name. Wird keine Übereinstimmung gefunden, sucht sie nach einem der unterstützten Formate ohne Präfix.If no match is found, it looks for one of the supported formats without the prefix. Beispiel:For example:

  • Angenommen, der Zielparameter ist eine Dictionary<int, string> mit dem Namen selectedCourses:Suppose the target parameter is a Dictionary<int, string> named selectedCourses:

    public IActionResult OnPost(int? id, Dictionary<int, string> selectedCourses)

  • Die bereitgestellten Formular- oder Abfragezeichenfolgendaten können wie eins der folgenden Beispiele aussehen: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

  • Bei allen der vorangehenden Beispielformate übergibt die Modellbindung ein Wörterbuch aus zwei Elementen an den selectedCourses-Parameter: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"

Konstruktorbindungs-und Daten Satz TypenConstructor binding and record types

Die Modell Bindung erfordert, dass komplexe Typen über einen Parameter losen Konstruktor verfügen.Model binding requires that complex types have a parameterless constructor. Sowohl System.Text.Json als auch Newtonsoft.Json basierte Eingabe Formatierer unterstützen die Deserialisierung von Klassen, die über keinen Parameter losen Konstruktor verfügen.Both System.Text.Json and Newtonsoft.Json based input formatters support deserialization of classes that don't have a parameterless constructor.

C# 9 führt Daten Satz Typen ein, die eine hervorragend Möglichkeit darstellen, Daten über das Netzwerk zu übermitteln.C# 9 introduces record types, which are a great way to succinctly represent data over the network. ASP.net Core fügt Unterstützung für die Modell Bindung und die Validierung von Daten Satz Typen mit einem einzelnen Konstruktor hinzu:ASP.NET Core adds support for model binding and validating record types with a single constructor:

public record Person([Required] string Name, [Range(0, 150)] int Age, [BindNever] int Id);

public class PersonController
{
   public IActionResult Index() => View();

   [HttpPost]
   public IActionResult Index(Person person)
   {
       ...
   }
}

Person/Index.cshtml:Person/Index.cshtml:

@model Person

Name: <input asp-for="Name" />
...
Age: <input asp-for="Age" />

Beim Überprüfen von Daten Satz Typen sucht die Runtime nach Bindungs-und Validierungs Metadaten speziell für Parameter und nicht für Eigenschaften.When validating record types, the runtime searches for binding and validation metadata specifically on parameters rather than on properties.

Globalisierungsverhalten der Routendaten und Abfragezeichenfolgen für die ModellbindungGlobalization behavior of model binding route data and query strings

Der ASP.NET Core-Routenwertanbieter und der Abfragezeichenfolgenwert-Anbieter:The ASP.NET Core route value provider and query string value provider:

  • behandeln Werte als invariante Kulturen.Treat values as invariant culture.
  • erwarten, dass URLs kulturinvariant sind.Expect that URLs are culture-invariant.

Im Gegensatz dazu durchlaufen Werte, die aus Formulardaten stammen, eine kulturabhängige Konvertierung.In contrast, values coming from form data undergo a culture-sensitive conversion. Dies ist beabsichtigt, damit URLs zwischen Gebietsschemas freigegeben werden können.This is by design so that URLs are shareable across locales.

So lassen Sie den ASP.NET Core-Routenwertanbieter und den Abfragezeichenfolgenwert-Anbieter eine kulturabhängige Konvertierung durchlaufen:To make the ASP.NET Core route value provider and query string value provider undergo a culture-sensitive conversion:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews(options =>
    {
        var index = options.ValueProviderFactories.IndexOf(
            options.ValueProviderFactories.OfType<QueryStringValueProviderFactory>().Single());
        options.ValueProviderFactories[index] = new CulturedQueryStringValueProviderFactory();
    });
}

public class CulturedQueryStringValueProviderFactory : IValueProviderFactory
{
    public Task CreateValueProviderAsync(ValueProviderFactoryContext context)
    {
        if (context == null)
        {
            throw new ArgumentNullException(nameof(context));
        }

        var query = context.ActionContext.HttpContext.Request.Query;
        if (query != null && query.Count > 0)
        {
            var valueProvider = new QueryStringValueProvider(
                BindingSource.Query,
                query,
                CultureInfo.CurrentCulture);

            context.ValueProviders.Add(valueProvider);
        }

        return Task.CompletedTask;
    }
}

Spezielle DatentypenSpecial data types

Es gibt einige spezielle Datentypen, die die Modellbindung verarbeiten kann.There are some special data types that model binding can handle.

„IFormFile“ und „IFormFileCollection“IFormFile and IFormFileCollection

Eine in der HTTP-Anforderung enthaltene, hochgeladenen Datei.An uploaded file included in the HTTP request. Außerdem wird IEnumerable<IFormFile> für mehrere Dateien unterstützt.Also supported is IEnumerable<IFormFile> for multiple files.

CancellationTokenCancellationToken

Aktionen können optional einen CancellationToken als Parameter binden.Actions can optionally bind a CancellationToken as a parameter. Dies bindet RequestAborted , wenn die Verbindung, die der HTTP-Anforderung zugrunde liegt, abgebrochen wird.This binds RequestAborted that signals when the connection underlying the HTTP request is aborted. Aktionen können diesen Parameter verwenden, um asynchrone Vorgänge mit langer Laufzeit abzubrechen, die als Teil der Controller Aktionen ausgeführt werden.Actions can use this parameter to cancel long running async operations that are executed as part of the controller actions.

„FormCollection“FormCollection

Wird verwendet, um alle Werte aus bereitgestellten Formulardaten abzurufen.Used to retrieve all the values from posted form data.

EingabeformatiererInput formatters

Daten im Anforderungstext können im JSON-, XML- oder einem anderen Format sein.Data in the request body can be in JSON, XML, or some other format. Um diese Daten zu analysieren, verwendet die Modellbindung einen Eingabeformatierer, der für die Verarbeitung eines bestimmten Inhaltstyps konfiguriert ist.To parse this data, model binding uses an input formatter that is configured to handle a particular content type. ASP.NET Core enthält standardmäßig JSON-basierte Eingabeformatierer für die Verarbeitung von JSON-Daten.By default, ASP.NET Core includes JSON based input formatters for handling JSON data. Sie können andere Formatierer für andere Inhaltstypen hinzufügen.You can add other formatters for other content types.

ASP.NET Core wählt Eingabeformatierer auf Grundlage des Consumes-Attributs aus.ASP.NET Core selects input formatters based on the Consumes attribute. Wenn kein Attribut vorhanden ist, verwendet es den Content-Type-Header.If no attribute is present, it uses the Content-Type header.

So verwenden Sie die integrierte XML-EingabeformatiererTo use the built-in XML input formatters:

  • Installieren Sie das NuGet-Paket Microsoft.AspNetCore.Mvc.Formatters.Xml.Install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

  • In Startup.ConfigureServices, rufen Sie AddXmlSerializerFormatters oder AddXmlDataContractSerializerFormatters auf.In Startup.ConfigureServices, call AddXmlSerializerFormatters or AddXmlDataContractSerializerFormatters.

    services.AddRazorPages()
    .AddMvcOptions(options =>
{
    options.ValueProviderFactories.Add(new CookieValueProviderFactory());
    options.ModelMetadataDetailsProviders.Add(
        new ExcludeBindingMetadataProvider(typeof(System.Version)));
    options.ModelMetadataDetailsProviders.Add(
        new SuppressChildValidationMetadataProvider(typeof(System.Guid)));
})
.AddXmlSerializerFormatters();

  • Wenden Sie das Consumes-Attribut auf Controllerklassen oder Aktionsmethoden an, die XML im Anforderungstext erwarten sollten.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)

    Weitere Informationen finden Sie unter Einführung der XML-Serialisierung.For more information, see Introducing XML Serialization.

Anpassen der Modellbindung mit EingabeformatierernCustomize model binding with input formatters

Ein Eingabeformatierer ist in vollem Umfang für das Lesen von Daten aus dem Anforderungstext verantwortlich.An input formatter takes full responsibility for reading data from the request body. Um diesen Prozess anzupassen, konfigurieren Sie die APIs, die vom Eingabeformatierer verwendet werden.To customize this process, configure the APIs used by the input formatter. In diesem Abschnitt wird beschrieben, wie Sie den auf System.Text.Json basierenden Eingabeformatierer so anpassen, dass er einen benutzerdefinierten Typ mit dem Namen ObjectId versteht.This section describes how to customize the System.Text.Json-based input formatter to understand a custom type named ObjectId.

Betrachten Sie das folgende Modell, das eine benutzerdefinierte ObjectId-Eigenschaft mit dem Namen Id enthält:Consider the following model, which contains a custom ObjectId property named Id:

public class ModelWithObjectId
{
    public ObjectId Id { get; set; }
}

Um den Modellbindungsprozess bei der Verwendung von System.Text.Jsonanzupassen, erstellen Sie eine aus JsonConverter<T> abgeleitete Klasse:To customize the model binding process when using System.Text.Json, create a class derived from JsonConverter<T>:

internal class ObjectIdConverter : JsonConverter<ObjectId>
{
    public override ObjectId Read(
        ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        return new ObjectId(JsonSerializer.Deserialize<int>(ref reader, options));
    }

    public override void Write(
        Utf8JsonWriter writer, ObjectId value, JsonSerializerOptions options)
    {
        writer.WriteNumberValue(value.Id);
    }
}

Um einen benutzerdefinierten Konverter zu verwenden, wenden Sie das JsonConverterAttribute-Attribut auf den Typ an.To use a custom converter, apply the JsonConverterAttribute attribute to the type. Im folgenden Beispiel wird der Typ ObjectId mit ObjectIdConverter als seinem benutzerdefinierten Konverter konfiguriert:In the following example, the ObjectId type is configured with ObjectIdConverter as its custom converter:

[JsonConverter(typeof(ObjectIdConverter))]
public struct ObjectId
{
    public ObjectId(int id) =>
        Id = id;

    public int Id { get; }
}

Weitere Informationen finden Sie unter Vorgehensweise: Schreiben benutzerdefinierter Konverter.For more information, see How to write custom converters.

Ausschließen angegebener Typen aus der ModellbindungExclude specified types from model binding

Das Verhalten der Modellbindung und des Validierungssystems wird von der Klasse ModelMetadata gesteuert.The model binding and validation systems' behavior is driven by ModelMetadata. Sie können ModelMetadata anpassen, indem Sie MvcOptions.ModelMetadataDetailsProviders einen Detailanbieter hinzufügen.You can customize ModelMetadata by adding a details provider to MvcOptions.ModelMetadataDetailsProviders. Integrierte Detailanbieter sind verfügbar, um die Modellbindung oder Validierung für angegebene Typen zu deaktivieren.Built-in details providers are available for disabling model binding or validation for specified types.

Um die Modellbindung für alle Modelle eines angegebenen Typs zu deaktivieren, fügen Sie in Startup.ConfigureServices einen ExcludeBindingMetadataProvider hinzu.To disable model binding on all models of a specified type, add an ExcludeBindingMetadataProvider in Startup.ConfigureServices. Beispielsweise können Sie die Modellbindung für alle Modelle vom Typ System.Version wie folgt deaktivieren:For example, to disable model binding on all models of type System.Version:

services.AddRazorPages()
    .AddMvcOptions(options =>
{
    options.ValueProviderFactories.Add(new CookieValueProviderFactory());
    options.ModelMetadataDetailsProviders.Add(
        new ExcludeBindingMetadataProvider(typeof(System.Version)));
    options.ModelMetadataDetailsProviders.Add(
        new SuppressChildValidationMetadataProvider(typeof(System.Guid)));
})
.AddXmlSerializerFormatters();

Um die Validierung für Eigenschaften eines angegebenen Typs zu deaktivieren, fügen Sie in Startup.ConfigureServices einen SuppressChildValidationMetadataProvider hinzu.To disable validation on properties of a specified type, add a SuppressChildValidationMetadataProvider in Startup.ConfigureServices. Beispielsweise können Sie die Überprüfung von Eigenschaften vom Typ System.Guid wie folgt deaktivieren:For example, to disable validation on properties of type System.Guid:

services.AddRazorPages()
    .AddMvcOptions(options =>
{
    options.ValueProviderFactories.Add(new CookieValueProviderFactory());
    options.ModelMetadataDetailsProviders.Add(
        new ExcludeBindingMetadataProvider(typeof(System.Version)));
    options.ModelMetadataDetailsProviders.Add(
        new SuppressChildValidationMetadataProvider(typeof(System.Guid)));
})
.AddXmlSerializerFormatters();

Benutzerdefinierte ModellbindungenCustom model binders

Sie können die Modellbindung erweitern, indem Sie eine benutzerdefinierte Modellbindung schreiben und das [ModelBinder]-Attribut verwenden, um diese für ein bestimmtes Ziel auszuwählen.You can extend model binding by writing a custom model binder and using the [ModelBinder] attribute to select it for a given target. Erfahren Sie mehr über die benutzerdefinierte Modellbindung.Learn more about custom model binding.

Manuelle ModellbindungManual model binding

Die Modellbindung kann mithilfe der TryUpdateModelAsync-Methode manuell aufgerufen werden.Model binding can be invoked manually by using the TryUpdateModelAsync method. Die Methode ist für die beiden Klassen ControllerBase und PageModel definiert.The method is defined on both ControllerBase and PageModel classes. Mithilfe von Methodenüberladungen können Sie das Präfix und den Wertanbieter festlegen, die verwendet werden sollen.Method overloads let you specify the prefix and value provider to use. Die Methode gibt false zurück, wenn die Modellbindung fehlschlägt.The method returns false if model binding fails. Hier sehen Sie ein Beispiel: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();

TryUpdateModelAsync verwendet Wertanbieter, um Daten aus dem Formulartext, der Abfragezeichenfolge und den Routendaten abzurufen.TryUpdateModelAsync uses value providers to get data from the form body, query string, and route data. TryUpdateModelAsync wird normalerweise so verwendet:TryUpdateModelAsync is typically:

  • Wird mit Razor Seiten und MVC-Apps verwendet, die Controller und Ansichten verwenden, um eine Übertragung zu verhindern.Used with Razor Pages and MVC apps using controllers and views to prevent over-posting.
  • Nicht zusammen mit einer Web-API, es sei denn, sie wird von Formulardaten, Abfragezeichenfolgen und Routendaten konsumiert.Not used with a web API unless consumed from form data, query strings, and route data. Web-API-Endpunkte, die JSON nutzen, verwenden Eingabeformatierer, um den Anforderungstext in ein-Objekt zu deserialisieren.Web API endpoints that consume JSON use Input formatters to deserialize the request body into an object.

Weitere Informationen finden Sie unter TryUpdateModelAsync.For more information, see TryUpdateModelAsync.

[FromServices]-Attribut[FromServices] attribute

Der Name dieses Attributs folgt dem Muster von Modellbindungsattributen, die eine Datenquelle angeben.This attribute's name follows the pattern of model binding attributes that specify a data source. Es ist aber nicht zum Binden von Daten aus einem Wertanbieter gedacht.But it's not about binding data from a value provider. Es ruft eine Instanz eines Typs aus dem Dependency Injection-Container (Abhängigkeitsinjektion) ab.It gets an instance of a type from the dependency injection container. Sein Zweck besteht darin, eine Alternative zur „Constructor Injection“ (Konstruktorinjektion) bereitzustellen, wenn Sie einen Dienst nur dann benötigen, wenn eine bestimmte Methode aufgerufen wird.Its purpose is to provide an alternative to constructor injection for when you need a service only if a particular method is called.

Zusätzliche RessourcenAdditional resources

In diesem Artikel wird erläutert, was Modellbindung ist, wie sie funktioniert, und wie Sie ihr Verhalten anpassen können.This article explains what model binding is, how it works, and how to customize its behavior.

Zeigen Sie Beispielcode an, oder laden Sie diesen herunter (Vorgehensweise zum Herunterladen).View or download sample code (how to download).

Was ist Modellbindung?What is Model binding

Controller und Razor Seiten arbeiten mit Daten, die aus HTTP-Anforderungen stammen.Controllers and Razor pages work with data that comes from HTTP requests. Routendaten können beispielsweise einen Datensatzschlüssel enthalten, und bereitgestellte Formularfelder können Werte für die Eigenschaften des Modells bereitstellen.For example, route data may provide a record key, and posted form fields may provide values for the properties of the model. Das Schreiben von Code zum Abrufen jedes dieser Werte und deren Konvertierung aus Zeichenfolgen in .NET-Datentypen wäre mühsam und fehleranfällig.Writing code to retrieve each of these values and convert them from strings to .NET types would be tedious and error-prone. Modellbindung automatisiert diesen Vorgang.Model binding automates this process. Das Modellbindungssystem:The model binding system:

  • Ruft Daten aus verschiedenen Quellen ab, z. B. Routendaten, Formularfelder und Abfragezeichenfolgen.Retrieves data from various sources such as route data, form fields, and query strings.
  • Stellt die Daten für Controller und Razor Seiten in Methoden Parametern und öffentlichen Eigenschaften bereit.Provides the data to controllers and Razor pages in method parameters and public properties.
  • Konvertiert Zeichenfolgendaten in .NET-Typen.Converts string data to .NET types.
  • Aktualisiert Eigenschaften komplexer Typen.Updates properties of complex types.

BeispielExample

Angenommen Sie haben die folgende Aktionsmethode:Suppose you have the following action method:

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

Und die App empfängt eine Anforderung mit dieser URL:And the app receives a request with this URL:

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

Die Modellbindung durchläuft die folgenden Schritte, nachdem das Routingsystem die Aktionsmethode ausgewählt hat:Model binding goes through the following steps after the routing system selects the action method:

  • Findet den ersten Parameters von GetByID, eine ganze Zahl namens id.Finds the first parameter of GetByID, an integer named id.
  • Durchsucht die verfügbaren Quellen in der HTTP-Anforderung und findet id = „2“ in den Routendaten.Looks through the available sources in the HTTP request and finds id = "2" in route data.
  • Konvertiert der Zeichenfolge „2“ in die ganze Zahl 2.Converts the string "2" into integer 2.
  • Findet den nächsten Parameter von GetByID, einen booleschen Wert namens dogsOnly.Finds the next parameter of GetByID, a boolean named dogsOnly.
  • Durchsucht die Quellen und findet „DogsOnly=True“ in der Abfragezeichenfolge.Looks through the sources and finds "DogsOnly=true" in the query string. Beim Abgleich von Namen wird die Groß- und Kleinschreibung nicht berücksichtigt.Name matching is not case-sensitive.
  • Konvertiert die Zeichenfolge „true“ in den booleschen Wert true.Converts the string "true" into boolean true.

Das Framework ruft dann die GetById-Methode auf, und übergibt dabei als Eingabe „2“ für den id-Parameter und true für den dogsOnly-Parameter.The framework then calls the GetById method, passing in 2 for the id parameter, and true for the dogsOnly parameter.

Im vorherigen Beispiel sind die Ziele der Modellbindung Methodenparameter, die einfache Typen sind.In the preceding example, the model binding targets are method parameters that are simple types. Ziele können aber auch die Eigenschaften eines komplexen Typs sein.Targets may also be the properties of a complex type. Nachdem jede Eigenschaft erfolgreich gebunden wurde, erfolgt die Modellvalidierung für diese Eigenschaft.After each property is successfully bound, model validation occurs for that property. Der Datensatz darüber, welche Daten an das Modell gebunden sind, sowie mit allen Bindungs- oder Validierungsfehlern wird in ControllerBase.ModelState oder PageModel.ModelState gespeichert.The record of what data is bound to the model, and any binding or validation errors, is stored in ControllerBase.ModelState or PageModel.ModelState. Um herauszufinden, ob dieser Vorgang erfolgreich war, überprüft die App das Flag ModelState.IsValid.To find out if this process was successful, the app checks the ModelState.IsValid flag.

ZieleTargets

Die Modellbindung versucht, Werte für die folgenden Arten von Zielen zu finden:Model binding tries to find values for the following kinds of targets:

  • Parameter der Controlleraktionsmethode, zu der eine Anforderung weitergeleitet wird.Parameters of the controller action method that a request is routed to.
  • Parameter der Razor pages-Handlermethode, an die eine Anforderung weitergeleitet wird.Parameters of the Razor Pages handler method that a request is routed to.
  • Öffentliche Eigenschaften eines Controllers oder einer PageModel-Klasse, falls durch Attribute angegeben.Public properties of a controller or PageModel class, if specified by attributes.

[BindProperty]-Attribut[BindProperty] attribute

Kann auf eine öffentliche Eigenschaft eines Controllers oder einer PageModel-Klasse angewendet werden, um die Modellbindung anzuweisen, diese Eigenschaft als Ziel zu verwenden: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
{
    [BindProperty]
    public Instructor Instructor { get; set; }

[BindProperties]-Attribut[BindProperties] attribute

Verfügbar in ASP.NET Core 2.1 und höher.Available in ASP.NET Core 2.1 and later. Kann auf einen Controller oder eine PageModel-Klasse angewendet werden, um die Modellbindung anzuweisen, alle öffentlichen Eigenschaften dieser Klasse als Ziel zu verwenden: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 Instructor Instructor { get; set; }

Modellbindung für HTTP-GET-AnforderungenModel binding for HTTP GET requests

Standardmäßig sind Eigenschaften für HTTP GET-Anforderungen nicht gebunden.By default, properties are not bound for HTTP GET requests. In der Regel ist alles, was Sie für eine GET-Anforderung benötigen, ein Datensatz-ID-Parameter.Typically, all you need for a GET request is a record ID parameter. Die Datensatz-ID wird verwendet, um das Element in der Datenbank zu suchen.The record ID is used to look up the item in the database. Daher besteht keine Notwendigkeit, eine Eigenschaft zu binden, die eine Instanz des Modells enthält.Therefore, there is no need to bind a property that holds an instance of the model. In Szenarien, in denen Sie Eigenschaften an Daten aus GET-Anforderungen binden möchten, legen Sie die Eigenschaft SupportsGet auf true fest: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; }

QuellenSources

Standardmäßig ruft die Modellbindung Daten in Form von Schlüssel-Wert-Paaren aus den folgenden Quellen in einer HTTP-Anforderung ab:By default, model binding gets data in the form of key-value pairs from the following sources in an HTTP request:

  1. FormularfelderForm fields
  2. Der Anforderungstext (für Controller mit dem [ApiController]-Attribut)The request body (For controllers that have the [ApiController] attribute.)
  3. RoutendatenRoute data
  4. Abfragezeichenfolge-ParameterQuery string parameters
  5. Hochgeladene DateienUploaded files

Für jeden Zielparameter oder jede Zieleigenschaft werden die Quellen nach der oben aufgeführten Reihenfolge überprüft.For each target parameter or property, the sources are scanned in the order indicated in the preceding list. Es gibt ein paar Ausnahmen:There are a few exceptions:

  • Routendaten und Abfragezeichenfolgenwerte werden nur für einfache Typen verwendet.Route data and query string values are used only for simple types.
  • Hochgeladene Dateien werden nur an Zieltypen gebunden, die IFormFile oder IEnumerable<IFormFile> implementieren.Uploaded files are bound only to target types that implement IFormFile or IEnumerable<IFormFile>.

Wenn die Standardquelle nicht richtig ist, verwenden Sie eines der folgenden Attribute zum Festlegen der Quelle:If the default source is not correct, use one of the following attributes to specify the source:

Diese Attribute:These attributes:

  • Werden Modelleigenschaften einzeln hinzugefügt (nicht zur Modellklasse), wie im folgenden Beispiel gezeigt: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; }

  • Akzeptieren optional einen Modellnamenswert im Konstruktor.Optionally accept a model name value in the constructor. Diese Option wird für den Fall bereitgestellt, dass der Eigenschaftenname nicht mit dem Wert in der Anforderung übereinstimmt.This option is provided in case the property name doesn't match the value in the request. Beispielsweise könnte der Wert in der Anforderung ein Header mit einem Bindestrich in seinem Namen sein, wie im folgenden Beispiel gezeigt: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)

[FromBody]-Attribut[FromBody] attribute

Wenden Sie das [FromBody]-Attribut auf einen Parameter an, um dessen Eigenschaften über den Text einer HTTP-Anforderung aufzufüllen.Apply the [FromBody] attribute to a parameter to populate its properties from the body of an HTTP request. Die ASP.NET Core-Runtime delegiert die Verantwortung, für das Lesen des Texts an einen Eingabeformatierer.The ASP.NET Core runtime delegates the responsibility of reading the body to an input formatter. Eingabeformatierer werden später in diesem Artikel erklärt.Input formatters are explained later in this article.

Wenn [FromBody] auf einen komplexen Typparameter angewendet wird, werden alle Bindungsquellenattribute ignoriert, die auf die Eigenschaften angewendet werden.When [FromBody] is applied to a complex type parameter, any binding source attributes applied to its properties are ignored. Die folgende Create-Aktion legt beispielsweise fest, dass der pet-Parameter mithilfe des Texts aufgefüllt wird:For example, the following Create action specifies that its pet parameter is populated from the body:

public ActionResult<Pet> Create([FromBody] Pet pet)

Die Pet-Klasse legt fest, dass ihre Breed-Eigenschaft mithilfe eines Abfragezeichenfolgenparameters aufgefüllt wird:The Pet class specifies that its Breed property is populated from a query string parameter:

public class Pet
{
    public string Name { get; set; }

    [FromQuery] // Attribute is ignored.
    public string Breed { get; set; }
}

Im vorherigen Beispiel:In the preceding example:

  • Das [FromQuery]-Attribut wird ignoriert.The [FromQuery] attribute is ignored.
  • Die Breed-Eigenschaft wird nicht mithilfe eines Abfragezeichenfolgenparameters aufgefüllt.The Breed property is not populated from a query string parameter.

Eingabeformatierer lesen nur den Text und verstehen Bindungsquellenattribute nicht.Input formatters read only the body and don't understand binding source attributes. Wenn ein geeigneter Wert im Text gefunden wird, wird dieser Wert zum Auffüllen der Breed-Eigenschaft verwendet.If a suitable value is found in the body, that value is used to populate the Breed property.

Wenden Sie [FromBody] auf nicht mehr als einen Parameter pro Aktionsmethode an.Don't apply [FromBody] to more than one parameter per action method. Sobald der Anforderungsdatenstrom von einem Eingabeformatierer gelesen wurde, ist er nicht mehr verfügbar, um für die Bindung anderer [FromBody]-Parameter nochmal gelesen zu werden.Once the request stream is read by an input formatter, it's no longer available to be read again for binding other [FromBody] parameters.

Zusätzliche QuellenAdditional sources

Quelldaten werden dem Modellbindungssystem durch Wertanbieter bereitgestellt.Source data is provided to the model binding system by value providers. Sie können benutzerdefinierte Wertanbieter schreiben und registrieren, die Daten für die Modellbindung aus anderen Quellen abrufen.You can write and register custom value providers that get data for model binding from other sources. Angenommen, Sie möchten Daten aus cookie s oder dem Sitzungszustand.For example, you might want data from cookies or session state. So rufen Sie Daten aus einer neuen Quelle abTo get data from a new source:

  • Erstellen Sie eine Klasse, die das IValueProvider implementiert.Create a class that implements IValueProvider.
  • Erstellen Sie eine Klasse, die das IValueProviderFactory implementiert.Create a class that implements IValueProviderFactory.
  • Registrieren Sie die Factoryklasse in Startup.ConfigureServices.Register the factory class in Startup.ConfigureServices.

Die Beispiel-app enthält einen Wert Anbieter und ein Factory -Beispiel, mit dem Werte von s abgerufen werden cookie .The sample app includes a value provider and factory example that gets values from cookies. Dies ist der Registrierungscode in 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);

Der angezeigte Code fügt den benutzerdefinierten Wertanbieter hinter allen integrierten Wertanbietern ein.The code shown puts the custom value provider after all the built-in value providers. Damit er der erste in der Liste wird, rufen Sie Insert(0, new CookieValueProviderFactory()) anstelle von Add auf.To make it the first in the list, call Insert(0, new CookieValueProviderFactory()) instead of Add.

Keine Quelle für eine ModelleigenschaftNo source for a model property

Standardmäßig wird kein Modellzustandsfehler erstellt, wenn kein Wert für eine Modelleigenschaft gefunden wird.By default, a model state error isn't created if no value is found for a model property. Die Eigenschaft wird auf „null“ oder einen Standardwert festgelegt:The property is set to null or a default value:

  • Einfache Nullable-Typen werden auf null festgelegt.Nullable simple types are set to null.
  • Nicht-Nullable-Werttypen werden auf default(T) festgelegt.Non-nullable value types are set to default(T). Beispiel: Ein Parameter int id wird auf „0“ festgelegt.For example, a parameter int id is set to 0.
  • Für komplexe Typen erstellt die Modellbindung eine Instanz, indem der Standardkonstruktor verwendet wird, ohne Eigenschaften festzulegen.For complex Types, model binding creates an instance by using the default constructor, without setting properties.
  • Arrays werden auf Array.Empty<T>() festgelegt, mit der Ausnahme, dass byte[]-Arrays auf null festgelegt werden.Arrays are set to Array.Empty<T>(), except that byte[] arrays are set to null.

Wenn der Modell Zustand für eine Modell Eigenschaft ungültig gemacht werden soll, wenn nichts gefunden wird, verwenden Sie das- [BindRequired] Attribut.If model state should be invalidated when nothing is found in form fields for a model property, use the [BindRequired] attribute.

Beachten Sie, dass dieses [BindRequired]-Verhalten für die Modellbindung von Daten aus bereitgestellten Formulardaten gilt, nicht für JSON- oder XML-Daten in einem Anforderungstext.Note that this [BindRequired] behavior applies to model binding from posted form data, not to JSON or XML data in a request body. Anforderungstextdaten werden von Eingabeformatierern verarbeitet.Request body data is handled by input formatters.

TypkonvertierungsfehlerType conversion errors

Wenn eine Quelle gefunden wird, aber nicht in den Zieltyp konvertiert werden kann, wird der Modellzustand als „ungültig“ gekennzeichnet.If a source is found but can't be converted into the target type, model state is flagged as invalid. Der Zielparameter oder die Zieleigenschaft wird auf „null“ oder einen Standardwert festgelegt, wie bereits im vorherigen Abschnitt erwähnt.The target parameter or property is set to null or a default value, as noted in the previous section.

In einem API-Controller, der über das [ApiController]-Attribut verfügt, führt ein ungültiger Modellzustand zu einer automatischen „HTTP 400“-Antwort.In an API controller that has the [ApiController] attribute, invalid model state results in an automatic HTTP 400 response.

Zeigen Sie auf einer Razor Seite die Seite erneut mit einer Fehlermeldung an: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");
}

Bei der Client seitigen Validierung werden die meisten ungültigen Daten abgefangen, die andernfalls an ein Seiten Formular übermittelt werden Razor .Client-side validation catches most bad data that would otherwise be submitted to a Razor Pages form. Diese Validierung erschwert es, den voranstehenden, hervorgehobenen Code auszulösen.This validation makes it hard to trigger the preceding highlighted code. Die Beispiel-App umfasst eine Schaltfläche Submit with Invalid Date (Mit ungültigem Datum absenden), die ungültige Daten in das Feld Hire Date (Einstellungsdatum) einfügt und das Formular absendet.The sample app includes a Submit with Invalid Date button that puts bad data in the Hire Date field and submits the form. Diese Schaltfläche zeigt, wie der Code zum erneuten Anzeigen der Seite funktioniert, wenn Datenkonvertierungsfehler auftreten.This button shows how the code for redisplaying the page works when data conversion errors occur.

Wenn die Seite von dem vorangehenden Code erneut angezeigt wird, wird die ungültige Eingabe nicht im Formularfeld angezeigt.When the page is redisplayed by the preceding code, the invalid input is not shown in the form field. Dies liegt daran, dass die Modelleigenschaft auf „null“ oder einen Standardwert festgelegt wurde.This is because the model property has been set to null or a default value. Die ungültige Eingabe wird jedoch in einer Fehlermeldung angezeigt.The invalid input does appear in an error message. Wenn Sie aber die ungültigen Daten im Formularfeld erneut anzeigen möchten, sollten Sie aus der Modelleigenschaft eine Zeichenfolge machen und die Datenkonvertierung manuell ausführen.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.

Dieselbe Strategie empfiehlt sich, wenn Sie nicht möchten, dass Typkonvertierungsfehler zu Modellzustandsfehlern führen.The same strategy is recommended if you don't want type conversion errors to result in model state errors. In diesem Fall machen Sie aus der Modelleigenschaft eine Zeichenfolge.In that case, make the model property a string.

Einfache TypenSimple types

Die einfachen Typen, in die die Modellbindung Quellzeichenfolgen konvertieren kann, sind unter anderem:The simple types that the model binder can convert source strings into include the following:

Komplexe TypenComplex types

Ein komplexer Typ muss einen öffentlichen Standardkonstruktor und öffentliche schreibbare Eigenschaften besitzen, die gebunden werden können.A complex type must have a public default constructor and public writable properties to bind. Wenn die Modellbindung erfolgt, wird die Klasse mit dem öffentlichen Standardkonstruktor instanziiert.When model binding occurs, the class is instantiated using the public default constructor.

Für jede Eigenschaft des komplexen Typs durchsucht die Modellbindung die Quellen für das Namensmuster prefix.property_name.For each property of the complex type, model binding looks through the sources for the name pattern prefix.property_name. Wenn nichts gefunden wird, sucht sie nur nach property_name ohne das Präfix.If nothing is found, it looks for just property_name without the prefix.

Beim Binden an einen Parameter ist das Präfix der Name des Parameters.For binding to a parameter, the prefix is the parameter name. Beim Binden an eine öffentliche Eigenschaft PageModel ist das Präfix der Name der öffentlichen Eigenschaft.For binding to a PageModel public property, the prefix is the public property name. Einige Attribute besitzen eine Eigenschaft Prefix, die es Ihnen gestattet, die Standardverwendung des Parameter- oder Eigenschaftennamens außer Kraft zu setzen.Some attributes have a Prefix property that lets you override the default usage of parameter or property name.

Nehmen Sie beispielsweise an, der komplexe Typ ist die folgende Instructor-Klasse: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äfix = ParameternamePrefix = parameter name

Wenn das zu bindende Modell ein Parameter namens instructorToUpdate ist:If the model to be bound is a parameter named instructorToUpdate:

public IActionResult OnPost(int? id, Instructor instructorToUpdate)

Die Modellbindung beginnt, indem sie die Quellen nach dem Schlüssel instructorToUpdate.ID durchsucht.Model binding starts by looking through the sources for the key instructorToUpdate.ID. Wenn dieser nicht gefunden wird, sucht sie nach ID ohne Präfix.If that isn't found, it looks for ID without a prefix.

Präfix = Name der EigenschaftPrefix = property name

Wenn das zu bindende Modell eine Eigenschaft des Controllers oder der PageModel-Klasse namens Instructor ist:If the model to be bound is a property named Instructor of the controller or PageModel class:

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

Die Modellbindung beginnt, indem sie die Quellen nach dem Schlüssel Instructor.ID durchsucht.Model binding starts by looking through the sources for the key Instructor.ID. Wenn dieser nicht gefunden wird, sucht sie nach ID ohne Präfix.If that isn't found, it looks for ID without a prefix.

Benutzerdefiniertes PräfixCustom prefix

Wenn das zu bindende Modell ein Parameter namens instructorToUpdate ist, und ein Bind-Attribut Instructor als Präfix angibt: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)

Die Modellbindung beginnt, indem sie die Quellen nach dem Schlüssel Instructor.ID durchsucht.Model binding starts by looking through the sources for the key Instructor.ID. Wenn dieser nicht gefunden wird, sucht sie nach ID ohne Präfix.If that isn't found, it looks for ID without a prefix.

Attribute für Ziele komplexen TypsAttributes for complex type targets

Mehrere integrierte Attribute stehen für die Kontrolle der Modellbindung komplexer Typen zur Verfügung:Several built-in attributes are available for controlling model binding of complex types:

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

Hinweis

Diese Attribute wirken sich auf die Modellbindung aus, wenn bereitgestellte Formulardaten die Quelle der Wert sind.These attributes affect model binding when posted form data is the source of values. Sie haben keine Auswirkungen auf Eingabeformatierer, die bereitgestellte JSON- und XML-Anforderungstexte verarbeiten.They do not affect input formatters, which process posted JSON and XML request bodies. Eingabeformatierer werden später in diesem Artikel erklärt.Input formatters are explained later in this article.

Lesen Sie auch die Diskussion des [Required]-Attributs in der Modellvalidierung.See also the discussion of the [Required] attribute in Model validation.

[BindRequired]-Attribut[BindRequired] attribute

Kann nur auf Modelleigenschaften angewendet werden, nicht auf Methodenparameter.Can only be applied to model properties, not to method parameters. Bewirkt, dass die Modellbindung einen Modellzustandsfehler hinzufügt, wenn die Bindung für die Eigenschaft eines Modells nicht erfolgen kann.Causes model binding to add a model state error if binding cannot occur for a model's property. Hier sehen Sie ein Beispiel: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; }

[BindNever]-Attribut[BindNever] attribute

Kann nur auf Modelleigenschaften angewendet werden, nicht auf Methodenparameter.Can only be applied to model properties, not to method parameters. Verhindert, dass die Modellbindung die Eigenschaft eines Modells festlegt.Prevents model binding from setting a model's property. Hier sehen Sie ein Beispiel:Here's an example:

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

[Bind]-Attribut[Bind] attribute

Kann auf eine Klasse oder einen Methodenparameter angewendet werden.Can be applied to a class or a method parameter. Gibt an, welche Eigenschaften eines Modells in die Modellbindung aufgenommen werden sollen.Specifies which properties of a model should be included in model binding.

Im folgenden Beispiel werden nur die angegebenen Eigenschaften des Instructor-Modells gebunden, wenn ein Ereignishandler oder eine Aktionsmethode aufgerufen wird: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

Im folgenden Beispiel werden nur die angegebenen Eigenschaften des Instructor-Modells gebunden, wenn die OnPost-Methode aufgerufen wird: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)

Das [Bind]-Attribut kann zum Schutz vor Overposting in Erstellungs szenarien (create) verwendet werden.The [Bind] attribute can be used to protect against overposting in create scenarios. Es funktioniert nicht gut in Bearbeitungsszenarien (edit), weil ausgeschlossene Eigenschaften auf „null“ oder einen Standardwert festgelegt werden, anstatt unverändert zu bleiben.It doesn't work well in edit scenarios because excluded properties are set to null or a default value instead of being left unchanged. Zum Schutz vor Overposting werden Ansichtsmodelle empfohlen, anstelle des [Bind]-Attributs.For defense against overposting, view models are recommended rather than the [Bind] attribute. Weitere Informationen finden Sie unter Sicherheitshinweis zum Overposting.For more information, see Security note about overposting.

AuflistungenCollections

Bei Zielen, die Sammlungen einfacher Typen sind, sucht die Modellbindung nach Übereinstimmungen mit parameter_name oder property_name.For targets that are collections of simple types, model binding looks for matches to parameter_name or property_name. Wird keine Übereinstimmung gefunden, sucht sie nach einem der unterstützten Formate ohne Präfix.If no match is found, it looks for one of the supported formats without the prefix. Beispiel:For example:

  • Angenommen, der zu bindende Parameter ist ein Array namens selectedCourses:Suppose the parameter to be bound is an array named selectedCourses:

    public IActionResult OnPost(int? id, int[] selectedCourses)

  • Formular- oder Abfragezeichenfolgendaten können eins der folgenden Formate haben: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

  • Das folgende Format wird nur für Formulardaten unterstützt:The following format is supported only in form data:

    selectedCourses[]=1050&selectedCourses[]=2000

  • Bei allen der vorangehenden Beispielformate übergibt die Modellbindung ein Array von zwei Elementen an den selectedCourses-Parameter: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

    Datenformate, die Indexnummern verwenden(... [0]... [1] ...), müssen sicherstellen, dass sie fortlaufend nummeriert sind, beginnend mit 0 (null).Data formats that use subscript numbers (... [0] ... [1] ...) must ensure that they are numbered sequentially starting at zero. Treten bei der Indexnummerierung Lücken auf, werden alle Elemente, die auf die Lücke folgen, ignoriert.If there are any gaps in subscript numbering, all items after the gap are ignored. Wenn die Indizes beispielsweise 0 und 2 anstelle von 0 und 1 sind, wird beispielsweise das zweite Element ignoriert.For example, if the subscripts are 0 and 2 instead of 0 and 1, the second item is ignored.

WörterbücherDictionaries

Bei Dictionary-Zielen sucht die Modellbindung nach Übereinstimmungen mit parameter_name oder property_name.For Dictionary targets, model binding looks for matches to parameter_name or property_name. Wird keine Übereinstimmung gefunden, sucht sie nach einem der unterstützten Formate ohne Präfix.If no match is found, it looks for one of the supported formats without the prefix. Beispiel:For example:

  • Angenommen, der Zielparameter ist eine Dictionary<int, string> mit dem Namen selectedCourses:Suppose the target parameter is a Dictionary<int, string> named selectedCourses:

    public IActionResult OnPost(int? id, Dictionary<int, string> selectedCourses)

  • Die bereitgestellten Formular- oder Abfragezeichenfolgendaten können wie eins der folgenden Beispiele aussehen: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

  • Bei allen der vorangehenden Beispielformate übergibt die Modellbindung ein Wörterbuch aus zwei Elementen an den selectedCourses-Parameter: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"

Globalisierungsverhalten der Routendaten und Abfragezeichenfolgen für die ModellbindungGlobalization behavior of model binding route data and query strings

Der ASP.NET Core-Routenwertanbieter und der Abfragezeichenfolgenwert-Anbieter:The ASP.NET Core route value provider and query string value provider:

  • behandeln Werte als invariante Kulturen.Treat values as invariant culture.
  • erwarten, dass URLs kulturinvariant sind.Expect that URLs are culture-invariant.

Im Gegensatz dazu durchlaufen Werte, die aus Formulardaten stammen, eine kulturabhängige Konvertierung.In contrast, values coming from form data undergo a culture-sensitive conversion. Dies ist beabsichtigt, damit URLs zwischen Gebietsschemas freigegeben werden können.This is by design so that URLs are shareable across locales.

So lassen Sie den ASP.NET Core-Routenwertanbieter und den Abfragezeichenfolgenwert-Anbieter eine kulturabhängige Konvertierung durchlaufen:To make the ASP.NET Core route value provider and query string value provider undergo a culture-sensitive conversion:

services.AddMvc(options =>
{
    var index = options.ValueProviderFactories.IndexOf(
        options.ValueProviderFactories.OfType<QueryStringValueProviderFactory>().Single());
    options.ValueProviderFactories[index] = new CulturedQueryStringValueProviderFactory();
});

public class CulturedQueryStringValueProviderFactory : IValueProviderFactory
{
    public Task CreateValueProviderAsync(ValueProviderFactoryContext context)
    {
        if (context == null)
        {
            throw new ArgumentNullException(nameof(context));
        }

        var query = context.ActionContext.HttpContext.Request.Query;
        if (query != null && query.Count > 0)
        {
            var valueProvider = new QueryStringValueProvider(
                BindingSource.Query,
                query,
                CultureInfo.CurrentCulture);

            context.ValueProviders.Add(valueProvider);
        }

        return Task.CompletedTask;
    }
}

Spezielle DatentypenSpecial data types

Es gibt einige spezielle Datentypen, die die Modellbindung verarbeiten kann.There are some special data types that model binding can handle.

„IFormFile“ und „IFormFileCollection“IFormFile and IFormFileCollection

Eine in der HTTP-Anforderung enthaltene, hochgeladenen Datei.An uploaded file included in the HTTP request. Außerdem wird IEnumerable<IFormFile> für mehrere Dateien unterstützt.Also supported is IEnumerable<IFormFile> for multiple files.

CancellationTokenCancellationToken

Wird verwendet, um die Aktivität in asynchronen Controllern zu beenden.Used to cancel activity in asynchronous controllers.

„FormCollection“FormCollection

Wird verwendet, um alle Werte aus bereitgestellten Formulardaten abzurufen.Used to retrieve all the values from posted form data.

EingabeformatiererInput formatters

Daten im Anforderungstext können im JSON-, XML- oder einem anderen Format sein.Data in the request body can be in JSON, XML, or some other format. Um diese Daten zu analysieren, verwendet die Modellbindung einen Eingabeformatierer, der für die Verarbeitung eines bestimmten Inhaltstyps konfiguriert ist.To parse this data, model binding uses an input formatter that is configured to handle a particular content type. ASP.NET Core enthält standardmäßig JSON-basierte Eingabeformatierer für die Verarbeitung von JSON-Daten.By default, ASP.NET Core includes JSON based input formatters for handling JSON data. Sie können andere Formatierer für andere Inhaltstypen hinzufügen.You can add other formatters for other content types.

ASP.NET Core wählt Eingabeformatierer auf Grundlage des Consumes-Attributs aus.ASP.NET Core selects input formatters based on the Consumes attribute. Wenn kein Attribut vorhanden ist, verwendet es den Content-Type-Header.If no attribute is present, it uses the Content-Type header.

So verwenden Sie die integrierte XML-EingabeformatiererTo use the built-in XML input formatters:

  • Installieren Sie das NuGet-Paket Microsoft.AspNetCore.Mvc.Formatters.Xml.Install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

  • In Startup.ConfigureServices, rufen Sie AddXmlSerializerFormatters oder AddXmlDataContractSerializerFormatters auf.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);

  • Wenden Sie das Consumes-Attribut auf Controllerklassen oder Aktionsmethoden an, die XML im Anforderungstext erwarten sollten.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)

    Weitere Informationen finden Sie unter Einführung der XML-Serialisierung.For more information, see Introducing XML Serialization.

Ausschließen angegebener Typen aus der ModellbindungExclude specified types from model binding

Das Verhalten der Modellbindung und des Validierungssystems wird von der Klasse ModelMetadata gesteuert.The model binding and validation systems' behavior is driven by ModelMetadata. Sie können ModelMetadata anpassen, indem Sie MvcOptions.ModelMetadataDetailsProviders einen Detailanbieter hinzufügen.You can customize ModelMetadata by adding a details provider to MvcOptions.ModelMetadataDetailsProviders. Integrierte Detailanbieter sind verfügbar, um die Modellbindung oder Validierung für angegebene Typen zu deaktivieren.Built-in details providers are available for disabling model binding or validation for specified types.

Um die Modellbindung für alle Modelle eines angegebenen Typs zu deaktivieren, fügen Sie in Startup.ConfigureServices einen ExcludeBindingMetadataProvider hinzu.To disable model binding on all models of a specified type, add an ExcludeBindingMetadataProvider in Startup.ConfigureServices. Beispielsweise können Sie die Modellbindung für alle Modelle vom Typ System.Version wie folgt deaktivieren: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);

Um die Validierung für Eigenschaften eines angegebenen Typs zu deaktivieren, fügen Sie in Startup.ConfigureServices einen SuppressChildValidationMetadataProvider hinzu.To disable validation on properties of a specified type, add a SuppressChildValidationMetadataProvider in Startup.ConfigureServices. Beispielsweise können Sie die Überprüfung von Eigenschaften vom Typ System.Guid wie folgt deaktivieren: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);

Benutzerdefinierte ModellbindungenCustom model binders

Sie können die Modellbindung erweitern, indem Sie eine benutzerdefinierte Modellbindung schreiben und das [ModelBinder]-Attribut verwenden, um diese für ein bestimmtes Ziel auszuwählen.You can extend model binding by writing a custom model binder and using the [ModelBinder] attribute to select it for a given target. Erfahren Sie mehr über die benutzerdefinierte Modellbindung.Learn more about custom model binding.

Manuelle ModellbindungManual model binding

Die Modellbindung kann mithilfe der TryUpdateModelAsync-Methode manuell aufgerufen werden.Model binding can be invoked manually by using the TryUpdateModelAsync method. Die Methode ist für die beiden Klassen ControllerBase und PageModel definiert.The method is defined on both ControllerBase and PageModel classes. Mithilfe von Methodenüberladungen können Sie das Präfix und den Wertanbieter festlegen, die verwendet werden sollen.Method overloads let you specify the prefix and value provider to use. Die Methode gibt false zurück, wenn die Modellbindung fehlschlägt.The method returns false if model binding fails. Hier sehen Sie ein Beispiel: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();

[FromServices]-Attribut[FromServices] attribute

Der Name dieses Attributs folgt dem Muster von Modellbindungsattributen, die eine Datenquelle angeben.This attribute's name follows the pattern of model binding attributes that specify a data source. Es ist aber nicht zum Binden von Daten aus einem Wertanbieter gedacht.But it's not about binding data from a value provider. Es ruft eine Instanz eines Typs aus dem Dependency Injection-Container (Abhängigkeitsinjektion) ab.It gets an instance of a type from the dependency injection container. Sein Zweck besteht darin, eine Alternative zur „Constructor Injection“ (Konstruktorinjektion) bereitzustellen, wenn Sie einen Dienst nur dann benötigen, wenn eine bestimmte Methode aufgerufen wird.Its purpose is to provide an alternative to constructor injection for when you need a service only if a particular method is called.

Zusätzliche RessourcenAdditional resources