A Complete Guide - ASP.NET Core Model Binding and Return Types

Step 1: Create an ASP.NET Core Web API Project

First, you'll need to create a new project in Visual Studio or using the dotnet CLI.

Using Visual Studio:

1. Select "Create a new project".
2. Choose "ASP.NET Core Web API".
3. Click "Next".
4. Enter your project details and click "Next".
5. Select "API" as the template and click "Create".

Using the .NET CLI:

dotnet new webapi -n ModelBindingAndReturnTypesExample
cd ModelBindingAndReturnTypesExample

Step 2: Define a Model for the API

For our example, we'll create a Product model. You can add this class in a Models folder.

// Models/Product.cs

using System.ComponentModel.DataAnnotations;

public class Product
{
    [Key]
    public int ProductId { get; set; }

    [Required]
    [StringLength(100)]
    public string Name { get; set; }

    [Required]
    [Range(0.01, double.MaxValue, ErrorMessage = "Price must be bigger than 0")]
    public decimal Price { get; set; }

    [StringLength(250)]
    public string Description { get; set; }
}

Step 3: Create a Controller for Handling Requests

In the Controllers folder, add a new controller named ProductsController.

// Controllers/ProductsController.cs

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Threading.Tasks;
using ModelBindingAndReturnTypesExample.Models;
using System.Linq;

[ApiController]
[Route("api/products")]
public class ProductsController : ControllerBase
{
    private static List<Product> _products = new List<Product>
    {
        new Product { ProductId = 1, Name = "Keyboard", Price = 50.0M },
        new Product { ProductId = 2, Name = "Mouse", Price = 20.0M }
    };

    // Get all products
    [HttpGet]
    public IActionResult GetProducts()
    {
        return Ok(_products);
    }

    // Get a product by ID
    [HttpGet("{id}")]
    public ActionResult<Product> GetProductById(int id)
    {
        var product = _products.FirstOrDefault(p => p.ProductId == id);

        if (product == null)
        {
            return NotFound();
        }

        return product;
    }

    // Adding a product
    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public IActionResult AddProduct([FromBody] Product product)
    {
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        product.ProductId = _products.Max(p => p.ProductId) + 1;
        _products.Add(product);

        return CreatedAtAction(nameof(GetProductById), new { id = product.ProductId }, product);
    }

    // Update an existing product
    [HttpPut("{id}")]
    [ProducesResponseType(StatusCodes.Status204NoContent)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public IActionResult UpdateProduct(int id, [FromBody] Product productUpdate)
    {
        var product = _products.FirstOrDefault(p => p.ProductId == id);

        if (product == null)
        {
            return NotFound();
        }

        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        product.Name = productUpdate.Name;
        product.Price = productUpdate.Price;
        product.Description = productUpdate.Description;

        return NoContent();
    }

    // Delete a product
    [HttpDelete("{id}")]
    [ProducesResponseType(StatusCodes.Status204NoContent)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    public IActionResult DeleteProduct(int id)
    {
        var product = _products.FirstOrDefault(p => p.ProductId == id);

        if (product == null)
        {
            return NotFound();
        }

        _products.Remove(product);

        return NoContent();
    }
}

Step 4: Test the Endpoints

You can use Postman or any other tool to test these endpoints.

Get All Products:

• Endpoint: GET /api/products
• Response:

  [
    {
      "productId": 1,
      "name": "Keyboard",
      "price": 50.0,
      "description": ""
    },
    {
      "productId": 2,
      "name": "Mouse",
      "price": 20.0,
      "description": ""
    }
  ]
  

Get Product By ID:

• Endpoint: GET /api/products/1
• Response:

  {
    "productId": 1,
    "name": "Keyboard",
    "price": 50.0,
    "description": ""
  }
  

• Endpoint: GET /api/products/99
• Response: 404 Not Found

Add A Product:

• Endpoint: POST /api/products
• Request Body:

  {
    "name": "Monitor",
    "price": 150.0,
    "description": "A high-resolution monitor"
  }
  

• Response: 201 Created
  You should receive a response indicating the product was created successfully, including its ID and other details.

Update A Product:

• Endpoint: PUT /api/products/1
• Request Body:

  {
    "name": "Mechanical Keyboard",
    "price": 75.0,
    "description": "High-performance mechanical keyboard"
  }
  

• Response: 204 No Content

Delete A Product:

• Endpoint: DELETE /api/products/1
• Response: 204 No Content

Step 5: Understanding Model Binding

Model binding maps data from HTTP requests to action method parameters. In our API, model binding is used to extract Product objects from the request body when AddProduct or UpdateProduct actions are invoked.

Example of Model Binding in AddProduct

When you make a POST request to /api/products, the [FromBody] attribute tells the framework to look for the JSON object in the request body and map it to the Product parameter in the AddProduct method.

If the JSON format is wrong (e.g., missing required fields or invalid values) the ModelState will be invalid.

if (!ModelState.IsValid)
{
    return BadRequest(ModelState);
}

Step 6: Understanding Return Types

There are different ways to return a response from an API controller method. Here are some of them illustrated:

Returning an Object

return Ok(_products); returns a 200 OK response along with the list of products serialized in JSON.

Returning a Single Object or HTTP 404 if Not Found

return product; returns a 200 OK response if the object is found. If not, return NotFound(); returns a 404 Not Found.

Returning HTTP Response Codes

return BadRequest(ModelState); returns a 400 Bad Request response if the input model validation fails. return CreatedAtAction(nameof(GetProductById), new { id = product.ProductId }, product); returns a 201 Created response after adding the product, along with a URL pointing to the newly created resource. return NoContent(); returns a 204 No Content response after successfully updating or deleting a resource. return NotFound(); returns a 404 Not Found response if the resource does not exist.

Summary:

This example covers:

• Creating a simple ASP.NET Core Web API.
• Defining the Product model.
• Various controller actions demonstrating HttpGet, HttpPost, HttpPut, and HttpDelete.
• How to perform model binding using [FromBody].
• Handling validation and returning responses with [ProducesResponseType].
• Returning different types of responses such as IActionResult, ActionResult<T>, and custom status codes.