設定 ASP.NET Web API 2

發行項
09/27/2024

本主題介紹如何設定 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。設定方法採用帶有 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 組態程式碼的委派。

Solution Explorer 對話框的螢幕擷取畫面，以紅色框出位於 App_Start 文件夾中的 Web API Config.cs。

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 自我裝載設定 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 自我裝載 ASP.NET Web API 2 展示了完整的步驟。

全域 Web API 服務

HttpConfiguration.Services 集合包含一組全域服務，Web API 會使用這些服務來執行各種工作，例如控制器選擇和內容協商。

注意

Services 集合不是通用的服務發現或依賴注入機制。它僅儲存 Web API 架構已知的服務類型。

Services 集合會使用一組預設的服務進行初始化，您可以提供自己的自訂實作。有些服務支援多個執行個體，而其他服務只能有一個執行個體。 (但是，您也可以在控制器層級提供服務；請參閱每個控制器組態。)

單一執行個體服務

Service	描述
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	提供追蹤寫入器。預設是「無作業」追蹤寫入器。請參閱「ASP.NET Web API 中的追蹤」。
IModelValidatorCache	提供模型驗證程式的快取。

多執行個體服務

Service	描述
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());

每個控制器組態

您可以針對每個控制器覆寫以下設定：

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

若要這樣做，請定義一個實作 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 物件。

共用方式為