모델: 응답 데이터 서식화

콘텐츠 협상 절차

콘텐츠 협상은 요청에 Accept 헤더가 존재하는 경우에만 수행됩니다. 요청에 Accept 헤더가 포함되어 있는 경우, 프레임워크는 우선순위에 따라 Accept 헤더에 지정되어 있는 미디어 유형들을 열거하고, Accept 헤더에 지정된 서식들 중 한 서식으로 응답을 생성할 수 있는 포맷터를 찾으려고 시도합니다. 그러나 프레임워크가 클라이언트의 요청을 만족하는 포맷터를 찾지 못한다면, 그 대신 응답을 생성할 수 있는 첫 번째 포맷터를 찾으려고 시도합니다 (개발자가 406 Not Acceptable을 반환하도록 MvcOptions의 옵션을 구성하지 않았다면). 만약 요청에 XML이 지정됐지만, XML 포맷터가 구성되어 있지 않다면 JSON 포맷터가 사용됩니다. 일반적으로 요청된 서식을 제공할 수 있는 구성된 포맷터가 존재하지 않으면, 해당 개체를 서식화할 수 있는 첫 번째 포맷터가 사용됩니다. 반면 헤더가 지정되지 않았다면 반환되는 개체를 처리할 수 있는 첫 번째 포맷터를 사용해서 응답을 직렬화합니다. 이 경우, 아무런 협상도 수행되지 않으며 서버가 사용될 서식을 일방적으로 결정합니다.

브라우저와 콘텐츠 협상

일반적인 API 클라이언트들과는 달리, 웹 브라우저는 와일드카드를 비롯한 다양한 서식들이 지정된 Accept 헤더를 제공하는 경우가 대부분입니다. 기본적으로 프레임워크는 요청이 브라우저로부터 전달된 것을 감지하더라도, Accept 헤더를 무시하고 대신 응용 프로그램에 구성된 기본 서식으로 (별도로 구성하지 않는 한 JSON 서식으로) 콘텐츠를 반환합니다. 이 방식이 다양한 브라우저들을 이용해서 API를 사용할 때 보다 일관적인 경험을 제공해줍니다.

만약 응용 프로그램에서 브라우저의 Accept 헤더 설정을 반영하도록 구현하고자 한다면, Startup.cs 파일의 ConfigureServices 메서드에서 MVC 구성의 일부로 RespectBrowserAcceptHeader 속성을 true로 설정하여 구성이 가능합니다.

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

XML 서식 지원 추가하기

XML 서식화 기능을 추가하려면, 먼저 "Microsoft.AspNetCore.Mvc.Formatters.Xml" 패키지를 project.json 파일의 의존성 목록에 추가해야 합니다.

그런 다음, Startup.cs 파일에서 MVC의 구성에 XmlSerializerFormatters를 추가합니다:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddXmlSerializerFormatters();

    services.AddScoped<IAuthorRepository, AuthorRepository>();
}

또는, 출력 포맷터만 별도로 추가할 수도 있습니다:

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

이 두 가지 접근방식은 System.Xml.Serialization.XmlSerializer를 이용해서 결과를 직렬화합니다. 만약 원한다면, 관련 포멧터를 추가해서 대신 System.Runtime.Serialization.DataContractSerializer를 사용할 수도 있습니다:

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

XML 서식화 관련 기능을 추가하고 나면, 다음 Fiddler 예제 데모에서 볼 수 있는 것처럼 컨트롤러 메서드가 요청의 Accept 헤더에 따라 적절한 서식으로 결과를 반환하게 됩니다.

이 스크린샷의 Inspectors 탭을 살펴보면 Raw GET 요청에 Accept: application/xml 헤더가 설정되어 있는 것을 확인할 수 있습니다. 그리고 응답 패인을 살펴보면 Content-Type: application/xml 헤더와 XML로 직렬화된 Author 개체를 확인할 수 있습니다.

이번에는 Composer 탭에서 요청을 수정해서 Accept 헤더 값을 application/json으로 설정합니다. 그런 다음, 요청을 실행하면 응답이 JSON으로 서식화되어 반환될 것입니다:

이 스크린샷을 살펴보면, Accept: application/json으로 설정된 요청의 헤더와, 동일하게 설정된 응답의 Content-Type을 확인할 수 있습니다. Author 개체는 JSON으로 서식화되어 응답의 본문에 담겨서 반환됩니다.

특정 서식 강제하기

특정 액션의 응답 서식을 제한하고 싶다면 [Produces] 필터를 적용하면 됩니다. [Produces] 필터는 지정된 액션의 (또는 컨트롤러의) 응답 서식을 지정합니다. 다른 대부분의 필터처럼 이 필터도 액션이나 컨트롤러, 또는 전역 범위에 적용할 수 있습니다.

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

이렇게 [Produces] 필터를 지정하면, 응용 프로그램에 다른 포맷터들이 구성되어 있고 클라이언트로부터 사용 가능한 다양한 서식들이 설정된 Accept 헤더가 전달되더라도, AuthorsController에 존재하는 모든 액션들은 무조건 JSON으로 서식화된 응답을 반환하게 됩니다. 필터를 전역 범위에 적용하는 방법을 비롯한, 필터에 대한 보다 자세한 정보들은 필터(Filters)를 참고하시기 바랍니다.

특수 사례 포맷터

일부 특수한 사례들은 기본 포맷터를 통해서 구현됩니다. 가령 반환 형식이 string일 경우, 기본적으로 text/plain 서식으로 서식화되는데 (Accept 헤더를 통해서 text/html 이 요청된 경우), 이 동작은 TextOutputFormatter를 제거해서 중지시킬 수 있습니다. 다음 코드에서 볼 수 있는 것처럼 포맷터는 Startup.cs 파일의 Configure 메서드에서 제거할 수 있습니다. 또한, 모델 개체를 반환하는 액션의 경우에는 null이 반환되면 자동으로 204 No Content 응답이 반환되는데, 이 동작은 HttpNoContentOutputFormatter를 제거해서 중지시킬 수 있습니다. 다음은 TextOutputFormatter 및 HttpNoContentOutputFormatter를 제거하는 코드입니다.

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

이렇게 TextOutputFormatter가 제거되면 string 반환 형식은 406 Not Acceptable을 반환하게 됩니다. 다만 TextOutputFormatter는 제거됐으나, XML 포맷터가 구성되어 있다면 XML 포맷터를 통해서 string 반환 형식이 서식화된다는 점에 주의하시기 바랍니다.

그리고 HttpNoContentOutputFormatter가 제거되고 나면 null 개체는 구성된 포맷터를 이용해서 서식화 됩니다. 예를 들어서, JSON 포맷터는 간단히 본문이 null인 응답을 반환하는 반면, XML 포맷터는 xsi:nil="true" 어트리뷰트가 설정된 빈 XML 요소를 반환합니다.