ASP.NET Web API 2.1의 새로운 기능
이 항목에서는 ASP.NET Web API 2.1의 새로운 사항에 대해 설명합니다.
다운로드
런타임 기능은 NuGet 갤러리에서 NuGet 패키지로 릴리스됩니다. 모든 런타임 패키지는 의미 체계 버전 관리 사양을 따릅니다. 최신 ASP.NET Web API 2.1 RTM 패키지에는 "5.1.2" 버전이 있습니다. NuGet을 통해 이러한 패키지를 설치하거나 업데이트할 수 있습니다. 릴리스에는 NuGet의 해당 지역화된 패키지도 포함되어 있습니다.
NuGet 패키지 관리자 콘솔을 사용하여 릴리스된 NuGet 패키지를 설치하거나 업데이트할 수 있습니다.
Install-Package Microsoft.AspNet.WebApi -Version 5.1.2
설명서
ASP.NET Web API 2.1 RTM에 대한 자습서 및 기타 정보는 ASP.NET 웹 사이트(https://www.asp.net/web-api)에서 확인할 수 있습니다.
ASP.NET Web API 2.1의 새로운 기능
전역 오류 처리
이제 처리되지 않은 모든 예외를 하나의 중앙 메커니즘을 통해 기록할 수 있으며 처리되지 않은 예외에 대한 동작을 사용자 지정할 수 있습니다.
프레임워크는 처리되지 않은 예외와 발생한 컨텍스트에 대한 정보(예: 당시 처리 중인 요청)를 모두 볼 수 있는 여러 예외 로거를 지원합니다.
예를 들어 다음 코드는 System.Diagnostics.TraceSource를 사용하여 처리되지 않은 모든 예외를 기록합니다.
public class TraceSourceExceptionLogger : ExceptionLogger
{
private readonly TraceSource _traceSource;
public TraceSourceExceptionLogger(TraceSource traceSource)
{
_traceSource = traceSource;
}
public override void Log(ExceptionLoggerContext context)
{
_traceSource.TraceEvent(TraceEventType.Error, 1,
"Unhandled exception processing {0} for {1}: {2}",
context.Request.Method,
context.Request.RequestUri,
context.Exception);
}
}
config.Services.Add(typeof(IExceptionLogger),
new TraceSourceExceptionLogger(new
TraceSource("MyTraceSource", SourceLevels.All)));
처리되지 않은 예외가 발생할 때 전송되는 HTTP 응답 메시지를 완전히 사용자 지정할 수 있도록 기본 예외 처리기를 바꿀 수도 있습니다.
널리 사용되는 ELMAH 프레임워크를 통해 처리되지 않은 모든 예외를 기록하는 샘플을 제공했습니다.
특성 라우팅 개선 사항
특성 라우팅은 이제 제약 조건을 지원하여 버전 관리 및 헤더 기반 경로 선택을 사용하도록 설정합니다. 또한 특성 경로의 여러 측면은 이제 IDirectRouteFactory 인터페이스 및 RouteFactoryAttribute 클래스를 통해 사용자 지정할 수 있습니다. 이제 경로 접두사는 IRoutePrefix 인터페이스 및 RoutePrefixAttribute 클래스를 통해 확장할 수 있습니다.
제약 조건을 사용하여 'api-version' HTTP 헤더로 컨트롤러를 동적으로 필터링하는 샘플을 제공했습니다.
도움말 페이지 개선 사항
Web API 2.1에는 API 도움말 페이지에 대한 다음과 같은 향상된 기능이 포함되어 있습니다.
- 매개 변수의 개별 속성 또는 작업 반환 형식에 대한 설명서입니다.
- 데이터 모델 주석에 대한 설명서입니다.
이러한 변경 내용을 수용하기 위해 도움말 페이지의 UI 디자인도 업데이트되었습니다.
IgnoreRoute 지원
Web API 2.1은 HttpRouteCollection의 IgnoreRoute 확장 메서드 집합을 통해 Web API 라우팅에서 URL 패턴 무시를 지원합니다. 이러한 메서드를 사용하면 Web API가 지정된 템플릿과 일치하는 URL을 무시하고 호스트가 적절한 경우 추가 처리를 적용할 수 있습니다.
다음 예제에서는 "콘텐츠" 세그먼트로 시작하는 URI를 무시합니다.
routes.IgnoreRoute("IgnoreContent", "content/{*paths}");
routes.MapHttpRoute("Default", "{controller}/{id}");
BSON Media-Type 포맷터
이제 Web API는 클라이언트와 서버 모두에서 BSON 와이어 형식을 지원합니다.
서버 쪽에서 BSON을 사용하도록 설정하려면 BsonMediaTypeFormatter 를 formatters 컬렉션에 추가합니다.
config.Formatters.Add(new BsonMediaTypeFormatter());
.NET 클라이언트에서 BSON 형식을 사용할 수 있는 방법은 다음과 같습니다.
// Add Accept header.
client.DefaultRequestHeaders.Accept.Add(
new MediaTypeWithQualityHeaderValue("application/bson"));
// POST data in BSON format.
HttpResponseMessage response = await client.PostAsync<MyData>("api/MyData", data, new
BsonMediaTypeFormatter());
// GET data in BSON format.
data = await response.Content.ReadAsAsync<MyData>(new MediaTypeFormatter[] {
new BsonMediaTypeFormatter() });
클라이언트와 서버 쪽을 모두 보여 주는 샘플을 제공했습니다.
자세한 내용은 Web API 2.1의 BSON 지원을 참조하세요.
비동기 필터에 대한 향상된 지원
이제 Web API는 비동기적으로 실행되는 필터를 만드는 쉬운 방법을 지원합니다. 이 기능은 필터가 데이터베이스 액세스와 같은 비동기 작업을 수행해야 하는 경우에 유용합니다. 이전에는 비동기 필터를 만들려면 필터 기본 클래스가 동기 메서드만 노출되었기 때문에 직접 필터 인터페이스를 구현해야 했습니다. 이제 필터 기본 클래스의 가상 On*Async 메서드를 재정의할 수 있습니다.
예:
public class AsyncLoggingFilter : ActionFilterAttribute
{
public override async Task OnActionExecutingAsync(HttpActionContext actionContext, CancellationToken cancellationToken)
{
await Trace.WriteAsync("Executing action named {0} for request {1}.",
actionContext.ActionDescriptor.ActionName,
actionContext.Request.GetCorrelationId());
}
}
AuthorizationFilterAttribute, ActionFilterAttribute 및 ExceptionFilterAttribute 클래스는 모두 Web API 2.1에서 비동기를 지원합니다.
클라이언트 서식 라이브러리에 대한 쿼리 구문 분석
이전에는 System.Net.Http.Formatting 에서 서버 쪽 코드에 대한 URI 쿼리 구문 분석 및 업데이트를 지원했지만 해당 이식 가능한 라이브러리에 이 기능이 누락되었습니다. Web API 2.1에서 클라이언트 애플리케이션은 이제 쿼리 문자열을 쉽게 구문 분석하고 업데이트할 수 있습니다.
다음 예제에서는 URI 쿼리를 구문 분석, 수정 및 생성하는 방법을 보여 줍니다. (예제에서는 간단히 하기 위해 콘솔 애플리케이션을 보여 줍니다.)
// Query parsing
HttpValueCollection collection = new Uri("http://api/something?catId=3&catId=4&dogId=1,2").ParseQueryString();
Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2
// Modify the query
collection.Add("dogId", "7");
// Index into the values
Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2,7
// Recreate the query string
Console.WriteLine(collection.ToString()); // output: catId=3&catId=4&dogId=1%2C2&dogId=7
// Query generation
HttpValueCollection newCollection = new HttpValueCollection();
newCollection.Add("catId", "1");
newCollection.Add("dogId", "7");
// Index into the values
Console.WriteLine(newCollection["catId"]); // output: 1
Console.WriteLine(newCollection["dogId"]); // output: 7
// Create the query string
Console.WriteLine(newCollection.ToString()); // catId=1&dogId=7
알려진 문제 및 호환성이 손상되는 변경
이 섹션에서는 ASP.NET Web API 2.1 RTM의 알려진 문제 및 호환성이 손상되는 변경에 대해 설명합니다.
특성 라우팅
특성 라우팅 일치의 모호성은 이제 첫 번째 일치 항목을 선택하는 대신 오류를 보고합니다.
특성 경로는 {controller} 매개 변수를 사용하고 작업에 배치된 경로에서 {action} 매개 변수를 사용할 수 없습니다. 이러한 매개 변수는 모호성을 유발할 가능성이 높습니다.
MVC/Web API를 5.1 패키지가 있는 프로젝트로 스캐폴딩하면 프로젝트에 아직 없는 패키지에 대해 5.0개의 패키지가 생성됩니다.
ASP.NET Web API 2.1 RTM용 NuGet 패키지를 업데이트해도 ASP.NET 스캐폴딩 또는 ASP.NET 웹 애플리케이션 프로젝트 템플릿과 같은 Visual Studio 도구는 업데이트되지 않습니다. 이전 버전의 ASP.NET 런타임 패키지(5.0.0.0)를 사용합니다. 따라서 ASP.NET 스캐폴딩은 프로젝트에서 아직 사용할 수 없는 경우 필요한 패키지의 이전 버전(5.0.0.0)을 설치합니다. 그러나 Visual Studio 2013 RTM 또는 업데이트 1의 ASP.NET 스캐폴딩은 프로젝트의 최신 패키지를 덮어쓰지 않습니다.
패키지를 Web API 2.1 또는 ASP.NET MVC 5.1로 업데이트한 후 ASP.NET 스캐폴딩을 사용하는 경우 Web API 및 MVC 버전이 일관된지 확인합니다.
형식 이름 바꾸기
특성 라우팅 확장성에 사용되는 일부 형식의 이름이 RC에서 2.1 RTM으로 바뀌었습니다.
| 이전 형식 이름(2.1 RC) | 새 형식 이름(2.1 RTM) |
|---|---|
| IDirectRouteProvider | IDirectRouteFactory |
| RouteProviderAttribute | RouteFactoryAttribute |
| DirectRouteProviderContext | DirectRouteFactoryContext |
예외 필터는 비동기 작업에서 throw된 집계 예외를 래프 해제하지 않습니다.
이전에는 비동기 작업에서 AggregateException을 throw한 경우 예외 필터가 예외 래이프를 해제하고 OnException에서 기본 예외를 가져옵니다. 2.1에서 예외 필터는 래프 해제하지 않으며 OnException 은 원래 AggregateException을 가져옵니다.
버그 수정
이 릴리스에는 몇 가지 버그 수정도 포함되어 있습니다.
5.1.2 패키지에는 IntelliSense 업데이트가 포함되어 있지만 버그 수정은 없습니다.