ASP.NET Core Web API에서 컨트롤러 작업 반환 형식Controller action return types in ASP.NET Core Web API

작성자: Scott AddieBy Scott Addie

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

ASP.NET Core에서는 Web API 컨트롤러 작업 반환 형식에 다음 옵션을 제공합니다.ASP.NET Core offers the following options for Web API controller action return types:

이 문서에서는 각 반환 형식을 사용하는 것이 가장 적합한 경우를 설명합니다.This document explains when it's most appropriate to use each return type.

특정 형식Specific type

가장 간단한 작업은 기본 또는 복합 데이터 형식을 반환합니다(예: string 또는 사용자 지정 개체 형식).The simplest action returns a primitive or complex data type (for example, string or a custom object type). 다음 작업을 사용하여 사용자 지정 Product 개체의 컬렉션을 반환합니다.Consider the following action, which returns a collection of custom Product objects:

[HttpGet]
public IEnumerable<Product> Get()
{
    return _repository.GetProducts();
}

작업 실행 중에 보호할 알려진 조건 없이 특정 형식을 반환하는 것으로 충분합니다.Without known conditions to safeguard against during action execution, returning a specific type could suffice. 매개 변수 제약 조건 유효성 검사가 필요하지 않으므로 위의 작업은 매개 변수를 허용하지 않습니다.The preceding action accepts no parameters, so parameter constraints validation isn't needed.

알려진 조건이 작업에서 고려되지 않으면 여러 반환 경로가 도입됩니다’.When known conditions need to be accounted for in an action, multiple return paths are introduced. 이 경우에 기본 또는 복합적인 반환 형식의 ActionResult 반환 형식을 혼합하는 것이 일반적입니다.In such a case, it's common to mix an ActionResult return type with the primitive or complex return type. 이 종류의 동작을 수용하기 위해 IActionResult 또는 ActionResult<T> 중 하나가 필요합니다.Either IActionResult or ActionResult<T> are necessary to accommodate this type of action.

IActionResult 형식IActionResult type

여러 ActionResult 반환 형식을 동작에서 사용할 수 있는 경우 IActionResult 반환 형식이 적절합니다.The IActionResult return type is appropriate when multiple ActionResult return types are possible in an action. ActionResult 형식은 다양한 HTTP 상태 코드를 나타냅니다.The ActionResult types represent various HTTP status codes. 이 범주에 속하는 몇 가지 일반적인 반환 형식은 BadRequestResult(400), NotFoundResult(404) 및 OkObjectResult(200)입니다.Some common return types falling into this category are BadRequestResult (400), NotFoundResult (404), and OkObjectResult (200).

작업에서 자유롭게 여러 반환 형식 및 경로가 있기 때문에 [ProducesResponseType] 특성이 필요합니다.Because there are multiple return types and paths in the action, liberal use of the [ProducesResponseType] attribute is necessary. 이 특성은 Swagger와 같은 도구에서 생성한 API 도움말 페이지에 대해 설명이 포함된 응답 세부 정보를 생성합니다.This attribute produces more descriptive response details for API help pages generated by tools like Swagger. [ProducesResponseType]은 작업에서 반환한 알려진 형식 및 HTTP 상태 코드을 나타냅니다.[ProducesResponseType] indicates the known types and HTTP status codes to be returned by the action.

동기화 작업Synchronous action

두 가지 가능한 반환 형식이 포함된 다음과 같은 동기 작업을 사용합니다.Consider the following synchronous action in which there are two possible return types:

[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public IActionResult GetById(int id)
{
    if (!_repository.TryGetProduct(id, out var product))
    {
        return NotFound();
    }

    return Ok(product);
}

위의 작업에서 id에서 표시하는 제품이 기본 데이터 저장소에 없는 경우 404 상태 코드가 반환됩니다.In the preceding action, a 404 status code is returned when the product represented by id doesn't exist in the underlying data store. NotFound 도우미 메서드는 return new NotFoundResult();에 대한 바로 가기로 호출됩니다.The NotFound helper method is invoked as a shortcut to return new NotFoundResult();. 제품이 있으면 페이로드를 나타내는 Product 개체가 200 상태 코드와 함께 반환됩니다.If the product does exist, a Product object representing the payload is returned with a 200 status code. 확인 도우미 메서드가 return new OkObjectResult(product);의 축약형으로 호출됩니다.The Ok helper method is invoked as the shorthand form of return new OkObjectResult(product);.

비동기 작업Asynchronous action

두 가지 가능한 반환 형식이 포함된 다음과 같은 비동기 작업을 사용합니다.Consider the following asynchronous action in which there are two possible return types:

[HttpPost]
[ProducesResponseType(typeof(Product), StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateAsync([FromBody] Product product)
{
    if (product.Description.Contains("XYZ Widget"))
    {
        return BadRequest();
    }

    await _repository.AddProductAsync(product);

    return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);
}

위의 코드에서In the preceding code:

  • 제품 설명에 “XYZ 위젯”이 포함된 경우 ASP.NET Core 런타임에서 400 상태 코드(BadRequest)가 반환됩니다.A 400 status code (BadRequest) is returned by the ASP.NET Core runtime when the product description contains "XYZ Widget".
  • 제품이 만들어지면 CreatedAtAction 메서드에서 201 상태 코드가 생성됩니다.A 201 status code is generated by the CreatedAtAction method when a product is created. 이 코드 경로에 Product 개체가 반환됩니다.In this code path, the Product object is returned.

예를 들어 다음 모델은 요청이 NameDescription 속성을 포함해야 함을 나타냅니다.For example, the following model indicates that requests must include the Name and Description properties. 따라서 요청에서 NameDescription을 제공하지 못하면 모델 유효성 검사에 실패합니다.Therefore, failure to provide Name and Description in the request causes model validation to fail.

public class Product
{
    public int Id { get; set; }

    [Required]
    public string Name { get; set; }

    [Required]
    public string Description { get; set; }
}

ASP.NET Core 2.1 이상의 [ApiController] 특성이 적용되면 모델 유효성 검사 오류로 인해 400 상태 코드가 생성됩니다.If the [ApiController] attribute in ASP.NET Core 2.1 or later is applied, model validation errors result in a 400 status code. 자세한 정보는 자동 HTTP 400 응답을 참조하세요.For more information, see Automatic HTTP 400 responses.

ActionResult<T> 형식ActionResult<T> type

ASP.NET Core 2.1은 Web API 컨트롤러 작업에 대해 ActionResult<T> 반환 형식을 소개합니다.ASP.NET Core 2.1 introduces the ActionResult<T> return type for Web API controller actions. ActionResult에서 파생된 형식을 반환하거나 특정 형식을 반환할 수 있습니다.It enables you to return a type deriving from ActionResult or return a specific type. ActionResult<T>IActionResult 형식을 통해 다음과 같은 혜택을 제공합니다.ActionResult<T> offers the following benefits over the IActionResult type:

  • [ProducesResponseType] 특성의 Type 속성을 제외할 수 있습니다.The [ProducesResponseType] attribute's Type property can be excluded. 예를 들어 [ProducesResponseType(200, Type = typeof(Product))][ProducesResponseType(200)]으로 단순화됩니다.For example, [ProducesResponseType(200, Type = typeof(Product))] is simplified to [ProducesResponseType(200)]. 작업의 예상 반환 형식은 대신 ActionResult<T>T에서 유추됩니다.The action's expected return type is instead inferred from the T in ActionResult<T>.
  • 암시적 캐스트 연산자TActionResult 모두를 ActionResult<T>로 변환하도록 지원합니다.Implicit cast operators support the conversion of both T and ActionResult to ActionResult<T>. TObjectResult로 변환합니다. 즉, return new ObjectResult(T);return T;로 간소화됩니다.T converts to ObjectResult, which means return new ObjectResult(T); is simplified to return T;.

C#은 인터페이스에서 암시적 캐스트 연산자를 지원하지 않습니다.C# doesn't support implicit cast operators on interfaces. 따라서 인터페이스를 구체적인 형식으로 전환하려면 ActionResult<T>를 사용해야 합니다.Consequently, conversion of the interface to a concrete type is necessary to use ActionResult<T>. 예를 들어 다음 예제에서 IEnumerable을 사용하면 작동하지 않습니다.For example, use of IEnumerable in the following example doesn't work:

[HttpGet]
public ActionResult<IEnumerable<Product>> Get()
{
    return _repository.GetProducts();
}

이전 코드를 수정하는 한 가지 옵션으로 _repository.GetProducts().ToList();를 반환해 볼 수 있습니다.One option to fix the preceding code is to return _repository.GetProducts().ToList();.

대부분의 작업에는 특정 반환 형식이 있습니다.Most actions have a specific return type. 작업을 실행하는 동안 예기치 않은 조건이 발생할 수 있습니다. 이 경우에 특정 형식이 반환되지 않습니다.Unexpected conditions can occur during action execution, in which case the specific type isn't returned. 예를 들어 작업의 입력 매개 변수는 모델 유효성 검사에 실패할 수 있습니다.For example, an action's input parameter may fail model validation. 이러한 경우에 일반적으로 특정 형식이 아닌 적절한 ActionResult 형식을 반환합니다.In such a case, it's common to return the appropriate ActionResult type instead of the specific type.

동기화 작업Synchronous action

두 가지 가능한 반환 형식이 포함된 동기 작업을 사용합니다.Consider a synchronous action in which there are two possible return types:

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ActionResult<Product> GetById(int id)
{
    if (!_repository.TryGetProduct(id, out var product))
    {
        return NotFound();
    }

    return product;
}

위의 코드에서 404 상태 코드는 제품이 데이터베이스에 존재하지 않는 경우에 반환됩니다.In the preceding code, a 404 status code is returned when the product doesn't exist in the database. 제품이 없는 경우 해당하는 Product 개체가 반환됩니다.If the product does exist, the corresponding Product object is returned. ASP.NET Core 2.1 이전에 return product; 줄은 return Ok(product);이었습니다.Before ASP.NET Core 2.1, the return product; line would have been return Ok(product);.

ASP.NET Core 2.1을 기준으로 작업 매개 변수 바인딩 원본 유추는 컨트롤러 클래스를 [ApiController] 특성으로 데코레이팅할 때 사용합니다.As of ASP.NET Core 2.1, action parameter binding source inference is enabled when a controller class is decorated with the [ApiController] attribute. 경로 템플릿의 이름과 일치하는 매개 변수 이름은 요청 경로 데이터를 사용하여 자동으로 바인딩됩니다.A parameter name matching a name in the route template is automatically bound using the request route data. 따라서 위 작업의 id 매개 변수가 [FromRoute] 특성을 사용하여 명시적으로 주석으로 추가되지 않습니다.Consequently, the preceding action's id parameter isn't explicitly annotated with the [FromRoute] attribute.

비동기 작업Asynchronous action

두 가지 가능한 반환 형식이 포함된 비동기 작업을 사용합니다.Consider an asynchronous action in which there are two possible return types:

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<ActionResult<Product>> CreateAsync(Product product)
{
    if (product.Description.Contains("XYZ Widget"))
    {
        return BadRequest();
    }

    await _repository.AddProductAsync(product);

    return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);
}

위의 코드에서In the preceding code:

  • 다음과 같은 경우 ASP.NET Core 런타임에서 400 상태 코드(BadRequest)가 반환됩니다.A 400 status code (BadRequest) is returned by the ASP.NET Core runtime when:
    • [ApiController] 특성이 적용되었고 모델 유효성 검사에 실패합니다.The [ApiController] attribute has been applied and model validation fails.
    • 제품 설명에 “XYZ 위젯”이 포함됩니다.The product description contains "XYZ Widget".
  • 제품이 만들어지면 CreatedAtAction 메서드에서 201 상태 코드가 생성됩니다.A 201 status code is generated by the CreatedAtAction method when a product is created. 이 코드 경로에 Product 개체가 반환됩니다.In this code path, the Product object is returned.

ASP.NET Core 2.1을 기준으로 작업 매개 변수 바인딩 원본 유추는 컨트롤러 클래스를 [ApiController] 특성으로 데코레이팅할 때 사용합니다.As of ASP.NET Core 2.1, action parameter binding source inference is enabled when a controller class is decorated with the [ApiController] attribute. 복합 형식 매개 변수는 요청 본문을 사용하여 자동으로 바인딩됩니다.Complex type parameters are automatically bound using the request body. 따라서 위 작업의 product 매개 변수가 [FromBody] 특성을 사용하여 명시적으로 주석으로 추가되지 않습니다.Consequently, the preceding action's product parameter isn't explicitly annotated with the [FromBody] attribute.

추가 자료Additional resources