C# ASP.NET Web APIのパラメーターバインディングとは？基本の仕組みと[FromBody]・[FromUri]属性の使い方

バインディング（Binding）とは、Web APIがコントローラーのアクションメソッドを呼び出す際に、そのメソッドのパラメーターへ値を設定するプロセスのことです。

この記事では、さまざまな型のパラメーターを持つWeb APIメソッドがどのように動作するのか、そしてバインディング処理をカスタマイズする方法について詳しく解説します。

デフォルトのバインディング動作

Web APIは、パラメーターの型に応じて自動的に値の取得元を判断します。

• 単純型（Simple Type）の場合： int、bool、doubleなどのプリミティブ型のパラメーターに対しては、Web APIはURIから値を取得しようとします。具体的には、ルートデータ（Route Data）またはクエリ文字列（Query String）が対象となります。
• 複合型（Complex Type）の場合： CustomerやEmployeeなどの複合型のパラメーターに対しては、Web APIフレームワークはリクエストボディ（Request Body）から値を取得しようとします。

このデフォルトの動作は、[FromBody]属性および[FromUri]属性を使用することで自由に変更できます。

単純型のバインディング（FromUri）

パラメーターが単純型である場合、Web APIはURIから値を取得します。対象となるのは、double、DateTime、GUID、stringなど、文字列型から変換可能な.NETのプリミティブ型です。

例

public Student Get(int id) { }

複合型のバインディング（FromBody）

パラメーターが複合型である場合、Web APIはメッセージボディから値をバインドします。

例

public Student Post(Employee employee) { }

[FromUri]属性で複合型をURIから取得する

通常、複合型はリクエストボディから取得されますが、[FromUri]属性をパラメーターに付与すると、Web APIに強制的にURI（クエリ文字列）から複合型の値を読み込ませることができます。

例

public Student Get([FromUri] Employee employee)
public HttpResponseMessage Get([FromUri] Employee employee) { ... }

[FromBody]属性で単純型をリクエストボディから取得する

逆に、単純型の値をリクエストボディから取得したい場合は、[FromBody]属性を使用します。これはデフォルトの動作とは正反対の指定です。

次の例では、Web APIがメディアタイプフォーマッター（Media-Type Formatter）を使用して、リクエストボディからnameの値を読み取ります。

例

public Student Post([FromBody] string name) { ... }
public HttpResponseMessage Post([FromBody] string name) { ... }

[FromBody]使用時の注意点

[FromBody]属性は、1つのアクションメソッド内で複数指定できません。1つのアクションにつき、リクエストボディから読み取れるパラメーターは1つだけという制限があるため、注意が必要です。複数の値を受け渡したい場合は、それらをまとめた複合型のクラスを定義して受け取るようにしましょう。

まとめ

パラメーターバインディングの仕組みと[FromBody]・[FromUri]属性を使いこなすことで、Web APIの入力処理を柔軟に設計できるようになります。