What is parameter binding in C# ASP.NET WebAPI?

Parameter binding in ASP.NET Web API is the process of automatically mapping HTTP request data to controller action method parameters. Web API uses different binding strategies based on the parameter type and can be customized using attributes.

Understanding how parameter binding works is essential for building robust Web APIs that can correctly receive and process data from HTTP requests.

Default Parameter Binding Rules

Web API follows these default rules for parameter binding −

• Simple types (int, bool, double, string, DateTime, GUID) are bound from the URI (route data or query string)

• Complex types (custom classes, objects) are bound from the request body

Simple Type Binding from URI

By default, simple types are extracted from the URI −

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class StudentsController : ControllerBase {
   [HttpGet("{id}")]
   public IActionResult Get(int id) {
      return Ok($"Student ID: {id}");
   }
   
   [HttpGet]
   public IActionResult Search(string name, int age) {
      return Ok($"Searching for: {name}, Age: {age}");
   }
}

public class Program {
   public static void Main(string[] args) {
      Console.WriteLine("Web API Parameter Binding Examples");
      Console.WriteLine("GET /api/students/123 - id=123 from route");
      Console.WriteLine("GET /api/students?name=John&age=25 - from query string");
   }
}

The output of the above code is −

Web API Parameter Binding Examples
GET /api/students/123 - id=123 from route
GET /api/students?name=John&age=25 - from query string

Complex Type Binding from Request Body

Complex types are automatically bound from the request body using JSON deserialization −

using Microsoft.AspNetCore.Mvc;
using System;

public class Employee {
   public int Id { get; set; }
   public string Name { get; set; }
   public string Department { get; set; }
}

[ApiController]
[Route("api/[controller]")]
public class EmployeesController : ControllerBase {
   [HttpPost]
   public IActionResult Post(Employee employee) {
      return Ok($"Created: {employee.Name} in {employee.Department}");
   }
}

public class Program {
   public static void Main(string[] args) {
      Console.WriteLine("Complex Type Binding Example");
      Console.WriteLine("POST /api/employees");
      Console.WriteLine("Request Body: {"Id": 1, "Name": "John", "Department": "IT"}");
      Console.WriteLine("Response: Created: John in IT");
   }
}

The output of the above code is −

Complex Type Binding Example
POST /api/employees
Request Body: {"Id": 1, "Name": "John", "Department": "IT"}
Response: Created: John in IT

Using [FromUri] Attribute

The [FromUri] attribute forces complex types to be bound from the URI instead of the request body −

using Microsoft.AspNetCore.Mvc;
using System;

public class SearchCriteria {
   public string Name { get; set; }
   public int MinAge { get; set; }
   public string Department { get; set; }
}

[ApiController]
[Route("api/[controller]")]
public class SearchController : ControllerBase {
   [HttpGet]
   public IActionResult Get([FromQuery] SearchCriteria criteria) {
      return Ok($"Searching: {criteria.Name}, MinAge: {criteria.MinAge}, Dept: {criteria.Department}");
   }
}

public class Program {
   public static void Main(string[] args) {
      Console.WriteLine("[FromQuery] Attribute Example");
      Console.WriteLine("GET /api/search?Name=John&MinAge=25&Department=IT");
      Console.WriteLine("Complex object bound from query string parameters");
   }
}

The output of the above code is −

[FromQuery] Attribute Example
GET /api/search?Name=John&MinAge=25&Department=IT
Complex object bound from query string parameters

Using [FromBody] Attribute

The [FromBody] attribute forces simple types to be read from the request body −

using Microsoft.AspNetCore.Mvc;
using System;

[ApiController]
[Route("api/[controller]")]
public class MessagesController : ControllerBase {
   [HttpPost("simple")]
   public IActionResult PostSimple([FromBody] string message) {
      return Ok($"Received message: {message}");
   }
   
   [HttpPost("number")]
   public IActionResult PostNumber([FromBody] int value) {
      return Ok($"Received number: {value}");
   }
}

public class Program {
   public static void Main(string[] args) {
      Console.WriteLine("[FromBody] Attribute Example");
      Console.WriteLine("POST /api/messages/simple");
      Console.WriteLine("Request Body: "Hello World"");
      Console.WriteLine("POST /api/messages/number"); 
      Console.WriteLine("Request Body: 42");
   }
}

The output of the above code is −

[FromBody] Attribute Example
POST /api/messages/simple
Request Body: "Hello World"
POST /api/messages/number
Request Body: 42

Parameter Binding Attributes

Key Rules

• Only one parameter per action can use [FromBody]

• Simple types default to URI binding, complex types to body binding

• Use binding attributes to override default behavior

• Model binding occurs before the action method executes

Conclusion

Parameter binding in ASP.NET Web API automatically maps HTTP request data to action method parameters based on type. Simple types bind from URI by default, while complex types bind from the request body. Use [FromQuery], [FromBody], and other binding attributes to customize this behavior when needed.