Powiązanie modelu w ASP.NET CoreModel Binding in ASP.NET Core

W tym artykule wyjaśniono, co to jest powiązanie modelu, jak to działa i jak dostosować jego zachowanie.This article explains what model binding is, how it works, and how to customize its behavior.

Wyświetlanie lub Pobieranie przykładowego kodu (jak pobrać).View or download sample code (how to download).

Co to jest powiązanie modeluWhat is Model binding

Kontrolery i Razor strony współpracują z danymi, które pochodzą z żądań HTTP.Controllers and Razor pages work with data that comes from HTTP requests. Na przykład dane trasy mogą dostarczyć klucz rekordu, a pola ogłoszone formularza mogą podawać wartości właściwości modelu.For example, route data may provide a record key, and posted form fields may provide values for the properties of the model. Pisanie kodu w celu pobrania każdej z tych wartości i przekonwertowania ich z ciągów na typy .NET byłoby żmudnym i podatne na błędy.Writing code to retrieve each of these values and convert them from strings to .NET types would be tedious and error-prone. Powiązanie modelu automatyzuje ten proces.Model binding automates this process. System powiązań modelu:The model binding system:

  • Pobiera dane z różnych źródeł, takich jak dane tras, pola formularzy i ciągi zapytań.Retrieves data from various sources such as route data, form fields, and query strings.
  • Dostarcza dane do kontrolerów i Razor stron w parametrach metod i właściwościach publicznych.Provides the data to controllers and Razor pages in method parameters and public properties.
  • Konwertuje dane ciągu na typy .NET.Converts string data to .NET types.
  • Aktualizuje właściwości typów złożonych.Updates properties of complex types.

PrzykładExample

Załóżmy, że masz następującą metodę działania:Suppose you have the following action method:

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

A aplikacja odbiera żądanie przy użyciu tego adresu URL:And the app receives a request with this URL:

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

Powiązanie modelu przechodzi przez następujące kroki, gdy system routingu wybierze metodę akcji:Model binding goes through the following steps after the routing system selects the action method:

  • Znajduje pierwszy parametr z GetByID , liczba całkowita o nazwie id .Finds the first parameter of GetByID, an integer named id.
  • Wyszukuje dostępne źródła w żądaniu HTTP i odnajduje id = "2" w danych trasy.Looks through the available sources in the HTTP request and finds id = "2" in route data.
  • Konwertuje ciąg "2" na liczbę całkowitą 2.Converts the string "2" into integer 2.
  • Znajduje następny parametr elementu GetByID , wartość logiczna o nazwie dogsOnly .Finds the next parameter of GetByID, a boolean named dogsOnly.
  • Wyszukuje źródła i wyszukuje ciąg "DogsOnly = true" w ciągu zapytania.Looks through the sources and finds "DogsOnly=true" in the query string. W dopasowaniu nazw nie jest rozróżniana wielkość liter.Name matching is not case-sensitive.
  • Konwertuje ciąg "true" na wartość logiczną true .Converts the string "true" into boolean true.

Struktura następnie wywołuje GetById metodę, przekazując wartość 2 dla id parametru i true dla dogsOnly parametru.The framework then calls the GetById method, passing in 2 for the id parameter, and true for the dogsOnly parameter.

W poprzednim przykładzie elementy docelowe powiązań modelu to parametry metody, które są typami prostymi.In the preceding example, the model binding targets are method parameters that are simple types. Elementy docelowe mogą być również właściwościami typu złożonego.Targets may also be the properties of a complex type. Po pomyślnym powiązaniu każdej właściwości Walidacja modelu jest wykonywana dla tej właściwości.After each property is successfully bound, model validation occurs for that property. Rekord danych powiązanych z modelem oraz wszelkie błędy powiązań lub walidacji są przechowywane w ControllerBase. ModelState lub 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. Aby dowiedzieć się, czy ten proces zakończył się pomyślnie, aplikacja sprawdza flagę ModelState. IsValid .To find out if this process was successful, the app checks the ModelState.IsValid flag.

Obiekty doceloweTargets

Powiązanie modelu próbuje znaleźć wartości dla następujących rodzajów obiektów docelowych:Model binding tries to find values for the following kinds of targets:

  • Parametry metody akcji kontrolera, do której jest kierowane żądanie.Parameters of the controller action method that a request is routed to.
  • Parametry Razor metody obsługi stron, do której jest kierowane żądanie.Parameters of the Razor Pages handler method that a request is routed to.
  • Właściwości publiczne kontrolera lub PageModel klasy, jeśli są określone przez atrybuty.Public properties of a controller or PageModel class, if specified by attributes.

[BindProperty] — atrybut[BindProperty] attribute

Można zastosować do właściwości publicznej kontrolera lub PageModel klasy, aby spowodować powiązanie modelu z celem tej właściwości: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] — atrybut[BindProperties] attribute

Dostępne w ASP.NET Core 2,1 i nowszych.Available in ASP.NET Core 2.1 and later. Można zastosować do kontrolera lub PageModel klasy, aby poinformować powiązanie modelu z elementem docelowym wszystkich właściwości publicznych klasy: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; }

Powiązanie modelu dla żądań HTTP GETModel binding for HTTP GET requests

Domyślnie właściwości nie są powiązane z żądaniami HTTP GET.By default, properties are not bound for HTTP GET requests. Zazwyczaj wszystkie potrzebne do żądania GET są parametrem identyfikatora rekordu.Typically, all you need for a GET request is a record ID parameter. Identyfikator rekordu służy do wyszukiwania elementu w bazie danych.The record ID is used to look up the item in the database. W związku z tym nie ma potrzeby powiązania właściwości, która przechowuje wystąpienie modelu.Therefore, there is no need to bind a property that holds an instance of the model. W scenariuszach, w których właściwości są powiązane z żądaniami GET, należy ustawić SupportsGet Właściwość na 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; }

ŹródłaSources

Domyślnie powiązanie modelu pobiera dane w postaci par klucz-wartość z następujących źródeł w żądaniu HTTP:By default, model binding gets data in the form of key-value pairs from the following sources in an HTTP request:

  1. Pola formularzaForm fields
  2. Treść żądania (dla kontrolerów, które mają atrybut [ApiController]).The request body (For controllers that have the [ApiController] attribute.)
  3. Dane trasyRoute data
  4. Parametry ciągu zapytaniaQuery string parameters
  5. Przekazane plikiUploaded files

Dla każdego parametru lub właściwości docelowej źródła są skanowane w kolejności wskazanej na poprzedniej liście.For each target parameter or property, the sources are scanned in the order indicated in the preceding list. Istnieje kilka wyjątków:There are a few exceptions:

  • Dane trasy i wartości ciągu zapytania są używane tylko dla typów prostych.Route data and query string values are used only for simple types.
  • Przekazane pliki są powiązane tylko z typami docelowymi implementującymi IFormFile lub IEnumerable<IFormFile> .Uploaded files are bound only to target types that implement IFormFile or IEnumerable<IFormFile>.

Jeśli źródło domyślne jest niepoprawne, użyj jednego z następujących atrybutów, aby określić Źródło:If the default source is not correct, use one of the following attributes to specify the source:

Następujące atrybuty:These attributes:

  • Są dodawane do właściwości modelu pojedynczo (nie do klasy modelu), jak w poniższym przykładzie: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; }
    
  • Opcjonalnie Zaakceptuj wartość nazwy modelu w konstruktorze.Optionally accept a model name value in the constructor. Ta opcja jest dostępna w przypadku, gdy nazwa właściwości nie jest zgodna z wartością w żądaniu.This option is provided in case the property name doesn't match the value in the request. Na przykład wartość w żądaniu może być nagłówkiem z łącznikiem w nazwie, jak w poniższym przykładzie: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] — atrybut[FromBody] attribute

Zastosuj [FromBody] atrybut do parametru, aby wypełnić jego właściwości z treści żądania HTTP.Apply the [FromBody] attribute to a parameter to populate its properties from the body of an HTTP request. Środowisko uruchomieniowe ASP.NET Core deleguje odpowiedzialność za odczytanie treści do wejściowego programu formatującego.The ASP.NET Core runtime delegates the responsibility of reading the body to an input formatter. Dane wejściowe są wyjaśnione w dalszej części tego artykułu.Input formatters are explained later in this article.

Gdy [FromBody] jest stosowany do parametru typu złożonego, wszystkie atrybuty źródła powiązań zastosowane do jego właściwości są ignorowane.When [FromBody] is applied to a complex type parameter, any binding source attributes applied to its properties are ignored. Na przykład Poniższa Create Akcja określa, że jego pet parametr jest wypełniany w treści:For example, the following Create action specifies that its pet parameter is populated from the body:

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

PetKlasa określa, że jej Breed Właściwość jest wypełniana przy użyciu parametru ciągu zapytania: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; }
}

W powyższym przykładzie:In the preceding example:

  • [FromQuery]Atrybut jest ignorowany.The [FromQuery] attribute is ignored.
  • BreedWłaściwość nie jest wypełniona z parametru ciągu zapytania.The Breed property is not populated from a query string parameter.

W danych wejściowych programu formatującego są odczytywane tylko treści i nie są rozpoznawane atrybuty źródłowe powiązania.Input formatters read only the body and don't understand binding source attributes. Jeśli w treści zostanie znaleziona odpowiednia wartość, ta wartość jest używana do wypełniania Breed właściwości.If a suitable value is found in the body, that value is used to populate the Breed property.

Nie stosuj [FromBody] do więcej niż jednego parametru na metodę akcji.Don't apply [FromBody] to more than one parameter per action method. Gdy strumień żądania jest odczytywany przez dane wejściowe programu formatującego, nie jest już dostępny do ponownego odczytywania dla powiązań innych [FromBody] parametrów.Once the request stream is read by an input formatter, it's no longer available to be read again for binding other [FromBody] parameters.

Dodatkowe źródłaAdditional sources

Dane źródłowe są dostarczane do systemu powiązań modelu przez dostawców wartości.Source data is provided to the model binding system by value providers. Można napisać i zarejestrować dostawców wartości niestandardowych, którzy pobierają dane dla powiązania modelu z innych źródeł.You can write and register custom value providers that get data for model binding from other sources. Na przykład możesz potrzebować danych z cookie lub stanu sesji.For example, you might want data from cookies or session state. Aby pobrać dane z nowego źródła:To get data from a new source:

  • Utwórz klasę implementującą IValueProvider .Create a class that implements IValueProvider.
  • Utwórz klasę implementującą IValueProviderFactory .Create a class that implements IValueProviderFactory.
  • Zarejestruj klasę fabryki w Startup.ConfigureServices .Register the factory class in Startup.ConfigureServices.

Aplikacja Przykładowa zawiera dostawcę wartości i przykład fabryki , który pobiera wartości z cookie s.The sample app includes a value provider and factory example that gets values from cookies. Oto kod rejestracji w programie 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();

Pokazany kod umieszcza niestandardowego dostawcę wartości po wszystkich wbudowanych dostawcach wartości.The code shown puts the custom value provider after all the built-in value providers. Aby najpierw utworzyć go na liście, należy wywołać Insert(0, new CookieValueProviderFactory()) zamiast Add .To make it the first in the list, call Insert(0, new CookieValueProviderFactory()) instead of Add.

Brak źródła dla właściwości modeluNo source for a model property

Domyślnie błąd stanu modelu nie jest tworzony, jeśli dla właściwości modelu nie znaleziono żadnej wartości.By default, a model state error isn't created if no value is found for a model property. Właściwość jest ustawiona na null lub wartość domyślną:The property is set to null or a default value:

  • Typy proste o wartości null są ustawione na wartość null .Nullable simple types are set to null.
  • Typy wartości, które nie są dopuszczane do wartości null, są ustawione na default(T) .Non-nullable value types are set to default(T). Na przykład parametr int id jest ustawiony na 0.For example, a parameter int id is set to 0.
  • W przypadku typów złożonych powiązanie modelu tworzy wystąpienie przy użyciu domyślnego konstruktora bez ustawiania właściwości.For complex Types, model binding creates an instance by using the default constructor, without setting properties.
  • Tablice są ustawiane na Array.Empty<T>() , z tą różnicą, że byte[] tablice są ustawione na null .Arrays are set to Array.Empty<T>(), except that byte[] arrays are set to null.

Jeśli stan modelu ma być unieważniony, gdy nic nie zostanie znalezione w polach formularza dla właściwości modelu, użyj [BindRequired] atrybutu.If model state should be invalidated when nothing is found in form fields for a model property, use the [BindRequired] attribute.

Należy zauważyć, że to [BindRequired] zachowanie ma zastosowanie do powiązania modelu z ogłoszonych danych formularza, nie do danych JSON ani XML w treści żądania.Note that this [BindRequired] behavior applies to model binding from posted form data, not to JSON or XML data in a request body. Dane treści żądania są obsługiwane przez elementy formatujące dane wejściowe.Request body data is handled by input formatters.

Błędy konwersji typówType conversion errors

Jeśli źródło zostanie znalezione, ale nie można go przekonwertować na typ docelowy, stan modelu jest oflagowany jako nieprawidłowy.If a source is found but can't be converted into the target type, model state is flagged as invalid. Parametr lub właściwość docelowa jest ustawiona na null lub wartość domyślną, jak wskazano w poprzedniej sekcji.The target parameter or property is set to null or a default value, as noted in the previous section.

W kontrolerze interfejsu API, który ma [ApiController] atrybut, nieprawidłowy stan modelu powoduje automatyczne odpowiedź HTTP 400.In an API controller that has the [ApiController] attribute, invalid model state results in an automatic HTTP 400 response.

Na Razor stronie ponownie Wyświetl stronę z komunikatem o błędzie: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");
}

Weryfikacja po stronie klienta umożliwia przechwycenie najbardziej nieprawidłowych danych, które w przeciwnym razie zostałyby przesłane do Razor formularza stron.Client-side validation catches most bad data that would otherwise be submitted to a Razor Pages form. Ta weryfikacja sprawia, że trudno jest wyzwolić poprzedni wyróżniony kod.This validation makes it hard to trigger the preceding highlighted code. Przykładowa aplikacja zawiera przycisk Prześlij z nieprawidłowym dniem , który umieszcza złe dane w polu Data zatrudnienia i przesyła formularz.The sample app includes a Submit with Invalid Date button that puts bad data in the Hire Date field and submits the form. Ten przycisk pokazuje, w jaki sposób kod na potrzeby wyświetlania strony działa po wystąpieniu błędów konwersji danych.This button shows how the code for redisplaying the page works when data conversion errors occur.

Gdy strona jest ponownie wyświetlana przez poprzedni kod, nieprawidłowe dane wejściowe nie są wyświetlane w polu formularza.When the page is redisplayed by the preceding code, the invalid input is not shown in the form field. Wynika to z faktu, że właściwość model ma wartość null lub domyślną.This is because the model property has been set to null or a default value. Nieprawidłowe dane wejściowe są wyświetlane w komunikacie o błędzie.The invalid input does appear in an error message. Jeśli jednak chcesz ponownie wyświetlić złe dane w polu formularza, rozważ, że właściwość model jest ciągiem i ręcznie wykonuje konwersję danych.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.

Ta sama strategia jest zalecana, jeśli nie chcesz, aby Błędy konwersji typów powodowały błędy stanu modelu.The same strategy is recommended if you don't want type conversion errors to result in model state errors. W takim przypadku należy zmienić wartość właściwości model na ciąg.In that case, make the model property a string.

Typy prosteSimple types

Typy proste, które tworzą spinacz modelu mogą konwertować ciągi źródłowe, w następujący sposób:The simple types that the model binder can convert source strings into include the following:

Typy złożoneComplex types

Typ złożony musi mieć publiczny Konstruktor domyślny i publiczne właściwości do zapisu do powiązania.A complex type must have a public default constructor and public writable properties to bind. W przypadku wystąpienia powiązania modelu Klasa jest tworzona przy użyciu publicznego konstruktora domyślnego.When model binding occurs, the class is instantiated using the public default constructor.

Dla każdej właściwości typu złożonego powiązanie modelu wyszukuje źródła nazwy wzorca prefix.property_name.For each property of the complex type, model binding looks through the sources for the name pattern prefix.property_name. Jeśli nic nie zostanie znalezione, szuka tylko property_name bez prefiksu.If nothing is found, it looks for just property_name without the prefix.

W przypadku powiązania z parametrem prefiks jest nazwą parametru.For binding to a parameter, the prefix is the parameter name. W przypadku powiązania z PageModel właściwością publiczną prefiks jest publiczną nazwą właściwości.For binding to a PageModel public property, the prefix is the public property name. Niektóre atrybuty mają Prefix Właściwość, która pozwala zastąpić domyślne użycie parametru lub nazwy właściwości.Some attributes have a Prefix property that lets you override the default usage of parameter or property name.

Na przykład, Załóżmy, że typ złożony jest następującą Instructor klasą: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; }
}

Prefix = Nazwa parametruPrefix = parameter name

Jeśli modelem, który ma zostać powiązany, jest parametr o nazwie instructorToUpdate :If the model to be bound is a parameter named instructorToUpdate:

public IActionResult OnPost(int? id, Instructor instructorToUpdate)

Powiązanie modelu zaczyna się od przejrzenia źródeł klucza instructorToUpdate.ID .Model binding starts by looking through the sources for the key instructorToUpdate.ID. Jeśli ta wartość nie zostanie znaleziona, szuka ID bez prefiksu.If that isn't found, it looks for ID without a prefix.

Prefix = nazwa właściwościPrefix = property name

Jeśli modelem do powiązania jest właściwość o nazwie Instructor kontrolera lub PageModel klasy:If the model to be bound is a property named Instructor of the controller or PageModel class:

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

Powiązanie modelu zaczyna się od przejrzenia źródeł klucza Instructor.ID .Model binding starts by looking through the sources for the key Instructor.ID. Jeśli ta wartość nie zostanie znaleziona, szuka ID bez prefiksu.If that isn't found, it looks for ID without a prefix.

Prefiks niestandardowyCustom prefix

Jeśli model do powiązania jest parametrem o nazwie instructorToUpdate i Bind atrybut określa Instructor jako prefiks: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)

Powiązanie modelu zaczyna się od przejrzenia źródeł klucza Instructor.ID .Model binding starts by looking through the sources for the key Instructor.ID. Jeśli ta wartość nie zostanie znaleziona, szuka ID bez prefiksu.If that isn't found, it looks for ID without a prefix.

Atrybuty dla obiektów docelowych typu złożonegoAttributes for complex type targets

Dostępne są kilka wbudowanych atrybutów do kontrolowania powiązania modelu typów złożonych:Several built-in attributes are available for controlling model binding of complex types:

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

Ostrzeżenie

Te atrybuty wpływają na powiązanie modelu, gdy dane formularza ogłoszonego są źródłem wartości.These attributes affect model binding when posted form data is the source of values. Nie mają one wpływu na wejściowe elementy formatujące, które przetwarzają ogłoszone treści JSON i XML.They do *not _ affect input formatters, which process posted JSON and XML request bodies. Dane wejściowe są wyjaśnione w dalszej części tego artykułu.Input formatters are explained later in this article.

[Bind] — atrybut[Bind] attribute

Można zastosować do klasy lub parametru metody.Can be applied to a class or a method parameter. Określa, które właściwości modelu powinny być dołączone do powiązania modelu.Specifies which properties of a model should be included in model binding. [Bind] nie ma wpływu na wejściowe elementy formatujące.[Bind] does not affect input formatters.

W poniższym przykładzie tylko określone właściwości Instructor modelu są powiązane, gdy wywoływana jest jakakolwiek procedura obsługi lub metoda działania: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

W poniższym przykładzie tylko określone właściwości Instructor modelu są powiązane, gdy OnPost wywoływana jest metoda: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)

Ten [Bind] atrybut może służyć do ochrony przed nadużyciem w scenariuszach _create *.The [Bind] attribute can be used to protect against overposting in _create* scenarios. Nie działa prawidłowo w scenariuszach edycji, ponieważ wykluczone właściwości mają ustawioną wartość null lub wartość domyślną, a nie jako pozostawione bez zmian.It doesn't work well in edit scenarios because excluded properties are set to null or a default value instead of being left unchanged. W celu zapewnienia obrony przed przekroczeniem, zaleca się, aby zamiast [Bind] atrybutu.For defense against overposting, view models are recommended rather than the [Bind] attribute. Aby uzyskać więcej informacji, zobacz temat Security uwagi dotyczący przefinalizowania.For more information, see Security note about overposting.

[ModelBinder] — atrybut[ModelBinder] attribute

ModelBinderAttribute można zastosować do typów, właściwości lub parametrów.ModelBinderAttribute can be applied to types, properties, or parameters. Umożliwia określenie typu spinacza modelu używanego do powiązania określonego wystąpienia lub typu.It allows specifying the type of model binder used to bind the specific instance or type. Przykład:For example:

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

Ten [ModelBinder] atrybut może być również używany do zmiany nazwy właściwości lub parametru, gdy jest on powiązany z modelem: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] — atrybut[BindRequired] attribute

Można stosować tylko do właściwości modelu, a nie do parametrów metody.Can only be applied to model properties, not to method parameters. Powoduje, że powiązanie modelu umożliwia dodanie błędu stanu modelu, Jeśli powiązanie nie może wystąpić dla właściwości modelu.Causes model binding to add a model state error if binding cannot occur for a model's property. Oto przykład: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; }

Zobacz również Omówienie [Required] atrybutu w walidacji modelu.See also the discussion of the [Required] attribute in Model validation.

[BindNever] — atrybut[BindNever] attribute

Można stosować tylko do właściwości modelu, a nie do parametrów metody.Can only be applied to model properties, not to method parameters. Uniemożliwia powiązanie modelu z ustawiania właściwości modelu.Prevents model binding from setting a model's property. Oto przykład:Here's an example:

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

KolekcjeCollections

Dla celów, które są kolekcjami typów prostych, powiązanie modelu wyszukuje dopasowania do parameter_name lub property_name.For targets that are collections of simple types, model binding looks for matches to parameter_name or property_name. Jeśli dopasowanie nie zostanie znalezione, szuka jednego z obsługiwanych formatów bez prefiksu.If no match is found, it looks for one of the supported formats without the prefix. Przykład:For example:

  • Załóżmy, że parametr, który ma zostać powiązany, jest tablicą o nazwie selectedCourses :Suppose the parameter to be bound is an array named selectedCourses:

    public IActionResult OnPost(int? id, int[] selectedCourses)
    
  • Dane formularza lub ciągu zapytania mogą znajdować się w jednym z następujących formatów: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
    
  • Następujący format jest obsługiwany tylko w danych formularza:The following format is supported only in form data:

    selectedCourses[]=1050&selectedCourses[]=2000
    
  • We wszystkich powyższych formatach przykładowe powiązanie modelu przekazuje tablicę dwóch elementów do selectedCourses parametru: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

    Formaty danych używające liczb indeksów dolnych (... [0]... [1]...) należy upewnić się, że są numerowane sekwencyjnie, zaczynając od zera.Data formats that use subscript numbers (... [0] ... [1] ...) must ensure that they are numbered sequentially starting at zero. Jeśli występują luki w numerze indeksu dolnego, wszystkie elementy po przerwie zostaną zignorowane.If there are any gaps in subscript numbering, all items after the gap are ignored. Na przykład, jeśli indeksy dolne są równe 0 i 2 zamiast 0 i 1, drugi element jest ignorowany.For example, if the subscripts are 0 and 2 instead of 0 and 1, the second item is ignored.

SłownikiDictionaries

Dla Dictionary elementów docelowych powiązanie modelu wyszukuje dopasowania do parameter_name lub property_name.For Dictionary targets, model binding looks for matches to parameter_name or property_name. Jeśli dopasowanie nie zostanie znalezione, szuka jednego z obsługiwanych formatów bez prefiksu.If no match is found, it looks for one of the supported formats without the prefix. Przykład:For example:

  • Załóżmy, że parametr docelowy jest Dictionary<int, string> nazwany selectedCourses :Suppose the target parameter is a Dictionary<int, string> named selectedCourses:

    public IActionResult OnPost(int? id, Dictionary<int, string> selectedCourses)
    
  • Ogłoszone dane formularza lub ciągu zapytania mogą wyglądać jak w jednym z następujących przykładów: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
    
  • We wszystkich powyższych formatach przykładowe powiązanie modelu przekazuje słownik dwóch elementów do selectedCourses parametru:For all of the preceding example formats, model binding passes a dictionary of two items to the selectedCourses parameter:

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

Typy powiązań konstruktora i rekordówConstructor binding and record types

Powiązanie modelu wymaga, aby typy złożone miały Konstruktor bez parametrów.Model binding requires that complex types have a parameterless constructor. Zarówno programowy System.Text.Json , jak i Newtonsoft.Json oparty na danych wejściowych elementy formatujące obsługują deserializacja klas, które nie mają konstruktora bez parametrów.Both System.Text.Json and Newtonsoft.Json based input formatters support deserialization of classes that don't have a parameterless constructor.

W języku C# 9 wprowadzono typy rekordów, które są doskonałym sposobem na zwięzłe przedstawianie danych przez sieć.C# 9 introduces record types, which are a great way to succinctly represent data over the network. ASP.NET Core dodaje obsługę powiązania modelu i sprawdzanie poprawności typów rekordów przy użyciu pojedynczego konstruktora: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);

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" />

Podczas sprawdzania poprawności typów rekordów środowisko uruchomieniowe wyszukuje metadane walidacji w zależności od parametrów, a nie właściwości.When validating record types, the runtime searches for validation metadata specifically on parameters rather than on properties.

Zachowanie globalizacji danych tras powiązań modelu i ciągów zapytańGlobalization behavior of model binding route data and query strings

Dostawca wartości ASP.NET Core tras i dostawcy wartości ciągu zapytania:The ASP.NET Core route value provider and query string value provider:

  • Traktuj wartości jako niezmienną kulturę.Treat values as invariant culture.
  • Należy oczekiwać, że adresy URL są kulturą niezmienną.Expect that URLs are culture-invariant.

Natomiast wartości pochodzące z danych formularza są przekształcane z uwzględnieniem kultury.In contrast, values coming from form data undergo a culture-sensitive conversion. Jest to zaprojektowane w taki sposób, aby adresy URL były udostępniane w ustawieniach regionalnych.This is by design so that URLs are shareable across locales.

Aby dostawca wartości ASP.NET Core trasy i dostawca wartości ciągu zapytania były poddawane konwersji zależnej od kultury: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;
    }
}

Specjalne typy danychSpecial data types

Istnieją specjalne typy danych, które może obsłużyć powiązanie modelu.There are some special data types that model binding can handle.

IFormFile i IFormFileCollectionIFormFile and IFormFileCollection

Przekazany plik uwzględniony w żądaniu HTTP.An uploaded file included in the HTTP request. Obsługiwane jest również IEnumerable<IFormFile> dla wielu plików.Also supported is IEnumerable<IFormFile> for multiple files.

CancellationTokenCancellationToken

Akcje można opcjonalnie powiązać CancellationToken jako parametr.Actions can optionally bind a CancellationToken as a parameter. To wiąże RequestAborted się z tym, że w przypadku przerwania połączenia z żądaniem http zostało przerwane.This binds RequestAborted that signals when the connection underlying the HTTP request is aborted. Akcje mogą używać tego parametru, aby anulować długotrwałe operacje asynchroniczne, które są wykonywane w ramach akcji kontrolera.Actions can use this parameter to cancel long running async operations that are executed as part of the controller actions.

FormularzFormCollection

Służy do pobierania wszystkich wartości z ogłoszonych danych formularza.Used to retrieve all the values from posted form data.

Wejściowe elementy formatująceInput formatters

Dane w treści żądania mogą być w formacie JSON, XML lub innym.Data in the request body can be in JSON, XML, or some other format. Aby przeanalizować te dane, powiązanie modelu korzysta z wejściowego programu formatującego , który jest skonfigurowany do obsługi określonego typu zawartości.To parse this data, model binding uses an input formatter that is configured to handle a particular content type. Domyślnie ASP.NET Core zawiera dane wejściowe w formacie JSON na potrzeby obsługi danych JSON.By default, ASP.NET Core includes JSON based input formatters for handling JSON data. Można dodać inne elementy formatujące dla innych typów zawartości.You can add other formatters for other content types.

ASP.NET Core wybiera wejściowe elementy formatujące na podstawie atrybutu użycia .ASP.NET Core selects input formatters based on the Consumes attribute. Jeśli atrybut nie jest obecny, używa nagłówka Content-Type.If no attribute is present, it uses the Content-Type header.

Aby użyć wbudowanych elementów formatujących dane wejściowe XML:To use the built-in XML input formatters:

  • Zainstaluj Microsoft.AspNetCore.Mvc.Formatters.Xml pakiet NuGet.Install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

  • W Startup.ConfigureServices , wywołaj AddXmlSerializerFormatters lub AddXmlDataContractSerializerFormatters .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();
    
  • Zastosuj Consumes atrybut do klas kontrolera lub metod akcji, które powinny oczekiwać XML w treści żądania.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)
    

    Aby uzyskać więcej informacji, zobacz wprowadzenie serializacji XML.For more information, see Introducing XML Serialization.

Dostosowywanie powiązania modelu z użyciem danych wejściowychCustomize model binding with input formatters

Wejściowy program formatujący pobiera pełną odpowiedzialność za odczytywanie danych z treści żądania.An input formatter takes full responsibility for reading data from the request body. Aby dostosować ten proces, należy skonfigurować interfejsy API używane przez dane wejściowe programu formatującego.To customize this process, configure the APIs used by the input formatter. W tej sekcji opisano sposób dostosowywania programu System.Text.Json formatującego wejściowego opartego na danych wejściowych w celu zrozumienia niestandardowego typu o nazwie ObjectId .This section describes how to customize the System.Text.Json-based input formatter to understand a custom type named ObjectId.

Rozważmy następujący model, który zawiera właściwość niestandardową ObjectId o nazwie Id :Consider the following model, which contains a custom ObjectId property named Id:

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

Aby dostosować proces powiązania modelu przy użyciu System.Text.Json , Utwórz klasę pochodną JsonConverter<T> :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);
    }
}

Aby użyć niestandardowego konwertera, Zastosuj JsonConverterAttribute atrybut do typu.To use a custom converter, apply the JsonConverterAttribute attribute to the type. W poniższym przykładzie ObjectId Typ jest skonfigurowany z użyciem ObjectIdConverter jako konwertera niestandardowego: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; }
}

Aby uzyskać więcej informacji, zobacz jak pisać konwertery niestandardowe.For more information, see How to write custom converters.

Wyklucz określone typy z powiązania modeluExclude specified types from model binding

Zachowanie modelu powiązań i systemów walidacji jest zależne od ModelMetadata.The model binding and validation systems' behavior is driven by ModelMetadata. Można dostosować ModelMetadata , dodając dostawcę szczegółów do MvcOptions. ModelMetadataDetailsProviders.You can customize ModelMetadata by adding a details provider to MvcOptions.ModelMetadataDetailsProviders. Wbudowane dostawcy szczegółów są dostępne do wyłączenia powiązania modelu lub walidacji dla określonych typów.Built-in details providers are available for disabling model binding or validation for specified types.

Aby wyłączyć powiązanie modelu dla wszystkich modeli określonego typu, Dodaj element ExcludeBindingMetadataProvider w Startup.ConfigureServices .To disable model binding on all models of a specified type, add an ExcludeBindingMetadataProvider in Startup.ConfigureServices. Na przykład aby wyłączyć powiązanie modelu dla wszystkich modeli typu System.Version :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();

Aby wyłączyć walidację właściwości określonego typu, Dodaj element SuppressChildValidationMetadataProvider w Startup.ConfigureServices .To disable validation on properties of a specified type, add a SuppressChildValidationMetadataProvider in Startup.ConfigureServices. Na przykład aby wyłączyć walidację właściwości typu System.Guid :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();

Niestandardowe powiązania modeluCustom model binders

Można rozszerzać powiązania modelu, pisząc niestandardowy spinacz modelu i używając [ModelBinder] atrybutu, aby wybrać go dla danego elementu docelowego.You can extend model binding by writing a custom model binder and using the [ModelBinder] attribute to select it for a given target. Dowiedz się więcej na temat niestandardowego powiązania modelu.Learn more about custom model binding.

Ręczne powiązanie modeluManual model binding

Powiązanie modelu można wywołać ręcznie przy użyciu TryUpdateModelAsync metody.Model binding can be invoked manually by using the TryUpdateModelAsync method. Metoda jest zdefiniowana dla obu ControllerBase klas i PageModel .The method is defined on both ControllerBase and PageModel classes. Przeciążenia metod umożliwiają określenie prefiksu i dostawcy wartości do użycia.Method overloads let you specify the prefix and value provider to use. Metoda zwraca false Jeśli powiązanie modelu nie powiedzie się.The method returns false if model binding fails. Oto przykład: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 używa dostawców wartości do pobierania danych z formularza, ciągu zapytania i danych tras.TryUpdateModelAsync uses value providers to get data from the form body, query string, and route data. TryUpdateModelAsync zwykle:TryUpdateModelAsync is typically:

  • Używany ze Razor stronami i aplikacjami MVC korzystającymi z kontrolerów i widoków, aby zapobiec nadmiernemu księgowaniu.Used with Razor Pages and MVC apps using controllers and views to prevent over-posting.
  • Nieużywany z interfejsem API sieci Web, chyba że jest używane z danych formularza, ciągów zapytań i danych tras.Not used with a web API unless consumed from form data, query strings, and route data. Punkty końcowe interfejsu API sieci Web, które używają formatu JSON, do deserializacji treści żądania do obiektu.Web API endpoints that consume JSON use Input formatters to deserialize the request body into an object.

Aby uzyskać więcej informacji, zobacz TryUpdateModelAsync.For more information, see TryUpdateModelAsync.

[FromServices] — atrybut[FromServices] attribute

Nazwa tego atrybutu jest zgodna ze wzorcem atrybutów powiązania modelu, które określają źródło danych.This attribute's name follows the pattern of model binding attributes that specify a data source. Ale nie informacje o powiązaniu danych od dostawcy wartości.But it's not about binding data from a value provider. Pobiera wystąpienie typu z kontenera iniekcji zależności .It gets an instance of a type from the dependency injection container. Jego celem jest zapewnienie alternatywy dla iniekcji konstruktorów, gdy potrzebna jest usługa tylko wtedy, gdy jest wywoływana konkretna metoda.Its purpose is to provide an alternative to constructor injection for when you need a service only if a particular method is called.

Dodatkowe zasobyAdditional resources

W tym artykule wyjaśniono, co to jest powiązanie modelu, jak to działa i jak dostosować jego zachowanie.This article explains what model binding is, how it works, and how to customize its behavior.

Wyświetlanie lub Pobieranie przykładowego kodu (jak pobrać).View or download sample code (how to download).

Co to jest powiązanie modeluWhat is Model binding

Kontrolery i Razor strony współpracują z danymi, które pochodzą z żądań HTTP.Controllers and Razor pages work with data that comes from HTTP requests. Na przykład dane trasy mogą dostarczyć klucz rekordu, a pola ogłoszone formularza mogą podawać wartości właściwości modelu.For example, route data may provide a record key, and posted form fields may provide values for the properties of the model. Pisanie kodu w celu pobrania każdej z tych wartości i przekonwertowania ich z ciągów na typy .NET byłoby żmudnym i podatne na błędy.Writing code to retrieve each of these values and convert them from strings to .NET types would be tedious and error-prone. Powiązanie modelu automatyzuje ten proces.Model binding automates this process. System powiązań modelu:The model binding system:

  • Pobiera dane z różnych źródeł, takich jak dane tras, pola formularzy i ciągi zapytań.Retrieves data from various sources such as route data, form fields, and query strings.
  • Dostarcza dane do kontrolerów i Razor stron w parametrach metod i właściwościach publicznych.Provides the data to controllers and Razor pages in method parameters and public properties.
  • Konwertuje dane ciągu na typy .NET.Converts string data to .NET types.
  • Aktualizuje właściwości typów złożonych.Updates properties of complex types.

PrzykładExample

Załóżmy, że masz następującą metodę działania:Suppose you have the following action method:

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

A aplikacja odbiera żądanie przy użyciu tego adresu URL:And the app receives a request with this URL:

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

Powiązanie modelu przechodzi przez następujące kroki, gdy system routingu wybierze metodę akcji:Model binding goes through the following steps after the routing system selects the action method:

  • Znajduje pierwszy parametr z GetByID , liczba całkowita o nazwie id .Finds the first parameter of GetByID, an integer named id.
  • Wyszukuje dostępne źródła w żądaniu HTTP i odnajduje id = "2" w danych trasy.Looks through the available sources in the HTTP request and finds id = "2" in route data.
  • Konwertuje ciąg "2" na liczbę całkowitą 2.Converts the string "2" into integer 2.
  • Znajduje następny parametr elementu GetByID , wartość logiczna o nazwie dogsOnly .Finds the next parameter of GetByID, a boolean named dogsOnly.
  • Wyszukuje źródła i wyszukuje ciąg "DogsOnly = true" w ciągu zapytania.Looks through the sources and finds "DogsOnly=true" in the query string. W dopasowaniu nazw nie jest rozróżniana wielkość liter.Name matching is not case-sensitive.
  • Konwertuje ciąg "true" na wartość logiczną true .Converts the string "true" into boolean true.

Struktura następnie wywołuje GetById metodę, przekazując wartość 2 dla id parametru i true dla dogsOnly parametru.The framework then calls the GetById method, passing in 2 for the id parameter, and true for the dogsOnly parameter.

W poprzednim przykładzie elementy docelowe powiązań modelu to parametry metody, które są typami prostymi.In the preceding example, the model binding targets are method parameters that are simple types. Elementy docelowe mogą być również właściwościami typu złożonego.Targets may also be the properties of a complex type. Po pomyślnym powiązaniu każdej właściwości Walidacja modelu jest wykonywana dla tej właściwości.After each property is successfully bound, model validation occurs for that property. Rekord danych powiązanych z modelem oraz wszelkie błędy powiązań lub walidacji są przechowywane w ControllerBase. ModelState lub 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. Aby dowiedzieć się, czy ten proces zakończył się pomyślnie, aplikacja sprawdza flagę ModelState. IsValid .To find out if this process was successful, the app checks the ModelState.IsValid flag.

Obiekty doceloweTargets

Powiązanie modelu próbuje znaleźć wartości dla następujących rodzajów obiektów docelowych:Model binding tries to find values for the following kinds of targets:

  • Parametry metody akcji kontrolera, do której jest kierowane żądanie.Parameters of the controller action method that a request is routed to.
  • Parametry Razor metody obsługi stron, do której jest kierowane żądanie.Parameters of the Razor Pages handler method that a request is routed to.
  • Właściwości publiczne kontrolera lub PageModel klasy, jeśli są określone przez atrybuty.Public properties of a controller or PageModel class, if specified by attributes.

[BindProperty] — atrybut[BindProperty] attribute

Można zastosować do właściwości publicznej kontrolera lub PageModel klasy, aby spowodować powiązanie modelu z celem tej właściwości: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] — atrybut[BindProperties] attribute

Dostępne w ASP.NET Core 2,1 i nowszych.Available in ASP.NET Core 2.1 and later. Można zastosować do kontrolera lub PageModel klasy, aby poinformować powiązanie modelu z elementem docelowym wszystkich właściwości publicznych klasy: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; }

Powiązanie modelu dla żądań HTTP GETModel binding for HTTP GET requests

Domyślnie właściwości nie są powiązane z żądaniami HTTP GET.By default, properties are not bound for HTTP GET requests. Zazwyczaj wszystkie potrzebne do żądania GET są parametrem identyfikatora rekordu.Typically, all you need for a GET request is a record ID parameter. Identyfikator rekordu służy do wyszukiwania elementu w bazie danych.The record ID is used to look up the item in the database. W związku z tym nie ma potrzeby powiązania właściwości, która przechowuje wystąpienie modelu.Therefore, there is no need to bind a property that holds an instance of the model. W scenariuszach, w których właściwości są powiązane z żądaniami GET, należy ustawić SupportsGet Właściwość na 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; }

ŹródłaSources

Domyślnie powiązanie modelu pobiera dane w postaci par klucz-wartość z następujących źródeł w żądaniu HTTP:By default, model binding gets data in the form of key-value pairs from the following sources in an HTTP request:

  1. Pola formularzaForm fields
  2. Treść żądania (dla kontrolerów, które mają atrybut [ApiController]).The request body (For controllers that have the [ApiController] attribute.)
  3. Dane trasyRoute data
  4. Parametry ciągu zapytaniaQuery string parameters
  5. Przekazane plikiUploaded files

Dla każdego parametru lub właściwości docelowej źródła są skanowane w kolejności wskazanej na poprzedniej liście.For each target parameter or property, the sources are scanned in the order indicated in the preceding list. Istnieje kilka wyjątków:There are a few exceptions:

  • Dane trasy i wartości ciągu zapytania są używane tylko dla typów prostych.Route data and query string values are used only for simple types.
  • Przekazane pliki są powiązane tylko z typami docelowymi implementującymi IFormFile lub IEnumerable<IFormFile> .Uploaded files are bound only to target types that implement IFormFile or IEnumerable<IFormFile>.

Jeśli źródło domyślne jest niepoprawne, użyj jednego z następujących atrybutów, aby określić Źródło:If the default source is not correct, use one of the following attributes to specify the source:

Następujące atrybuty:These attributes:

  • Są dodawane do właściwości modelu pojedynczo (nie do klasy modelu), jak w poniższym przykładzie: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; }
    
  • Opcjonalnie Zaakceptuj wartość nazwy modelu w konstruktorze.Optionally accept a model name value in the constructor. Ta opcja jest dostępna w przypadku, gdy nazwa właściwości nie jest zgodna z wartością w żądaniu.This option is provided in case the property name doesn't match the value in the request. Na przykład wartość w żądaniu może być nagłówkiem z łącznikiem w nazwie, jak w poniższym przykładzie: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] — atrybut[FromBody] attribute

Zastosuj [FromBody] atrybut do parametru, aby wypełnić jego właściwości z treści żądania HTTP.Apply the [FromBody] attribute to a parameter to populate its properties from the body of an HTTP request. Środowisko uruchomieniowe ASP.NET Core deleguje odpowiedzialność za odczytanie treści do wejściowego programu formatującego.The ASP.NET Core runtime delegates the responsibility of reading the body to an input formatter. Dane wejściowe są wyjaśnione w dalszej części tego artykułu.Input formatters are explained later in this article.

Gdy [FromBody] jest stosowany do parametru typu złożonego, wszystkie atrybuty źródła powiązań zastosowane do jego właściwości są ignorowane.When [FromBody] is applied to a complex type parameter, any binding source attributes applied to its properties are ignored. Na przykład Poniższa Create Akcja określa, że jego pet parametr jest wypełniany w treści:For example, the following Create action specifies that its pet parameter is populated from the body:

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

PetKlasa określa, że jej Breed Właściwość jest wypełniana przy użyciu parametru ciągu zapytania: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; }
}

W powyższym przykładzie:In the preceding example:

  • [FromQuery]Atrybut jest ignorowany.The [FromQuery] attribute is ignored.
  • BreedWłaściwość nie jest wypełniona z parametru ciągu zapytania.The Breed property is not populated from a query string parameter.

W danych wejściowych programu formatującego są odczytywane tylko treści i nie są rozpoznawane atrybuty źródłowe powiązania.Input formatters read only the body and don't understand binding source attributes. Jeśli w treści zostanie znaleziona odpowiednia wartość, ta wartość jest używana do wypełniania Breed właściwości.If a suitable value is found in the body, that value is used to populate the Breed property.

Nie stosuj [FromBody] do więcej niż jednego parametru na metodę akcji.Don't apply [FromBody] to more than one parameter per action method. Gdy strumień żądania jest odczytywany przez dane wejściowe programu formatującego, nie jest już dostępny do ponownego odczytywania dla powiązań innych [FromBody] parametrów.Once the request stream is read by an input formatter, it's no longer available to be read again for binding other [FromBody] parameters.

Dodatkowe źródłaAdditional sources

Dane źródłowe są dostarczane do systemu powiązań modelu przez dostawców wartości.Source data is provided to the model binding system by value providers. Można napisać i zarejestrować dostawców wartości niestandardowych, którzy pobierają dane dla powiązania modelu z innych źródeł.You can write and register custom value providers that get data for model binding from other sources. Na przykład możesz potrzebować danych z cookie lub stanu sesji.For example, you might want data from cookies or session state. Aby pobrać dane z nowego źródła:To get data from a new source:

  • Utwórz klasę implementującą IValueProvider .Create a class that implements IValueProvider.
  • Utwórz klasę implementującą IValueProviderFactory .Create a class that implements IValueProviderFactory.
  • Zarejestruj klasę fabryki w Startup.ConfigureServices .Register the factory class in Startup.ConfigureServices.

Aplikacja Przykładowa zawiera dostawcę wartości i przykład fabryki , który pobiera wartości z cookie s.The sample app includes a value provider and factory example that gets values from cookies. Oto kod rejestracji w programie 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);

Pokazany kod umieszcza niestandardowego dostawcę wartości po wszystkich wbudowanych dostawcach wartości.The code shown puts the custom value provider after all the built-in value providers. Aby najpierw utworzyć go na liście, należy wywołać Insert(0, new CookieValueProviderFactory()) zamiast Add .To make it the first in the list, call Insert(0, new CookieValueProviderFactory()) instead of Add.

Brak źródła dla właściwości modeluNo source for a model property

Domyślnie błąd stanu modelu nie jest tworzony, jeśli dla właściwości modelu nie znaleziono żadnej wartości.By default, a model state error isn't created if no value is found for a model property. Właściwość jest ustawiona na null lub wartość domyślną:The property is set to null or a default value:

  • Typy proste o wartości null są ustawione na wartość null .Nullable simple types are set to null.
  • Typy wartości, które nie są dopuszczane do wartości null, są ustawione na default(T) .Non-nullable value types are set to default(T). Na przykład parametr int id jest ustawiony na 0.For example, a parameter int id is set to 0.
  • W przypadku typów złożonych powiązanie modelu tworzy wystąpienie przy użyciu domyślnego konstruktora bez ustawiania właściwości.For complex Types, model binding creates an instance by using the default constructor, without setting properties.
  • Tablice są ustawiane na Array.Empty<T>() , z tą różnicą, że byte[] tablice są ustawione na null .Arrays are set to Array.Empty<T>(), except that byte[] arrays are set to null.

Jeśli stan modelu ma być unieważniony, gdy nic nie zostanie znalezione w polach formularza dla właściwości modelu, użyj [BindRequired] atrybutu.If model state should be invalidated when nothing is found in form fields for a model property, use the [BindRequired] attribute.

Należy zauważyć, że to [BindRequired] zachowanie ma zastosowanie do powiązania modelu z ogłoszonych danych formularza, nie do danych JSON ani XML w treści żądania.Note that this [BindRequired] behavior applies to model binding from posted form data, not to JSON or XML data in a request body. Dane treści żądania są obsługiwane przez elementy formatujące dane wejściowe.Request body data is handled by input formatters.

Błędy konwersji typówType conversion errors

Jeśli źródło zostanie znalezione, ale nie można go przekonwertować na typ docelowy, stan modelu jest oflagowany jako nieprawidłowy.If a source is found but can't be converted into the target type, model state is flagged as invalid. Parametr lub właściwość docelowa jest ustawiona na null lub wartość domyślną, jak wskazano w poprzedniej sekcji.The target parameter or property is set to null or a default value, as noted in the previous section.

W kontrolerze interfejsu API, który ma [ApiController] atrybut, nieprawidłowy stan modelu powoduje automatyczne odpowiedź HTTP 400.In an API controller that has the [ApiController] attribute, invalid model state results in an automatic HTTP 400 response.

Na Razor stronie ponownie Wyświetl stronę z komunikatem o błędzie: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");
}

Weryfikacja po stronie klienta umożliwia przechwycenie najbardziej nieprawidłowych danych, które w przeciwnym razie zostałyby przesłane do Razor formularza stron.Client-side validation catches most bad data that would otherwise be submitted to a Razor Pages form. Ta weryfikacja sprawia, że trudno jest wyzwolić poprzedni wyróżniony kod.This validation makes it hard to trigger the preceding highlighted code. Przykładowa aplikacja zawiera przycisk Prześlij z nieprawidłowym dniem , który umieszcza złe dane w polu Data zatrudnienia i przesyła formularz.The sample app includes a Submit with Invalid Date button that puts bad data in the Hire Date field and submits the form. Ten przycisk pokazuje, w jaki sposób kod na potrzeby wyświetlania strony działa po wystąpieniu błędów konwersji danych.This button shows how the code for redisplaying the page works when data conversion errors occur.

Gdy strona jest ponownie wyświetlana przez poprzedni kod, nieprawidłowe dane wejściowe nie są wyświetlane w polu formularza.When the page is redisplayed by the preceding code, the invalid input is not shown in the form field. Wynika to z faktu, że właściwość model ma wartość null lub domyślną.This is because the model property has been set to null or a default value. Nieprawidłowe dane wejściowe są wyświetlane w komunikacie o błędzie.The invalid input does appear in an error message. Jeśli jednak chcesz ponownie wyświetlić złe dane w polu formularza, rozważ, że właściwość model jest ciągiem i ręcznie wykonuje konwersję danych.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.

Ta sama strategia jest zalecana, jeśli nie chcesz, aby Błędy konwersji typów powodowały błędy stanu modelu.The same strategy is recommended if you don't want type conversion errors to result in model state errors. W takim przypadku należy zmienić wartość właściwości model na ciąg.In that case, make the model property a string.

Typy prosteSimple types

Typy proste, które tworzą spinacz modelu mogą konwertować ciągi źródłowe, w następujący sposób:The simple types that the model binder can convert source strings into include the following:

Typy złożoneComplex types

Typ złożony musi mieć publiczny Konstruktor domyślny i publiczne właściwości do zapisu do powiązania.A complex type must have a public default constructor and public writable properties to bind. W przypadku wystąpienia powiązania modelu Klasa jest tworzona przy użyciu publicznego konstruktora domyślnego.When model binding occurs, the class is instantiated using the public default constructor.

Dla każdej właściwości typu złożonego powiązanie modelu wyszukuje źródła nazwy wzorca prefix.property_name.For each property of the complex type, model binding looks through the sources for the name pattern prefix.property_name. Jeśli nic nie zostanie znalezione, szuka tylko property_name bez prefiksu.If nothing is found, it looks for just property_name without the prefix.

W przypadku powiązania z parametrem prefiks jest nazwą parametru.For binding to a parameter, the prefix is the parameter name. W przypadku powiązania z PageModel właściwością publiczną prefiks jest publiczną nazwą właściwości.For binding to a PageModel public property, the prefix is the public property name. Niektóre atrybuty mają Prefix Właściwość, która pozwala zastąpić domyślne użycie parametru lub nazwy właściwości.Some attributes have a Prefix property that lets you override the default usage of parameter or property name.

Na przykład, Załóżmy, że typ złożony jest następującą Instructor klasą: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; }
}

Prefix = Nazwa parametruPrefix = parameter name

Jeśli modelem, który ma zostać powiązany, jest parametr o nazwie instructorToUpdate :If the model to be bound is a parameter named instructorToUpdate:

public IActionResult OnPost(int? id, Instructor instructorToUpdate)

Powiązanie modelu zaczyna się od przejrzenia źródeł klucza instructorToUpdate.ID .Model binding starts by looking through the sources for the key instructorToUpdate.ID. Jeśli ta wartość nie zostanie znaleziona, szuka ID bez prefiksu.If that isn't found, it looks for ID without a prefix.

Prefix = nazwa właściwościPrefix = property name

Jeśli modelem do powiązania jest właściwość o nazwie Instructor kontrolera lub PageModel klasy:If the model to be bound is a property named Instructor of the controller or PageModel class:

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

Powiązanie modelu zaczyna się od przejrzenia źródeł klucza Instructor.ID .Model binding starts by looking through the sources for the key Instructor.ID. Jeśli ta wartość nie zostanie znaleziona, szuka ID bez prefiksu.If that isn't found, it looks for ID without a prefix.

Prefiks niestandardowyCustom prefix

Jeśli model do powiązania jest parametrem o nazwie instructorToUpdate i Bind atrybut określa Instructor jako prefiks: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)

Powiązanie modelu zaczyna się od przejrzenia źródeł klucza Instructor.ID .Model binding starts by looking through the sources for the key Instructor.ID. Jeśli ta wartość nie zostanie znaleziona, szuka ID bez prefiksu.If that isn't found, it looks for ID without a prefix.

Atrybuty dla obiektów docelowych typu złożonegoAttributes for complex type targets

Dostępne są kilka wbudowanych atrybutów do kontrolowania powiązania modelu typów złożonych:Several built-in attributes are available for controlling model binding of complex types:

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

Uwaga

Te atrybuty wpływają na powiązanie modelu, gdy dane formularza ogłoszonego są źródłem wartości.These attributes affect model binding when posted form data is the source of values. Nie wpływają one na wejściowe elementy formatujące, które przetwarzają ogłoszone treści kodu JSON i XML.They do not affect input formatters, which process posted JSON and XML request bodies. Dane wejściowe są wyjaśnione w dalszej części tego artykułu.Input formatters are explained later in this article.

Zobacz również Omówienie [Required] atrybutu w walidacji modelu.See also the discussion of the [Required] attribute in Model validation.

[BindRequired] — atrybut[BindRequired] attribute

Można stosować tylko do właściwości modelu, a nie do parametrów metody.Can only be applied to model properties, not to method parameters. Powoduje, że powiązanie modelu umożliwia dodanie błędu stanu modelu, Jeśli powiązanie nie może wystąpić dla właściwości modelu.Causes model binding to add a model state error if binding cannot occur for a model's property. Oto przykład: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] — atrybut[BindNever] attribute

Można stosować tylko do właściwości modelu, a nie do parametrów metody.Can only be applied to model properties, not to method parameters. Uniemożliwia powiązanie modelu z ustawiania właściwości modelu.Prevents model binding from setting a model's property. Oto przykład:Here's an example:

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

[Bind] — atrybut[Bind] attribute

Można zastosować do klasy lub parametru metody.Can be applied to a class or a method parameter. Określa, które właściwości modelu powinny być dołączone do powiązania modelu.Specifies which properties of a model should be included in model binding.

W poniższym przykładzie tylko określone właściwości Instructor modelu są powiązane, gdy wywoływana jest jakakolwiek procedura obsługi lub metoda działania: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

W poniższym przykładzie tylko określone właściwości Instructor modelu są powiązane, gdy OnPost wywoływana jest metoda: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)

Ten [Bind] atrybut może służyć do ochrony przed nadużyciem w scenariuszach tworzenia scenariuszy.The [Bind] attribute can be used to protect against overposting in create scenarios. Nie działa prawidłowo w scenariuszach edycji, ponieważ wykluczone właściwości mają ustawioną wartość null lub wartość domyślną, a nie jako pozostawione bez zmian.It doesn't work well in edit scenarios because excluded properties are set to null or a default value instead of being left unchanged. W celu zapewnienia obrony przed przekroczeniem, zaleca się, aby zamiast [Bind] atrybutu.For defense against overposting, view models are recommended rather than the [Bind] attribute. Aby uzyskać więcej informacji, zobacz temat Security uwagi dotyczący przefinalizowania.For more information, see Security note about overposting.

KolekcjeCollections

Dla celów, które są kolekcjami typów prostych, powiązanie modelu wyszukuje dopasowania do parameter_name lub property_name.For targets that are collections of simple types, model binding looks for matches to parameter_name or property_name. Jeśli dopasowanie nie zostanie znalezione, szuka jednego z obsługiwanych formatów bez prefiksu.If no match is found, it looks for one of the supported formats without the prefix. Przykład:For example:

  • Załóżmy, że parametr, który ma zostać powiązany, jest tablicą o nazwie selectedCourses :Suppose the parameter to be bound is an array named selectedCourses:

    public IActionResult OnPost(int? id, int[] selectedCourses)
    
  • Dane formularza lub ciągu zapytania mogą znajdować się w jednym z następujących formatów: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
    
  • Następujący format jest obsługiwany tylko w danych formularza:The following format is supported only in form data:

    selectedCourses[]=1050&selectedCourses[]=2000
    
  • We wszystkich powyższych formatach przykładowe powiązanie modelu przekazuje tablicę dwóch elementów do selectedCourses parametru: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

    Formaty danych używające liczb indeksów dolnych (... [0]... [1]...) należy upewnić się, że są numerowane sekwencyjnie, zaczynając od zera.Data formats that use subscript numbers (... [0] ... [1] ...) must ensure that they are numbered sequentially starting at zero. Jeśli występują luki w numerze indeksu dolnego, wszystkie elementy po przerwie zostaną zignorowane.If there are any gaps in subscript numbering, all items after the gap are ignored. Na przykład, jeśli indeksy dolne są równe 0 i 2 zamiast 0 i 1, drugi element jest ignorowany.For example, if the subscripts are 0 and 2 instead of 0 and 1, the second item is ignored.

SłownikiDictionaries

Dla Dictionary elementów docelowych powiązanie modelu wyszukuje dopasowania do parameter_name lub property_name.For Dictionary targets, model binding looks for matches to parameter_name or property_name. Jeśli dopasowanie nie zostanie znalezione, szuka jednego z obsługiwanych formatów bez prefiksu.If no match is found, it looks for one of the supported formats without the prefix. Przykład:For example:

  • Załóżmy, że parametr docelowy jest Dictionary<int, string> nazwany selectedCourses :Suppose the target parameter is a Dictionary<int, string> named selectedCourses:

    public IActionResult OnPost(int? id, Dictionary<int, string> selectedCourses)
    
  • Ogłoszone dane formularza lub ciągu zapytania mogą wyglądać jak w jednym z następujących przykładów: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
    
  • We wszystkich powyższych formatach przykładowe powiązanie modelu przekazuje słownik dwóch elementów do selectedCourses parametru:For all of the preceding example formats, model binding passes a dictionary of two items to the selectedCourses parameter:

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

Zachowanie globalizacji danych tras powiązań modelu i ciągów zapytańGlobalization behavior of model binding route data and query strings

Dostawca wartości ASP.NET Core tras i dostawcy wartości ciągu zapytania:The ASP.NET Core route value provider and query string value provider:

  • Traktuj wartości jako niezmienną kulturę.Treat values as invariant culture.
  • Należy oczekiwać, że adresy URL są kulturą niezmienną.Expect that URLs are culture-invariant.

Natomiast wartości pochodzące z danych formularza są przekształcane z uwzględnieniem kultury.In contrast, values coming from form data undergo a culture-sensitive conversion. Jest to zaprojektowane w taki sposób, aby adresy URL były udostępniane w ustawieniach regionalnych.This is by design so that URLs are shareable across locales.

Aby dostawca wartości ASP.NET Core trasy i dostawca wartości ciągu zapytania były poddawane konwersji zależnej od kultury: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;
    }
}

Specjalne typy danychSpecial data types

Istnieją specjalne typy danych, które może obsłużyć powiązanie modelu.There are some special data types that model binding can handle.

IFormFile i IFormFileCollectionIFormFile and IFormFileCollection

Przekazany plik uwzględniony w żądaniu HTTP.An uploaded file included in the HTTP request. Obsługiwane jest również IEnumerable<IFormFile> dla wielu plików.Also supported is IEnumerable<IFormFile> for multiple files.

CancellationTokenCancellationToken

Służy do anulowania działania w kontrolerach asynchronicznych.Used to cancel activity in asynchronous controllers.

FormularzFormCollection

Służy do pobierania wszystkich wartości z ogłoszonych danych formularza.Used to retrieve all the values from posted form data.

Wejściowe elementy formatująceInput formatters

Dane w treści żądania mogą być w formacie JSON, XML lub innym.Data in the request body can be in JSON, XML, or some other format. Aby przeanalizować te dane, powiązanie modelu korzysta z wejściowego programu formatującego , który jest skonfigurowany do obsługi określonego typu zawartości.To parse this data, model binding uses an input formatter that is configured to handle a particular content type. Domyślnie ASP.NET Core zawiera dane wejściowe w formacie JSON na potrzeby obsługi danych JSON.By default, ASP.NET Core includes JSON based input formatters for handling JSON data. Można dodać inne elementy formatujące dla innych typów zawartości.You can add other formatters for other content types.

ASP.NET Core wybiera wejściowe elementy formatujące na podstawie atrybutu użycia .ASP.NET Core selects input formatters based on the Consumes attribute. Jeśli atrybut nie jest obecny, używa nagłówka Content-Type.If no attribute is present, it uses the Content-Type header.

Aby użyć wbudowanych elementów formatujących dane wejściowe XML:To use the built-in XML input formatters:

  • Zainstaluj Microsoft.AspNetCore.Mvc.Formatters.Xml pakiet NuGet.Install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

  • W Startup.ConfigureServices , wywołaj AddXmlSerializerFormatters lub 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);
    
  • Zastosuj Consumes atrybut do klas kontrolera lub metod akcji, które powinny oczekiwać XML w treści żądania.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)
    

    Aby uzyskać więcej informacji, zobacz wprowadzenie serializacji XML.For more information, see Introducing XML Serialization.

Wyklucz określone typy z powiązania modeluExclude specified types from model binding

Zachowanie modelu powiązań i systemów walidacji jest zależne od ModelMetadata.The model binding and validation systems' behavior is driven by ModelMetadata. Można dostosować ModelMetadata , dodając dostawcę szczegółów do MvcOptions. ModelMetadataDetailsProviders.You can customize ModelMetadata by adding a details provider to MvcOptions.ModelMetadataDetailsProviders. Wbudowane dostawcy szczegółów są dostępne do wyłączenia powiązania modelu lub walidacji dla określonych typów.Built-in details providers are available for disabling model binding or validation for specified types.

Aby wyłączyć powiązanie modelu dla wszystkich modeli określonego typu, Dodaj element ExcludeBindingMetadataProvider w Startup.ConfigureServices .To disable model binding on all models of a specified type, add an ExcludeBindingMetadataProvider in Startup.ConfigureServices. Na przykład aby wyłączyć powiązanie modelu dla wszystkich modeli typu 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);

Aby wyłączyć walidację właściwości określonego typu, Dodaj element SuppressChildValidationMetadataProvider w Startup.ConfigureServices .To disable validation on properties of a specified type, add a SuppressChildValidationMetadataProvider in Startup.ConfigureServices. Na przykład aby wyłączyć walidację właściwości typu 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);

Niestandardowe powiązania modeluCustom model binders

Można rozszerzać powiązania modelu, pisząc niestandardowy spinacz modelu i używając [ModelBinder] atrybutu, aby wybrać go dla danego elementu docelowego.You can extend model binding by writing a custom model binder and using the [ModelBinder] attribute to select it for a given target. Dowiedz się więcej na temat niestandardowego powiązania modelu.Learn more about custom model binding.

Ręczne powiązanie modeluManual model binding

Powiązanie modelu można wywołać ręcznie przy użyciu TryUpdateModelAsync metody.Model binding can be invoked manually by using the TryUpdateModelAsync method. Metoda jest zdefiniowana dla obu ControllerBase klas i PageModel .The method is defined on both ControllerBase and PageModel classes. Przeciążenia metod umożliwiają określenie prefiksu i dostawcy wartości do użycia.Method overloads let you specify the prefix and value provider to use. Metoda zwraca false Jeśli powiązanie modelu nie powiedzie się.The method returns false if model binding fails. Oto przykład: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] — atrybut[FromServices] attribute

Nazwa tego atrybutu jest zgodna ze wzorcem atrybutów powiązania modelu, które określają źródło danych.This attribute's name follows the pattern of model binding attributes that specify a data source. Ale nie informacje o powiązaniu danych od dostawcy wartości.But it's not about binding data from a value provider. Pobiera wystąpienie typu z kontenera iniekcji zależności .It gets an instance of a type from the dependency injection container. Jego celem jest zapewnienie alternatywy dla iniekcji konstruktorów, gdy potrzebna jest usługa tylko wtedy, gdy jest wywoływana konkretna metoda.Its purpose is to provide an alternative to constructor injection for when you need a service only if a particular method is called.

Dodatkowe zasobyAdditional resources