ASP.NET Web API 2.1 の新機能

提供元: Microsoft

このトピックでは、ASP.NET Web API 2.1 の新機能について説明します。

• ダウンロード

• ドキュメント

• ASP.NET Web API 2.1 の新機能

  • グローバル エラー処理
  • 属性ルーティングの機能強化
  • ヘルプ ページの機能強化
  • IgnoreRoute のサポート
  • BSON メディアの種類のフォーマッタ
  • 非同期フィルターのサポートの強化
  • クライアント書式設定ライブラリのクエリ解析

• 既知の問題と重大な変更

• バグ修正

ダウンロード

ランタイム機能は、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 Web サイト (https://www.asp.net/web-api) から入手できます。

ASP.NET Web API 2.1 の新機能

グローバル エラー処理

ハンドルされない例外を 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 をすべて無視し、必要に応じてホストが追加の処理を適用できるようにします。

次の例では、"content" セグメントで始まる URI は無視されます。

routes.IgnoreRoute("IgnoreContent", "content/{*paths}");
routes.MapHttpRoute("Default", "{controller}/{id}");

BSON メディアの種類のフォーマッタ

Web API では、クライアントとサーバーの両方で BSON ワイヤー形式がサポートされるようになりました。

サーバー側で BSON を有効にするには、フォーマッタ コレクションに BsonMediaTypeFormatter を追加します。

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 Web アプリケーション プロジェクト テンプレートなどの Visual Studio ツールは更新されません。 これらのツールでは、ASP.NET ランタイム パッケージの旧バージョン (5.0.0.0) を使用します。 その結果、ASP.NET スキャフォールディングでは、必要なパッケージがプロジェクトでまだ使用できない場合、旧バージョン (5.0.0.0) がインストールされます。 ただし、Visual Studio 2013 RTM または Update 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

例外フィルターは、非同期アクションでスローされた集計例外の折り返しを解除しません

以前は、非同期アクションが AggregateException をスローした場合、例外フィルターが例外の折り返しを解除し、OnException が基本例外を取得していました。 2.1 では、例外フィルターは折り返しを解除せず、OnException は元の AggregateException を取得します。

バグの修正

このリリースには、数件バグ修正も含まれています。

5.1.2 パッケージには IntelliSense の更新プログラムが含まれていますが、バグの修正は含まれていません。