ASP.NET Web API 2 の構成

[アーティクル]
05/14/2024

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

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

構成設定

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

メンバー	説明
DependencyResolver	コントローラーで依存関係の挿入を有効にします。 Web API 依存関係リゾルバーの使用に関する記事をご覧ください。
フィルター	アクションフィルター。
Formatters	メディアタイプフォーマッタ。
IncludeErrorDetailPolicy	サーバーが HTTP 応答メッセージに、例外メッセージやスタックトレースなどのエラーの詳細を含める必要があるかどうかを指定します。 IncludeErrorDetailPolicy に関する記事をご覧ください。
Initializer	HttpConfiguration の最終的な初期化を実行する関数。
MessageHandlers	HTTP メッセージハンドラー。
ParameterBindingRules	コントローラーアクションでのパラメーターのバインドに関する規則のコレクション。
Properties	汎用プロパティバッグ。
Routes	ルートのコレクション。「ASP.NET Web API でのルーティング」をご覧ください。
サービス	サービスのコレクション。サービスに関する記事をご覧ください。

前提条件

Visual Studio 2017 Community、Professional、または Enterprise エディション。

ASP.NET ホスティングでの Web API の構成

ASP.NET アプリケーションで Web API を構成するには、Application_Start メソッドで GlobalConfiguration.Configure を呼び出します。 Configure メソッドは、HttpConfiguration 型の 1 つのパラメーターでデリゲートを受け取ります。すべての構成はデリゲート内で実行します。

匿名デリゲートの使用例を次に示します。

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 構成コードを配置する必要があるデリゲートが定義されています。

Screenshot of Solution Explorer dialog, with Web A P I Config dot c s outlined in red, inside App Start folder.

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 が使うグローバルサービスのセットが含まれています。

Note

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

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

単一インスタンスサービス

サービス	説明
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	モデル検証コントロールのキャッシュを提供します。

複数インスタンスサービス

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

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

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

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

次の方法で共有