ASP.NET Web API 2.1 的新功能

發行項
06/25/2023

本主題描述 ASP.NET Web API 2.1 的新功能。

下載
文件集
ASP.NET Web API 2.1 中的新功能
已知問題和重大變更
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 Media-Type Formatter

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 Scaffolding 至具有 5.1 套件的專案會產生 5.0 個套件，而專案中尚未存在的專案則會產生 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 Scaffolding 將會安裝舊版 (5.0.0.0) 所需的套件，如果您的專案中尚未提供這些套件。不過，Visual Studio 2013 RTM 或 Update 1 中的 ASP.NET Scaffolding 不會覆寫專案中的最新套件。

如果您在將套件更新至 Web API 2.1 或 ASP.NET MVC 5.1 之後使用 ASP.NET Scaffolding，請確定 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。

錯誤修正

此版本也包含數個 Bug 修正。

5.1.2 套件包含 IntelliSense 更新，但沒有錯誤修正。

共用方式為