設定 ASP.NET Web API 2

本主題描述如何設定 ASP.NET Web API。

• 組態設定
• 使用 ASP.NET 裝載來設定 Web API
• 使用 OWIN 自我裝載設定 Web API
• 全域 Web API 服務
• 個別控制器組態

組態設定

Web API 組態設定定義于 HttpConfiguration 類別中。

member	描述
DependencyResolver	啟用控制器的相依性插入。 請參閱 使用 Web API 相依性解析程式。
篩選	動作篩選條件。
格式器	媒體類型格式器。
IncludeErrorDetailPolicy	指定伺服器是否應該在 HTTP 回應訊息中包含錯誤詳細資料，例如例外狀況訊息和堆疊追蹤。 請參閱 IncludeErrorDetailPolicy。
初始 化	執行 HttpConfiguration最終初始化的函式。
MessageHandlers	HTTP 訊息處理常式。
ParameterBindingRules	控制器動作上系結參數的規則集合。
屬性	泛型屬性包。
路由	路由的集合。 請參閱ASP.NET Web API中的路由。
服務	服務的集合。 請參閱 服務。

必要條件

Visual Studio 2017 Community、Professional 或 Enterprise 版。

使用 ASP.NET 裝載來設定 Web API

在 ASP.NET 應用程式中，在Application_Start方法中呼叫GlobalConfiguration.Configure來設定 Web API。 Configure方法會採用具有HttpConfiguration類型的單一參數的委派。 在委派內執行所有組態。

以下是使用匿名委派的範例：

using System.Web.Http;
namespace WebApplication1
{
    public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            GlobalConfiguration.Configure(config =>
            {
                config.MapHttpAttributeRoutes();

                config.Routes.MapHttpRoute(
                    name: "DefaultApi",
                    routeTemplate: "api/{controller}/{id}",
                    defaults: new { id = RouteParameter.Optional }
                );
            });
        }
    }
}

在 Visual Studio 2017 中，如果您在 [ 新增 ASP.NET 專案 ] 對話方塊中選取 [Web API]，「ASP.NET Web 應用程式」 專案範本會自動設定組態代碼。

專案範本會在 App_Start 資料夾中建立名為 WebApiConfig.cs 的檔案。 此程式碼檔案會定義您應該放置 Web API 組態程式碼的委派。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace WebApplication1
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // TODO: Add any additional configuration code.

            // Web API routes
            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

專案範本也會新增從 Application_Start呼叫委派的程式碼。

public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        GlobalConfiguration.Configure(WebApiConfig.Register);
    }
}

使用 OWIN Self-Hosting設定 Web API

如果您是使用 OWIN 進行自我裝載，請建立新的 HttpConfiguration 實例。 在此實例上執行任何組態，然後將 實例傳遞至 Owin.UseWebApi 擴充方法。

public class Startup 
{ 
    public void Configuration(IAppBuilder appBuilder) 
    { 
        HttpConfiguration config = new HttpConfiguration(); 

        config.Routes.MapHttpRoute( 
            name: "DefaultApi", 
            routeTemplate: "api/{controller}/{id}", 
            defaults: new { id = RouteParameter.Optional } 
        ); 

        appBuilder.UseWebApi(config); 
    } 
}

本教學課程使用 OWIN Self-Host ASP.NET Web API 2會顯示完整的步驟。

全域 Web API 服務

HttpConfiguration.Services集合包含一組全域服務，Web API 用來執行各種工作，例如控制器選取和內容交涉。

注意

Services集合不是服務探索或相依性插入的一般用途機制。 它只會儲存 Web API 架構已知的服務類型。

Services集合會以一組預設的服務初始化，而且您可以提供自己的自訂實作。 有些服務支援多個實例，而其他服務則只能有一個實例。 不過， (您也可以在控制器層級提供服務;請參閱 個別控制器組態。

Single-Instance服務

服務	描述
IActionValueBinder	取得參數的系結。
IApiExplorer	取得應用程式所公開之 API 的描述。 請參閱 建立 Web API 的說明頁面。
IAssembliesResolver	取得應用程式的元件清單。 請參閱 路由和動作選取。
IBodyModelValidator	驗證由媒體類型格式器從要求本文讀取的模型。
IContentNegotiator	執行內容交涉。
IDocumentationProvider	提供 API 的檔。 預設值為 null。 請參閱 建立 Web API 的說明頁面。
IHostBufferPolicySelector	指出主機是否應該緩衝處理 HTTP 訊息實體主體。
IHttpActionInvoker	叫用控制器動作。 請參閱 路由和動作選取。
IHttpActionSelector	選取控制器動作。 請參閱 路由和動作選取。
IHttpControllerActivator	啟動控制器。 請參閱 路由和動作選取。
IHttpControllerSelector	選取控制器。 請參閱 路由和動作選取。
IHttpControllerTypeResolver	提供應用程式中的 Web API 控制器類型清單。 請參閱 路由和動作選取。
ITraceManager	初始化追蹤架構。 請參閱ASP.NET Web API中的追蹤。
ITraceWriter	提供追蹤寫入器。 預設值為「no-op」 追蹤寫入器。 請參閱ASP.NET Web API中的追蹤。
IModelValidatorCache	提供模型驗證程式的快取。

Multiple-Instance服務

服務	描述
IFilterProvider	傳回控制器動作的篩選準則清單。
ModelBinderProvider	傳回指定類型的模型系結器。
ModelMetadataProvider	提供模型的中繼資料。
ModelValidatorProvider	提供模型的驗證程式。
ValueProviderFactory	建立值提供者。 如需詳細資訊，請參閱 Mike Stall 的部落格文章 如何在 WebAPI 中建立自訂值提供者

若要將自訂實作新增至多重實例服務，請在Services集合上呼叫Add或Insert：

config.Services.Add(typeof(IFilterProvider), new MyFilterProvider());

若要以自訂實作取代單一實例服務，請在Services集合上呼叫Replace：

config.Services.Replace(typeof(ITraceWriter), new MyTraceWriter());

Per-Controller設定

您可以依據每個控制器覆寫下列設定：

• 媒體類型格式器
• 參數系結規則
• 服務

若要這樣做，請定義實作 IControllerConfiguration 介面的自訂屬性。 然後將 屬性套用至控制器。

下列範例會將預設媒體類型格式子取代為自訂格式器。

using System;
using System.Web.Http;
using System.Web.Http.Controllers;

namespace WebApplication1.Controllers
{

    public class UseMyFormatterAttribute : Attribute, IControllerConfiguration
    {
        public void Initialize(HttpControllerSettings settings,
            HttpControllerDescriptor descriptor)
        {
            // Clear the formatters list.
            settings.Formatters.Clear();

            // Add a custom media-type formatter.
            settings.Formatters.Add(new MyFormatter());
        }
    }

    [UseMyFormatter]
    public class ValuesController : ApiController
    {
        // Controller methods not shown...
    }
}

IControllerConfiguration.Initialize方法會採用兩個參數：

• HttpControllerSettings物件
• HttpControllerDescriptor物件

HttpControllerDescriptor包含控制器的描述，您可以檢查其資訊用途， (說來區分兩個控制器) 。

使用 HttpControllerSettings 物件來設定控制器。 此物件包含您可以依每個控制器覆寫的組態參數子集。 您不會變更為全域 HttpConfiguration 物件的任何設定。