ASP.NET Core MVC의 서식 지정 응답 데이터 소개Introduction to formatting response data in ASP.NET Core MVC

으로 Steve SmithBy Steve Smith

ASP.NET Core MVC에서 응답 데이터를 고정된 형식을 사용 하 여 서식을 지정 하기 위한 또는 클라이언트 사양에 대 한 응답에서 기본적으로 지원 합니다.ASP.NET Core MVC has built-in support for formatting response data, using fixed formats or in response to client specifications.

보기 또는 GitHub에서 샘플을 다운로드합니다.View or download sample from GitHub.

형식에 따른 작업 결과Format-Specific Action Results

일부 작업 결과 유형은 특정 형식에 고유한와 같은 JsonResultContentResult합니다.Some action result types are specific to a particular format, such as JsonResult and ContentResult. 작업은 항상 특정 한 방식으로 형식이 지정 된 특정 결과 반환할 수 있습니다.Actions can return specific results that are always formatted in a particular manner. 예를 들어 반환 된 JsonResult 클라이언트 기본 설정에 관계 없이 JSON 형식의 데이터를 반환 합니다.For example, returning a JsonResult will return JSON-formatted data, regardless of client preferences. 마찬가지로, 반환 된 ContentResult (단순히 문자열을 반환 합니다)으로 일반 텍스트 형식 문자열 데이터를 반환 합니다.Likewise, returning a ContentResult will return plain-text-formatted string data (as will simply returning a string).

참고

특정 형식 제한; 반환 하는 작업 필요 하지 않습니다. MVC는 모든 개체 반환 값을 지원합니다.An action isn't required to return any particular type; MVC supports any object return value. 작업에서 반환 하는 경우는 IActionResult 구현과 컨트롤러에서 상속 Controller, 개발자는 선택 사항 중 많은 부분에 해당 하는 많은 도우미 메서드.If an action returns an IActionResult implementation and the controller inherits from Controller, developers have many helper methods corresponding to many of the choices. 개체를 반환 하는 작업의 결과는 없는 IActionResult 적절 한 사용 하 여 형식을 serialize 할 IOutputFormatter 구현 합니다.Results from actions that return objects that are not IActionResult types will be serialized using the appropriate IOutputFormatter implementation.

상속 되는 컨트롤러에서 특정 형식의 데이터를 반환 하는 Controller 기본 클래스, 기본 제공 도우미 메서드를 사용 Json JSON을 반환 하 고 Content 일반 텍스트에 대 한 합니다.To return data in a specific format from a controller that inherits from the Controller base class, use the built-in helper method Json to return JSON and Content for plain text. 동작 메서드에서 특정 결과 형식을 반환 해야 (예를 들어, JsonResult) 또는 IActionResult합니다.Your action method should return either the specific result type (for instance, JsonResult) or IActionResult.

JSON 형식의 데이터를 반환 합니다.Returning JSON-formatted data:

// GET: api/authors
[HttpGet]
public JsonResult Get()
{
    return Json(_authorRepository.List());
}

이 작업에서 샘플 응답:Sample response from this action:

네트워크 탭에서 Microsoft Edge 응답의 콘텐츠 형식을 보여 주는 개발자 도구의 application/json

응답의 콘텐츠 형식을 application/json와 응답 헤더 섹션 모두의 네트워크 요청 목록에 표시 합니다.Note that the content type of the response is application/json, shown both in the list of network requests and in the Response Headers section. 또한 note 요청 헤더 섹션에서 Accept 헤더에서에 (이 경우, Microsoft Edge) 브라우저에서 제공 되는 옵션 목록입니다.Also note the list of options presented by the browser (in this case, Microsoft Edge) in the Accept header in the Request Headers section. 기술을이 헤더를 무시 하 엑세스 그 아래에 설명 되어 있습니다.The current technique is ignoring this header; obeying it is discussed below.

사용 하 여 서식이 지정 된 일반 텍스트 데이터를 반환 하려면 ContentResultContent 도우미:To return plain text formatted data, use ContentResult and the Content helper:

// GET api/authors/about
[HttpGet("About")]
public ContentResult About()
{
    return Content("An API listing authors of docs.asp.net.");
}

이 작업의 응답:A response from this action:

Microsoft Edge 응답의 콘텐츠 형식을 보여 주는 개발자 도구의 네트워크 탭은 텍스트/일반

이 경우는 Content-Type 반환 된 text/plain합니다.Note in this case the Content-Type returned is text/plain. 또한는 문자열 응답 유형을 사용 하 여이 동작을 얻을 수 있습니다.You can also achieve this same behavior using just a string response type:

// GET api/authors/version
[HttpGet("version")]
public string Version()
{
    return "Version 1.0.0";
}

여러 개 포함 된 특정 작업에 대 한 반환 형식 또는 옵션 (예: 수행 되는 작업의 결과에 따라 다른 HTTP 상태 코드), 원하는 IActionResult 반환 형식으로.For non-trivial actions with multiple return types or options (for example, different HTTP status codes based on the result of operations performed), prefer IActionResult as the return type.

콘텐츠 협상Content Negotiation

콘텐츠 협상 (conneg 줄여서) 클라이언트를 지정 하는 경우에 발생 한 Accept 헤더합니다.Content negotiation (conneg for short) occurs when the client specifies an Accept header. ASP.NET Core MVC에서 사용 하는 기본 형식은 JSON입니다.The default format used by ASP.NET Core MVC is JSON. 콘텐츠 협상에 의해 구현 됩니다 ObjectResult합니다.Content negotiation is implemented by ObjectResult. 또한 도우미 메서드에서 반환 된 특정 작업 결과 상태 코드에 기본적으로 (모두를 기반으로 하 ObjectResult).It is also built into the status code specific action results returned from the helper methods (which are all based on ObjectResult). 모델 형식 (데이터 전송 형식으로 정의 된 클래스)을 반환할 수 있습니다 및 프레임 워크는 자동으로 줄 바꿈이는 ObjectResult 드립니다.You can also return a model type (a class you've defined as your data transfer type) and the framework will automatically wrap it in an ObjectResult for you.

다음 작업 메서드에서 사용 하는 OkNotFound 도우미 메서드.The following action method uses the Ok and NotFound helper methods:

// GET: api/authors/search?namelike=th
[HttpGet("Search")]
public IActionResult Search(string namelike)
{
    var result = _authorRepository.GetByNameSubstring(namelike);
    if (!result.Any())
    {
        return NotFound(namelike);
    }
    return Ok(result);
}

다른 형식 요청 하 고 서버에 요청된 된 형식을 반환 수 하지 않으면 JSON 형식의 응답 반환 됩니다.A JSON-formatted response will be returned unless another format was requested and the server can return the requested format. 와 같은 도구를 사용할 수 있습니다 Fiddler 를 Accept 헤더를 포함 하는 요청을 만들고 다른 형식을 지정 합니다.You can use a tool like Fiddler to create a request that includes an Accept header and specify another format. 서버에 있는 경우 해당 경우에는 포맷터 요청 된 형식으로 응답을 생성할 수 있는, 결과에 반환 됩니다 클라이언트 기본 형식입니다.In that case, if the server has a formatter that can produce a response in the requested format, the result will be returned in the client-preferred format.

수동으로 만든를 보여 주는 fiddler 콘솔 GET 요청 Accept 헤더 값이 응용 프로그램/x m l

위의 스크린 샷에서 요청을 생성 하는 Fiddler 작성기 사용 되었습니다 지정 Accept: application/xml합니다.In the above screenshot, the Fiddler Composer has been used to generate a request, specifying Accept: application/xml. 기본적으로 ASP.NET Core MVC만 지원 JSON, 하더라도 반환 결과 여전히 JSON 형식 수 다른 format을 지정 합니다.By default, ASP.NET Core MVC only supports JSON, so even when another format is specified, the result returned is still JSON-formatted. 다음 섹션에 추가 하는 포맷터를 추가 하는 방법을 볼 수 있습니다.You'll see how to add additional formatters in the next section.

컨트롤러 작업을 반환할 수 있습니다 (일반 이전 CLR 개체), POCOs ASP.NET MVC에서 자동으로 만듭니다는 쿼리에서 ObjectResult 을 해당 개체를 래핑합니다.Controller actions can return POCOs (Plain Old CLR Objects), in which case ASP.NET MVC will automatically create an ObjectResult for you that wraps the object. 클라이언트는 서식이 지정 된 직렬화 된 개체를 발생 합니다 (JSON 형식은 기본, XML 또는 기타 형식을 구성할 수 있습니다).The client will get the formatted serialized object (JSON format is the default; you can configure XML or other formats). 가 반환 되는 개체 null, 면 프레임 워크는 반환 된 204 No Content 응답 합니다.If the object being returned is null, then the framework will return a 204 No Content response.

개체 유형을 반환 합니다.Returning an object type:

// GET api/authors/ardalis
[HttpGet("{alias}")]
public Author Get(string alias)
{
    return _authorRepository.GetByAlias(alias);
}

이 샘플에서는 유효한 작성자 별칭에 대 한 요청 작성자의 데이터로 200 정상 응답이 받게 됩니다.In the sample, a request for a valid author alias will receive a 200 OK response with the author's data. 잘못 된 별칭에 대 한 요청 204 콘텐츠 없음 응답을 받게 됩니다.A request for an invalid alias will receive a 204 No Content response. XML 및 JSON 형식의 응답을 보여 주는 스크린샷 다음과 같습니다.Screenshots showing the response in XML and JSON formats are shown below.

콘텐츠 협상 프로세스Content Negotiation Process

콘텐츠 협상 만 수행한 경우는 Accept 요청에 헤더를 표시 합니다.Content negotiation only takes place if an Accept header appears in the request. 요청에 accept 헤더가 포함 되어 있으면, 프레임 워크 기본 설정 순서 대로 accept 헤더의 미디어 유형을 열거 합니다 및 accept 헤더에 의해 지정 된 형식 중 하나에 대 한 응답을 생성할 수 있는 포맷터를 찾으려고 시도 합니다.When a request contains an accept header, the framework will enumerate the media types in the accept header in preference order and will try to find a formatter that can produce a response in one of the formats specified by the accept header. 프레임 워크 응답을 생성할 수 있는 첫 번째 포맷터를 찾으려고 시도할 경우 클라이언트의 요청을 충족 시킬 수 있는 포맷터를 발견 되 면 (개발자가에서 옵션을 구성 하지 않는 한 MvcOptions 406 반환할 승인 금지 대신).In case no formatter is found that can satisfy the client's request, the framework will try to find the first formatter that can produce a response (unless the developer has configured the option on MvcOptions to return 406 Not Acceptable instead). 이 요청에는 XML을 지정 하는 경우 XML 포맷터 구성 되지 않았습니다. JSON 포맷터 사용 됩니다.If the request specifies XML, but the XML formatter has not been configured, then the JSON formatter will be used. 보다 일반적으로 포맷터를 구성 된 경우 요청 된 형식으로 제공할 수 있는 다음 개체의 서식을 지정할 수 있는 보다 첫 번째 포맷터가 사용 합니다.More generally, if no formatter is configured that can provide the requested format, then the first formatter than can format the object is used. 헤더가 없으면이 지정 되 면 반환 될 개체를 처리할 수 있는 첫 번째 포맷터는 응답을 직렬화 하는 데 사용될지 합니다.If no header is given, the first formatter that can handle the object to be returned will be used to serialize the response. 이 경우 모든 협상이 발생 하지 않으므로-서버 결정할 때 알고리즘 형식을 사용 합니다.In this case, there isn't any negotiation taking place - the server is determining what format it will use.

참고

Accept 헤더를 포함 하는 경우 */*, 머리글은 무시 됩니다 RespectBrowserAcceptHeader 로 설정 하면 true이 고 MvcOptions합니다.If the Accept header contains */*, the Header will be ignored unless RespectBrowserAcceptHeader is set to true on MvcOptions.

브라우저 및 콘텐츠 협상Browsers and Content Negotiation

일반적인 API 클라이언트와 달리 웹 브라우저에 제공 하는 하는 경향이 Accept 다양 한 종류의 와일드 카드를 포함 한 형식으로 포함 하는 헤더입니다.Unlike typical API clients, web browsers tend to supply Accept headers that include a wide array of formats, including wildcards. 기본적으로 프레임 워크는 브라우저에서 요청 된을 감지할 때 무시 됩니다는 Accept 헤더 구성과 대신 반환 콘텐츠 응용 프로그램에서의 기본 형식 (JSON 달리 구성 하지 않는 한).By default, when the framework detects that the request is coming from a browser, it will ignore the Accept header and instead return the content in the application's configured default format (JSON unless otherwise configured). 이 Api를 사용 하 여 다양 한 브라우저를 사용 하는 경우는 보다 일관 된 환경을 제공 합니다.This provides a more consistent experience when using different browsers to consume APIs.

응용 프로그램 honor 브라우저 accept 헤더가 사용 하려는 경우 구성할 수 있습니다이 MVC의 구성의 일부분으로 설정 하 여 RespectBrowserAcceptHeadertrueConfigureServices 메서드에서 Startup.cs합니다.If you would prefer your application honor browser accept headers, you can configure this as part of MVC's configuration by setting RespectBrowserAcceptHeader to true in the ConfigureServices method in Startup.cs.

services.AddMvc(options =>
{
    options.RespectBrowserAcceptHeader = true; // false by default
}

포맷터를 구성합니다.Configuring Formatters

JSON의 기본값을 초과 하는 추가 형식을 지원 하기 위해 응용 프로그램에 필요한 경우 NuGet 패키지 추가 구성 하는 MVC를 지원 합니다.If your application needs to support additional formats beyond the default of JSON, you can add NuGet packages and configure MVC to support them. 입력 및 출력에 대 한 별도 포맷터 가지가 있습니다.There are separate formatters for input and output. 입력된 포맷터에서 사용 모델 바인딩; 출력 포맷터는 응답 형식을 지정 하는 데 사용 됩니다.Input formatters are used by Model Binding; output formatters are used to format responses. 구성할 수 있습니다 사용자 지정 포맷터합니다.You can also configure Custom Formatters.

XML 형식 지원 추가Adding XML Format Support

XML 서식 지정에 대 한 지원을 추가할 설치는 Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet 패키지 합니다.To add support for XML formatting, install the Microsoft.AspNetCore.Mvc.Formatters.Xml NuGet package.

MVC의 구성에는 XmlSerializerFormatters 추가 Startup.cs:Add the XmlSerializerFormatters to MVC's configuration in Startup.cs:

services.AddMvc()
    .AddXmlSerializerFormatters();

또는 출력 포맷터만 추가할 수 있습니다.Alternately, you can add just the output formatter:

services.AddMvc(options =>
{
    options.OutputFormatters.Add(new XmlSerializerOutputFormatter());
});

이러한 두 방법을 사용 하 여 결과 serialize System.Xml.Serialization.XmlSerializer합니다.These two approaches will serialize results using System.Xml.Serialization.XmlSerializer. 원하는 경우 사용할 수 있습니다는 System.Runtime.Serialization.DataContractSerializer 해당 연결 된 포맷터를 추가 하 여:If you prefer, you can use the System.Runtime.Serialization.DataContractSerializer by adding its associated formatter:

services.AddMvc(options =>
{
    options.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter());
});

컨트롤러 메서드는 요청에 따라 적절 한 형식을 반환 해야 XML 서식 지정에 대 한 지원을 추가 하면 Accept 헤더 예제에서는이 Fiddler로:Once you've added support for XML formatting, your controller methods should return the appropriate format based on the request's Accept header, as this Fiddler example demonstrates:

Fiddler 콘솔: 요청에 대 한 원시 The 탭 Accept 헤더 값은 application/xml에 표시 합니다.

원시 GET 요청이 사용 하 고 검사기 탭에서 볼 수는 Accept: application/xml 헤더 집합입니다.You can see in the Inspectors tab that the Raw GET request was made with an Accept: application/xml header set. 창에 표시 된 응답의 Content-Type: application/xml 헤더로, 및 Author XML로 serialize 된 개체입니다.The response pane shows the Content-Type: application/xml header, and the Author object has been serialized to XML.

지정 하는 요청을 수정 하려면 Composer 탭을 사용 하 여 application/json 에서 Accept 헤더입니다.Use the Composer tab to modify the request to specify application/json in the Accept header. 요청을 실행 하 고 응답 JSON으로 형식이 지정 됩니다.Execute the request, and the response will be formatted as JSON:

Fiddler 콘솔: Accept 헤더 값은 application/json 요청에 대 한 원시의 탭에 표시 합니다.

이 스크린 샷에 볼 수 있습니다의 헤더를 설정 하는 요청 Accept: application/json 응답와 동일 하 게 지정 하 고 해당 Content-Type합니다.In this screenshot, you can see the request sets a header of Accept: application/json and the response specifies the same as its Content-Type. Author 개체의 JSON 형식의 응답 본문에 표시 됩니다.The Author object is shown in the body of the response, in JSON format.

특정 형식 적용Forcing a Particular Format

특정 작업에 대 한 응답 형식을 제한 하려는 경우 할 수 있습니다, 적용할 수는 [Produces] 필터입니다.If you would like to restrict the response formats for a specific action you can, you can apply the [Produces] filter. [Produces] 필터는 특정 작업 (또는 컨트롤러)에 대 한 응답 형식을 지정 합니다.The [Produces] filter specifies the response formats for a specific action (or controller). 마찬가지로 대부분 필터, 작업, 컨트롤러 또는 전역 범위에 적용할 수 있습니다.Like most Filters, this can be applied at the action, controller, or global scope.

[Produces("application/json")]
public class AuthorsController

[Produces] 필터 내에서 모든 작업을 강제로 AuthorsController 다른 포맷터는 응용 프로그램 및 제공 된 클라이언트에 대해 구성 된 경우에 JSON 형식의 응답을 반환 하는 Accept 헤더를 요청 하는 다른 사용 가능한 형식입니다.The [Produces] filter will force all actions within the AuthorsController to return JSON-formatted responses, even if other formatters were configured for the application and the client provided an Accept header requesting a different, available format. 참조 필터 필터를 전역으로 적용 하는 방법을 비롯 하 여 자세한 내용을 보려면 합니다.See Filters to learn more, including how to apply filters globally.

특수 한 사례 포맷터Special Case Formatters

일부 특수 한 경우 기본 제공 포맷터를 사용 하 여 구현 됩니다.Some special cases are implemented using built-in formatters. 기본적으로 string 반환 형식으로 형식이 지정 됩니다 텍스트/일반 (텍스트/html 통해 요청 된 경우 Accept 헤더).By default, string return types will be formatted as text/plain (text/html if requested via Accept header). 이 문제를 제거 하 여 제거할 수는 TextOutputFormatter합니다.This behavior can be removed by removing the TextOutputFormatter. 포맷터에서 제거는 Configure 에서 메서드 Startup.cs (아래 참조).You remove formatters in the Configure method in Startup.cs (shown below). 모델 개체에 영향을 주는 작업 반환 형식을 반환 합니다는 204 콘텐츠 없음 응답 반환 하는 경우 null합니다.Actions that have a model object return type will return a 204 No Content response when returning null. 이 문제를 제거 하 여 제거할 수는 HttpNoContentOutputFormatter합니다.This behavior can be removed by removing the HttpNoContentOutputFormatter. 다음 코드를 제거는 TextOutputFormatterHttpNoContentOutputFormatter합니다.The following code removes the TextOutputFormatter and HttpNoContentOutputFormatter.

services.AddMvc(options =>
{
    options.OutputFormatters.RemoveType<TextOutputFormatter>();
    options.OutputFormatters.RemoveType<HttpNoContentOutputFormatter>();
});

없이 TextOutputFormatter, string 406를 반환 하는 형식 반환 합니다. 예를 들어 승인 금지 합니다.Without the TextOutputFormatter, string return types return 406 Not Acceptable, for example. XML 포맷터 있으면 것은 서식을 참고 string 경우 반환 형식에서 TextOutputFormatter 제거 됩니다.Note that if an XML formatter exists, it will format string return types if the TextOutputFormatter is removed.

없이 HttpNoContentOutputFormatter, null 개체는 구성 된 포맷터를 사용 하 여 서식이 지정 합니다.Without the HttpNoContentOutputFormatter, null objects are formatted using the configured formatter. 예를 들어 JSON 포맷터는 반환 된 응답의 본문으로 nullXML 포맷터는 특성으로 빈 XML 요소를 반환 하는 반면, xsi:nil="true" 설정 합니다.For example, the JSON formatter will simply return a response with a body of null, while the XML formatter will return an empty XML element with the attribute xsi:nil="true" set.

응답 형식 URL 매핑Response Format URL Mappings

클라이언트 쿼리 문자열 또는 일부는 경로의 또는.xml 또는.json 등의 형식에 따른 파일 확장명을 사용 하 여 특정 형식을 URL의 일부로 같은 요청할 수 있습니다.Clients can request a particular format as part of the URL, such as in the query string or part of the path, or by using a format-specific file extension such as .xml or .json. 요청 경로에서 매핑은 API를 사용 하 여 경로에 지정 해야 합니다.The mapping from request path should be specified in the route the API is using. 예:For example:

[FormatFilter]
public class ProductsController
{
    [Route("[controller]/[action]/{id}.{format?}")]
    public Product GetById(int id)

이 경로 사용 하면 요청 된 형식 선택적 파일 확장명으로 지정할 수 있습니다.This route would allow the requested format to be specified as an optional file extension. [FormatFilter] 특성에 형식 값의 존재 여부를 검사는 RouteData 응답 만들어질 때 응답 형식을 적절 한 포맷터에 매핑합니다.The [FormatFilter] attribute checks for the existence of the format value in the RouteData and will map the response format to the appropriate formatter when the response is created.

경로Route 포맷터Formatter
/products/GetById/5 기본 출력 포맷터The default output formatter
/products/GetById/5.json JSON 포맷터 (구성 된 경우)The JSON formatter (if configured)
/products/GetById/5.xml XML 포맷터 (구성 된 경우)The XML formatter (if configured)