ASP.NET Core의 모델 바인딩Model Binding in ASP.NET Core

이 문서는 모델 바인딩이 무엇인지, 작동 방법 및 해당 동작을 사용자 지정하는 방법을 설명합니다.This article explains what model binding is, how it works, and how to customize its behavior.

예제 코드 살펴보기 및 다운로드 (다운로드 방법)View or download sample code (how to download).

모델 바인딩이란What is Model binding

컨트롤러 및 Razor 페이지는 HTTP 요청에서 제공되는 데이터를 사용하여 작동합니다.Controllers and Razor pages work with data that comes from HTTP requests. 예를 들어 경로 데이터는 레코드 키를 제공할 수 있으며, 게시된 양식 필드는 모델의 속성에 대한 값을 제공할 수 있습니다.For example, route data may provide a record key, and posted form fields may provide values for the properties of the model. 이러한 각 값을 검색하고 문자열에서 .NET 형식으로 변환하도록 코드를 작성하는 것은 번거롭고 오류가 발생하기 쉽습니다.Writing code to retrieve each of these values and convert them from strings to .NET types would be tedious and error-prone. 모델 바인딩은 이 프로세스를 자동화합니다.Model binding automates this process. 모델 바인딩 시스템:The model binding system:

  • 경로 데이터, 양식 필드 및 쿼리 문자열과 같은 다양한 원본의 데이터를 검색합니다.Retrieves data from various sources such as route data, form fields, and query strings.
  • 메서드 매개 변수 및 공용 속성에서 컨트롤러 및 Razor 페이지에 데이터를 제공합니다.Provides the data to controllers and Razor pages in method parameters and public properties.
  • 문자열 데이터를 .NET 형식으로 변환합니다.Converts string data to .NET types.
  • 복합 형식의 속성을 업데이트합니다.Updates properties of complex types.

Example

다음 작업 메서드를 사용합니다.Suppose you have the following action method:

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

앱은 이 URL로 요청을 수신합니다.And the app receives a request with this URL:

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

모델 바인딩은 라우팅 시스템이 작업 메서드를 선택한 후 다음 단계를 통해 진행됩니다.Model binding goes though the following steps after the routing system selects the action method:

  • GetByID의 첫 번째 매개 변수, id라는 정수를 찾습니다.Finds the first parameter of GetByID, an integer named id.
  • HTTP 요청에서 사용 가능한 원본을 찾고 경로 데이터에서 id = "2"를 찾습니다.Looks through the available sources in the HTTP request and finds id = "2" in route data.
  • 문자열 "2"를 정수 2로 변환합니다.Converts the string "2" into integer 2.
  • GetByID의 다음 매개 변수, dogsOnly라는 부울을 찾습니다.Finds the next parameter of GetByID, a boolean named dogsOnly.
  • 원본을 찾고 쿼리 문자열에서 "DogsOnly=true"를 찾습니다.Looks through the sources and finds "DogsOnly=true" in the query string. 이름 일치는 대/소문자를 구분하지 않습니다.Name matching is not case-sensitive.
  • 문자열 "true"를 부울 true로 변환합니다.Converts the string "true" into boolean true.

그런 다음, 프레임워크는 id 매개 변수에 대해 2를 dogsOnly 매개 변수에 대해 true를 전달하는 GetById 메서드를 호출합니다.The framework then calls the GetById method, passing in 2 for the id parameter, and true for the dogsOnly parameter.

앞의 예제에서 모델 바인딩 대상은 단순 형식인 메서드 매개 변수입니다.In the preceding example, the model binding targets are method parameters that are simple types. 대상은 복합 형식의 속성일 수도 있습니다.Targets may also be the properties of a complex type. 각 속성이 성공적으로 바인딩된 후 모델 유효성 검사가 해당 속성에 대해 발생합니다.After each property is successfully bound, model validation occurs for that property. 모델에 바인딩되는 데이터의 레코드 및 모든 바인딩 또는 유효성 검사 오류는 ControllerBase.ModelState 또는 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. 이 프로세스가 성공되었는지 확인하기 위해 앱은 ModelState.IsValid 플래그를 확인합니다.To find out if this process was successful, the app checks the ModelState.IsValid flag.

대상Targets

모델 바인딩은 다음 종류의 대상에 대한 값을 찾으려고 합니다.Model binding tries to find values for the following kinds of targets:

  • 요청이 라우팅되는 컨트롤러 작업 메서드의 매개 변수Parameters of the controller action method that a request is routed to.
  • 요청이 라우팅되는 Razor Pages 처리기 메서드의 매개 변수Parameters of the Razor Pages handler method that a request is routed to.
  • 특성으로 지정되는 경우 컨트롤러 또는 PageModel 클래스의 공용 속성Public properties of a controller or PageModel class, if specified by attributes.

[BindProperty] 특성[BindProperty] attribute

모델 바인딩이 해당 속성을 대상으로 하도록 컨트롤러의 공용 속성 또는 PageModel 클래스에 적용할 수 있습니다.Can be applied to a public property of a controller or PageModel class to cause model binding to target that property:

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

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

[BindProperties] 특성[BindProperties] attribute

ASP.NET Core 2.1 이상에서 사용할 수 있습니다.Available in ASP.NET Core 2.1 and later. 모델 바인딩이 클래스의 모든 공용 속성을 대상으로 하도록 컨트롤러 또는 PageModel 클래스에 적용할 수 있습니다.Can be applied to a controller or PageModel class to tell model binding to target all public properties of the class:

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

    public Instructor Instructor { get; set; }

HTTP GET 요청에 대한 모델 바인딩Model binding for HTTP GET requests

기본적으로 속성은 HTTP GET 요청에 대해 바인딩되지 않습니다.By default, properties are not bound for HTTP GET requests. 일반적으로 GET 요청에 대해 필요한 것은 레코드 ID 매개 변수입니다.Typically, all you need for a GET request is a record ID parameter. 레코드 ID는 데이터베이스에 있는 항목을 찾는 데 사용됩니다.The record ID is used to look up the item in the database. 따라서 모델의 인스턴스를 포함하는 속성을 바인딩할 필요가 없습니다.Therefore, there is no need to bind a property that holds an instance of the model. 속성을 GET 요청의 데이터에 바인딩하려는 시나리오에서 SupportsGet 속성을 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; }

원본Sources

기본적으로 모델 바인딩은 HTTP 요청의 다음 원본에서 키-값 쌍의 양식으로 데이터를 가져옵니다.By default, model binding gets data in the form of key-value pairs from the following sources in an HTTP request:

  1. 양식 필드Form fields
  2. 요청 본문([ApiController] 특성이 있는 컨트롤러의 경우)The request body (For controllers that have the [ApiController] attribute.)
  3. 경로 데이터Route data
  4. 쿼리 문자열 매개 변수Query string parameters
  5. 업로드된 파일Uploaded files

각 대상 매개 변수 또는 속성의 경우 원본은 이 목록에 표시된 순서대로 검사됩니다.For each target parameter or property, the sources are scanned in the order indicated in this list. 몇 가지 예외도 있습니다.There are a few exceptions:

  • 경로 데이터 및 쿼리 문자열 값은 단순 형식에 대해서만 사용됩니다.Route data and query string values are used only for simple types.
  • 업로드된 파일은 IFormFile 또는 IEnumerable<IFormFile>을 구현하는 대상 유형에만 바인딩됩니다.Uploaded files are bound only to target types that implement IFormFile or IEnumerable<IFormFile>.

기본 동작이 올바른 결과를 제공하지 않는 경우 다음 특성 중 하나를 사용하여 지정된 대상을 사용하도록 원본을 지정할 수 있습니다.If the default behavior doesn't give the right results, you can use one of the following attributes to specify the source to use for any given target.

이러한 특성:These attributes:

  • 다음 예제와 같이 모델 속성(모델 클래스가 아닌)에 개별적으로 추가됩니다.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; }
    
  • 필요에 따라 생성자에서 모델 이름 값을 허용합니다.Optionally accept a model name value in the constructor. 이 옵션은 속성 이름이 요청의 값과 일치하지 않는 경우에 제공됩니다.This option is provided in case the property name doesn't match the value in the request. 예를 들어 요청의 값은 다음 예제와 같이 해당 이름에 하이픈이 있는 헤더일 수 있습니다.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] 특성[FromBody] attribute

요청 본문 데이터는 요청의 콘텐츠 형식과 관련된 입력 포맷터를 사용하여 구문 분석됩니다.The request body data is parsed by using input formatters specific to the content type of the request. 입력 포맷터는 이 문서의 뒷부분에 설명되어 있습니다.Input formatters are explained later in this article.

작업 메서드당 둘 이상의 매개 변수에 [FromBody]를 적용하지 마십시오.Don't apply [FromBody] to more than one parameter per action method. ASP.NET Core 런타임은 요청 스트림을 읽는 책임을 입력 포맷터에 위임합니다.The ASP.NET Core runtime delegates the responsibility of reading the request stream to the input formatter. 요청 스트림을 읽으면 더 이상 다른 [FromBody] 매개 변수를 바인딩하기 위해 다시 읽을 수 없습니다.Once the request stream is read, it's no longer available to be read again for binding other [FromBody] parameters.

추가 원본Additional sources

원본 데이터는 값 공급 기업에 의해 모델 바인딩 시스템에 제공됩니다.Source data is provided to the model binding system by value providers. 다른 원본에서 모델 바인딩에 대한 데이터를 가져오는 사용자 지정 값 공급 기업을 작성 및 등록할 수 있습니다.You can write and register custom value providers that get data for model binding from other sources. 예를 들어 쿠키 또는 세션 상태의 데이터를 원할 수 있습니다.For example, you might want data from cookies or session state. 새 원본에서 데이터를 가져오려면 다음을 수행합니다.To get data from a new source:

  • IValueProvider를 구현하는 클래스를 만듭니다.Create a class that implements IValueProvider.
  • IValueProviderFactory를 구현하는 클래스를 만듭니다.Create a class that implements IValueProviderFactory.
  • Startup.ConfigureServices에서 팩터리 클래스를 등록합니다.Register the factory class in Startup.ConfigureServices.

샘플 앱은 쿠키에서 값을 가져오는 값 공급 기업팩터리 예제를 포함합니다.The sample app includes a value provider and factory example that gets values from cookies. 다음은 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);

표시된 코드는 사용자 지정 값 공급 기업을 모든 기본 제공 값 공급 기업 다음에 배치합니다.The code shown puts the custom value provider after all the built-in value providers. 목록에서 첫 번째로 지정하려면 Add 대신에 Insert(0, new CookieValueProviderFactory())를 호출합니다.To make it the first in the list, call Insert(0, new CookieValueProviderFactory()) instead of Add.

모델 속성에 대한 원본 없음No source for a model property

기본적으로 모델 속성에 대한 값이 없으면 모델 상태 오류가 생성되지 않습니다.By default, a model state error isn't created if no value is found for a model property. 속성은 Null 또는 기본값으로 설정됩니다.The property is set to null or a default value:

  • Nullable 단순 형식은 null로 설정됩니다.Nullable simple types are set to null.
  • Null을 허용하지 않는 값 형식은 default(T)로 설정됩니다.Non-nullable value types are set to default(T). 예를 들어 매개 변수 int id는 0으로 설정됩니다.For example, a parameter int id is set to 0.
  • 복합 형식의 경우 모델 바인딩은 속성을 설정하지 않고 기본 생성자를 사용하여 인스턴스를 만듭니다.For complex Types, model binding creates an instance by using the default constructor, without setting properties.
  • 배열은 byte[] 배열이 null로 설정되는 점을 제외하고 Array.Empty<T>()로 설정됩니다.Arrays are set to Array.Empty<T>(), except that byte[] arrays are set to null.

모델 속성에 대한 양식 필드에 아무것도 없을 때 모델 상태가 무효화되어야 하는 경우 [BindRequired] 특성을 사용합니다.If model state should be invalidated when nothing is found in form fields for a model property, use the [BindRequired] attribute.

[BindRequired] 동작은 요청 본문의 JSON 또는 XML 데이터가 아니라 게시된 양식 데이터의 모델 바인딩에 적용됩니다.Note that this [BindRequired] behavior applies to model binding from posted form data, not to JSON or XML data in a request body. 요청 본문 데이터는 입력 포맷터에서 처리됩니다.Request body data is handled by input formatters.

형식 변환 오류Type conversion errors

원본이 있지만 대상 형식으로 변환될 수 없는 경우 모델 상태는 잘못된 것으로 플래그가 지정됩니다.If a source is found but can't be converted into the target type, model state is flagged as invalid. 이전 섹션에서 설명한 것처럼 대상 매개 변수 또는 속성은 Null 또는 기본값으로 설정됩니다.The target parameter or property is set to null or a default value, as noted in the previous section.

[ApiController] 특성이 있는 API 컨트롤러에서 잘못된 모델 상태로 자동 HTTP 400 응답이 발생합니다.In an API controller that has the [ApiController] attribute, invalid model state results in an automatic HTTP 400 response.

Razor 페이지에서 페이지를 오류 메시지와 함께 다시 표시합니다.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");
}

클라이언트 쪽 유효성 검사는 Razor Pages 양식으로 제출될 수 있는 대부분의 잘못된 데이터를 catch합니다.Client-side validation catches most bad data that would otherwise be submitted to a Razor Pages form. 이 유효성 검사는 위의 강조 표시된 코드를 트리거하기 어렵게 만듭니다.This validation makes it hard to trigger the preceding highlighted code. 샘플 앱은 Hire Date 필드에 잘못된 데이터를 배치하고 양식을 제출하는 잘못된 데이터로 제출 단추를 포함합니다.The sample app includes a Submit with Invalid Date button that puts bad data in the Hire Date field and submits the form. 이 단추는 데이터 변환 오류가 발생하는 경우 페이지를 다시 표시하기 위해 코드가 작동하는 방식을 보여 줍니다.This button shows how the code for redisplaying the page works when data conversion errors occur.

위의 코드로 페이지가 다시 표시될 때 잘못된 입력은 양식 필드에 표시되지 않습니다.When the page is redisplayed by the preceding code, the invalid input is not shown in the form field. 이는 모델 속성이 Null 또는 기본값으로 설정되었기 때문입니다.This is because the model property has been set to null or a default value. 잘못된 입력은 오류 메시지에 표시됩니다.The invalid input does appear in an error message. 그러나 양식 필드에 잘못된 데이터를 다시 표시하려는 경우 모델 속성을 문자열로 만들고 데이터 변환을 수동으로 수행하는 것이 좋습니다.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.

형식 변환 오류를 모델 상태 오류로 만들려 하지 않는 경우 동일한 전략을 권장합니다.The same strategy is recommended if you don't want type conversion errors to result in model state errors. 이 경우 모델 속성을 문자열로 만듭니다.In that case, make the model property a string.

단순 형식Simple types

모델 바인더에서 원본 문자열을 변환할 수 있는 단순 형식은 다음을 포함합니다.The simple types that the model binder can convert source strings into include the following:

복합 형식Complex types

복합 형식에 공용 기본 생성자와 바인딩할 공용 쓰기 가능 속성이 있어야 합니다.A complex type must have a public default constructor and public writable properties to bind. 모델 바인딩이 발생하면 클래스는 공용 기본 생성자를 사용하여 인스턴스화됩니다.When model binding occurs, the class is instantiated using the public default constructor.

복합 형식의 각 속성의 경우 모델 바인딩은 이름 패턴prefix.property_name에 대한 원본을 찾습니다.For each property of the complex type, model binding looks through the sources for the name pattern prefix.property_name. 아무것도 없는 경우 접두사 없이 property_name만을 찾습니다.If nothing is found, it looks for just property_name without the prefix.

매개 변수에 대한 바인딩의 경우 접두사는 매개 변수 이름입니다.For binding to a parameter, the prefix is the parameter name. PageModel 공용 속성에 대한 바인딩의 경우 접두사는 공용 속성 이름입니다.For binding to a PageModel public property, the prefix is the public property name. 일부 특성에는 매개 변수의 기본 사용 또는 속성 이름을 재정의할 수 있도록 하는 Prefix 속성이 있습니다.Some attributes have a Prefix property that lets you override the default usage of parameter or property name.

예를 들어 복합 형식이 다음 Instructor 클래스라고 가정합니다.For example, suppose the complex type is the following Instructor class:

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

접두사 = 매개 변수 이름Prefix = parameter name

바인딩될 모델이 instructorToUpdate라는 매개 변수인 경우:If the model to be bound is a parameter named instructorToUpdate:

public IActionResult OnPost(int? id, Instructor instructorToUpdate)

모델 바인딩은 키 instructorToUpdate.ID에 대한 원본을 찾아 시작합니다.Model binding starts by looking through the sources for the key instructorToUpdate.ID. 없는 경우 접두사 없이 ID를 찾습니다.If that isn't found, it looks for ID without a prefix.

접두사 = 속성 이름Prefix = property name

바인딩될 모델이 컨트롤러 또는 PageModel 클래스의 Instructor라는 속성인 경우:If the model to be bound is a property named Instructor of the controller or PageModel class:

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

모델 바인딩은 키 Instructor.ID에 대한 원본을 찾아 시작합니다.Model binding starts by looking through the sources for the key Instructor.ID. 없는 경우 접두사 없이 ID를 찾습니다.If that isn't found, it looks for ID without a prefix.

사용자 지정 접두사Custom prefix

바인딩될 모델이 instructorToUpdate라는 매개 변수이고 Bind 특성이 접두사로 Instructor를 지정하는 경우: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)

모델 바인딩은 키 Instructor.ID에 대한 원본을 찾아 시작합니다.Model binding starts by looking through the sources for the key Instructor.ID. 없는 경우 접두사 없이 ID를 찾습니다.If that isn't found, it looks for ID without a prefix.

복합 형식 대상에 대한 특성Attributes for complex type targets

여러 기본 제공 특성은 복합 형식의 모델 바인딩을 제어할 수 있습니다.Several built-in attributes are available for controlling model binding of complex types:

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

참고

이러한 특성은 게시된 양식 데이터가 값의 원본일 때 모델 바인딩에 영향을 줍니다.These attributes affect model binding when posted form data is the source of values. 게시된 JSON 및 XML 요청 본문을 처리하는 입력 포맷터에는 영향을 주지 않습니다.They do not affect input formatters, which process posted JSON and XML request bodies. 입력 포맷터는 이 문서의 뒷부분에 설명되어 있습니다.Input formatters are explained later in this article.

모델 유효성 검사에서 [Required] 특성의 설명을 참조하세요.See also the discussion of the [Required] attribute in Model validation.

[BindRequired] 특성[BindRequired] attribute

메서드 매개 변수가 아닌 모델 속성에만 적용될 수 있습니다.Can only be applied to model properties, not to method parameters. 모델의 속성에 대한 바인딩이 발생할 수 없는 경우 모델 바인딩이 모델 상태 오류를 추가하도록 합니다.Causes model binding to add a model state error if binding cannot occur for a model's property. 예를 들면 다음과 같습니다.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] 특성[BindNever] attribute

메서드 매개 변수가 아닌 모델 속성에만 적용될 수 있습니다.Can only be applied to model properties, not to method parameters. 모델 바인딩이 모델의 속성을 설정하는 것을 방지합니다.Prevents model binding from setting a model's property. 예를 들면 다음과 같습니다.Here's an example:

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

[Bind] 특성[Bind] attribute

클래스 또는 메서드 매개 변수에 적용될 수 있습니다.Can be applied to a class or a method parameter. 모델 바인딩에 포함되어야 하는 모델의 속성을 지정합니다.Specifies which properties of a model should be included in model binding.

다음 예제에서 모든 처리기 또는 작업 메서드가 호출될 때 지정된 속성의 Instructor 모델만 바인딩됩니다.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

다음 예제에서 OnPost 메서드가 호출될 때 지정된 속성의 Instructor 모델만 바인딩됩니다.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)

[Bind] 특성은 만들기 시나리오에서 초과 게시를 방지하는 데 사용될 수 있습니다.The [Bind] attribute can be used to protect against overposting in create scenarios. 제외된 속성은 변경되지 않은 채로 남겨지는 대신 Null 또는 기본값으로 설정되기 때문에 편집 시나리오에서 잘 작동하지 않습니다.It doesn't work well in edit scenarios because excluded properties are set to null or a default value instead of being left unchanged. 초과 게시에 대한 방어의 경우 뷰 모델이 [Bind] 특성보다 권장됩니다.For defense against overposting, view models are recommended rather than the [Bind] attribute. 자세한 내용은 초과 게시에 대한 보안 정보를 참조하세요.For more information, see Security note about overposting.

컬렉션Collections

단순 형식의 컬렉션인 대상의 경우 모델 바인딩은 parameter_name 또는 property_name에 대한 일치 항목을 찾습니다.For targets that are collections of simple types, model binding looks for matches to parameter_name or property_name. 일치하는 항목이 없는 경우 접두사 없이 지원되는 양식 중 하나를 찾습니다.If no match is found, it looks for one of the supported formats without the prefix. 예:For example:

  • 바인딩되는 매개 변수가 selectedCourses라는 배열이라고 가정합니다.Suppose the parameter to be bound is an array named selectedCourses:

    public IActionResult OnPost(int? id, int[] selectedCourses)
    
  • 양식 또는 쿼리 문자열 데이터는 다음 형식 중 하나일 수 있습니다.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
    
  • 다음 형식은 양식 데이터에서만 지원됩니다.The following format is supported only in form data:

    selectedCourses[]=1050&selectedCourses[]=2000
    
  • 앞의 모든 예제 형식의 경우 모델 바인딩은 두 항목의 배열을 selectedCourses 매개 변수에 전달합니다.For all of the preceding example formats, model binding passes an array of two items to the selectedCourses parameter:

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

    아래 첨자 숫자(... [0] ... [1] ...)를 사용하는 데이터 형식은 0부터 시작하여 순차적으로 번호가 매겨지는지 확인해야 합니다.Data formats that use subscript numbers (... [0] ... [1] ...) must ensure that they are numbered sequentially starting at zero. 아래 첨자 번호에 간격이 있는 경우 간격 뒤에 있는 모든 항목은 무시됩니다.If there are any gaps in subscript numbering, all items after the gap are ignored. 예를 들어 아래 첨자가 0과 1 대신 0과 2인 경우 두 번째 항목은 무시됩니다.For example, if the subscripts are 0 and 2 instead of 0 and 1, the second item is ignored.

사전Dictionaries

Dictionary 대상의 경우 모델 바인딩은 parameter_name 또는 property_name에 대한 일치 항목을 찾습니다.For Dictionary targets, model binding looks for matches to parameter_name or property_name. 일치하는 항목이 없는 경우 접두사 없이 지원되는 양식 중 하나를 찾습니다.If no match is found, it looks for one of the supported formats without the prefix. 예:For example:

  • 대상 매개 변수가 selectedCourses라는 Dictionary<int, string>라고 가정합니다.Suppose the target parameter is a Dictionary<int, string> named selectedCourses:

    public IActionResult OnPost(int? id, Dictionary<int, string> selectedCourses)
    
  • 게시된 양식 또는 쿼리 문자열 데이터는 다음 예제 중 하나와 같을 수 있습니다.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
    
  • 앞의 모든 예제 형식의 경우 모델 바인딩은 두 항목의 사전을 selectedCourses 매개 변수에 전달합니다.For all of the preceding example formats, model binding passes a dictionary of two items to the selectedCourses parameter:

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

특수 데이터 형식Special data types

모델 바인딩이 처리할 수 있는 일부 특수 데이터 형식이 있습니다.There are some special data types that model binding can handle.

IFormFile 및 IFormFileCollectionIFormFile and IFormFileCollection

HTTP 요청에 포함되는 업로드된 파일입니다.An uploaded file included in the HTTP request. 또한 여러 파일에 대해 IEnumerable<IFormFile>이 지원됩니다.Also supported is IEnumerable<IFormFile> for multiple files.

CancellationTokenCancellationToken

비동기 컨트롤러에서 작업을 취소하는 데 사용됩니다.Used to cancel activity in asynchronous controllers.

FormCollectionFormCollection

게시된 양식 데이터에서 모든 값을 검색하는 데 사용됩니다.Used to retrieve all the values from posted form data.

입력 포맷터Input formatters

요청 본문의 데이터는 JSON, XML 또는 일부 다른 형식일 수 있습니다.Data in the request body can be in JSON, XML, or some other format. 이 데이터를 구문 분석하기 위해 모델 바인딩은 특정 콘텐츠 유형을 처리하도록 구성된 입력 포맷터를 사용합니다.To parse this data, model binding uses an input formatter that is configured to handle a particular content type. 기본적으로 ASP.NET Core는 JSON 데이터를 처리하기 위한 JSON 기반 입력 포맷터를 포함합니다.By default, ASP.NET Core includes JSON based input formatters for handling JSON data. 다른 콘텐츠 형식에 대해 다른 포맷터를 추가할 수 있습니다.You can add other formatters for other content types.

ASP.NET Core는 Consumes 특성을 기반으로 입력 포맷터를 선택합니다.ASP.NET Core selects input formatters based on the Consumes attribute. 특성이 없는 경우 Content-Type 헤더를 사용합니다.If no attribute is present, it uses the Content-Type header.

기본 제공 XML 입력 포맷터를 사용하려면 다음을 수행합니다.To use the built-in XML input formatters:

  • Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet 패키지를 설치합니다.Install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

  • Startup.ConfigureServices에서 AddXmlSerializerFormatters 또는 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);
    
  • 요청 본문에서 XML을 필요로 하는 컨트롤러 클래스 또는 작업 메서드에 Consumes 특성을 적용합니다.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)
    

    자세한 내용은 XML Serialization 소개를 참조하세요.For more information, see Introducing XML Serialization.

모델 바인딩에서 지정된 형식 제외Exclude specified types from model binding

모델 바인딩 및 시스템 동작의 유효성 검사는 ModelMetadata를 기반으로 합니다.The model binding and validation systems' behavior is driven by ModelMetadata. MvcOptions.ModelMetadataDetailsProviders에 세부 정보 공급 기업을 추가하여 ModelMetadata를 사용자 지정할 수 있습니다.You can customize ModelMetadata by adding a details provider to MvcOptions.ModelMetadataDetailsProviders. 기본 제공 세부 정보 공급 기업을 지정된 형식에 대한 모델 바인딩 또는 유효성 검사를 비활성화하기 위해 사용할 수 있습니다.Built-in details providers are available for disabling model binding or validation for specified types.

지정된 형식의 모든 모델에 대한 모델 바인딩을 비활성화하려면 Startup.ConfigureServices에서 ExcludeBindingMetadataProvider를 추가합니다.To disable model binding on all models of a specified type, add an ExcludeBindingMetadataProvider in Startup.ConfigureServices. 예를 들어 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);

지정된 형식의 속성에 대한 유효성 검사를 비활성화하려면 Startup.ConfigureServices에서 SuppressChildValidationMetadataProvider를 추가합니다.To disable validation on properties of a specified type, add a SuppressChildValidationMetadataProvider in Startup.ConfigureServices. 예를 들어 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);

사용자 지정 모델 바인더Custom model binders

사용자 지정 모델 바인더를 작성하고 지정된 대상에 대해 선택하도록 [ModelBinder] 특성을 사용하여 모델 바인딩을 확장할 수 있습니다.You can extend model binding by writing a custom model binder and using the [ModelBinder] attribute to select it for a given target. 사용자 모델 바인딩에 대해 자세히 알아보세요.Learn more about custom model binding.

수동 모델 바인딩Manual model binding

TryUpdateModelAsync 메서드를 사용하여 모델 바인딩을 수동으로 호출할 수 있습니다.Model binding can be invoked manually by using the TryUpdateModelAsync method. 메서드는 ControllerBasePageModel 클래스에서 정의됩니다.The method is defined on both ControllerBase and PageModel classes. 메서드 오버로드를 통해 사용할 접두사 및 값 공급 기업을 지정할 수 있습니다.Method overloads let you specify the prefix and value provider to use. 모델 바인딩이 실패하는 경우 메서드는 false를 반환합니다.The method returns false if model binding fails. 예를 들면 다음과 같습니다.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] 특성[FromServices] attribute

이 특성의 이름은 데이터 원본을 지정하는 모델 바인딩 특성의 패턴을 따릅니다.This attribute's name follows the pattern of model binding attributes that specify a data source. 그러나 값 공급 기업의 바인딩 데이터에 대한 것은 아닙니다.But it's not about binding data from a value provider. 종속성 주입 컨테이너에서 형식의 인스턴스를 가져옵니다.It gets an instance of a type from the dependency injection container. 특정 메서드가 호출되는 경우에만 서비스가 필요할 때 생성자 주입에 대안을 제공하는 것이 목적입니다.Its purpose is to provide an alternative to constructor injection for when you need a service only if a particular method is called.

추가 자료Additional resources