ASP.NET Web API 2 の構成

[アーティクル]
07/13/2023

このトピックでは、ASP.NET Web APIを構成する方法について説明します。

構成設定
ASP.NET ホスティングを使用した Web API の構成
OWIN セルフホスティングを使用した Web API の構成
グローバル Web API サービス
コントローラーごとの構成

構成設定

Web API 構成設定は、 HttpConfiguration クラスで定義されます。

メンバー	説明
DependencyResolver	コントローラーの依存関係の挿入を有効にします。「Web API 依存関係リゾルバーの使用」を参照してください。
フィルター	アクションフィルター。
フォーマッタ	メディア型フォーマッタ。
IncludeErrorDetailPolicy	サーバーに、例外メッセージやスタックトレースなどのエラーの詳細を HTTP 応答メッセージに含めるかどうかを指定します。 IncludeErrorDetailPolicy を参照してください。
初期化子	HttpConfiguration の最終的な初期化を実行する関数。
MessageHandlers	HTTP メッセージハンドラー。
ParameterBindingRules	コントローラーアクションのバインドパラメーターに関する規則のコレクション。
Properties	汎用プロパティバッグ。
Routes	ルートのコレクション。「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 構成コードを配置する必要があるデリゲートを定義します。

[アプリの開始] フォルダー内で、Web A P I Config ドット c が赤で囲まれた [ソリューションエクスプローラー] ダイアログのスクリーンショット。

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 を使用して 2 をSelf-Host ASP.NET Web APIする」のチュートリアルでは、完全な手順を示します。

グローバル Web API サービス

HttpConfiguration.Services コレクションには、コントローラーの選択やコンテンツネゴシエーションなど、さまざまなタスクを実行するために Web API が使用するグローバルサービスのセットが含まれています。

Note

Services コレクションは、サービス検出または依存関係の挿入のための汎用メカニズムではありません。 Web API フレームワークに認識されているサービスの種類のみが格納されます。

Services コレクションは、既定のサービスセットで初期化され、独自のカスタム実装を提供できます。複数のインスタンスをサポートするサービスもあれば、インスタンスを 1 つだけ持つサービスもあります。 (ただし、コントローラーレベルでサービスを提供することもできます。「コントローラーごとの構成」を参照してください。

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 メソッドは、次の 2 つのパラメーターを受け取ります。

HttpControllerSettings オブジェクト
HttpControllerDescriptor オブジェクト

HttpControllerDescriptor にはコントローラーの説明が含まれています。この説明は、情報を得るために調べることができます (たとえば、2 つのコントローラーを区別するため)。

コントローラーを構成するには、 HttpControllerSettings オブジェクトを使用します。このオブジェクトには、コントローラーごとにオーバーライドできる構成パラメーターのサブセットが含まれています。既定でグローバル HttpConfiguration オブジェクトに変更しない設定。