ASP.NET Web API 2.1 的新功能

由 Microsoft 提供

本主題旨在說明 ASP.NET Web API 2.1 的新增功能。

• 下載

• 文件

• ASP.NET Web API 2.1 的新功能

  • 全域錯誤處理
  • 屬性路由改善
  • 說明頁面改善
  • IgnoreRoute 支援
  • BSON 媒體類型格式器
  • 更好的非同步篩選支援
  • 用戶端格式化程式庫的查詢剖析

• 已知問題和重大變更

• Bug 修正

下載

執行時間功能在 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 網站 (https://www.asp.net/web-api) 取得 ASP.NET Web API 2.1 RTM 的教學課程和其他資訊。

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 媒體類型格式化程式

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 套件不會更新 Visual Studio 工具，例如 ASP.NET Scaffolding 或 ASP.NET Web 應用程式專案範本。 它們使用舊版的 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 更新，但沒有錯誤修正。