ATK.Command.AspNet.ModelBinder 0.0.5

How to Use Model Binder in ASP.NET

This guide explains how to use the Model Binder to automatically bind JSON command objects from HTTP requests based on a command interface.

Installation

dotnet add package ATK.Command.AspNet.ModelBinder

Core Concept

The model binder works on the basis of a command interface that all commands implement. This enables:

• ✅ Polymorphic binding of multiple command types
• ✅ Centralized authentication and validation
• ✅ Type-safe deserialization based on $type in JSON

Step-by-Step Guide

Step 1: Define Command Interface

Create an interface that all commands will implement:

namespace MyApp.Commands
{
    public interface IUserCommand
    {
        // All commands implementing IUserCommand can be bound
    }
}

Step 2: Create Concrete Commands

Create concrete command classes that implement the interface:

using System.ComponentModel.DataAnnotations;

public class CreateUserCommand : IUserCommand
{
    [Required]
    [StringLength(50)]
    public string Username { get; set; }

    [Required]
    [EmailAddress]
    public string Email { get; set; }

    public string FullName { get; set; }
}

public class UpdateUserCommand : IUserCommand
{
    [Required]
    public int UserId { get; set; }

    [StringLength(50)]
    public string Username { get; set; }

    [EmailAddress]
    public string Email { get; set; }
}

public class DeleteUserCommand : IUserCommand
{
    [Required]
    public int UserId { get; set; }
}

Step 3: Register Model Binder

Register the model binder for the interface in Program.cs:

using ATK.Command.AspNet.ModelBinder;
using ATK.Command.AspNet.ModelBinder.CommandAuthentications;

var builder = WebApplicationBuilder.CreateBuilder(args);

// Setup authentication
builder.Services.AddAuthentication("Bearer");
builder.Services.AddAuthorization();

// Register model binder with the command interface
var commandAuthentications = new List<ICommandAuthentication>
{
    new DefaultCommandAuthentication()
};

builder.Services.AddControllers(options =>
{
    // IMPORTANT: Register the INTERFACE, not individual command classes!
    options.ModelBinderProviders.Insert(0, 
        new RequestCommandModelBinderProvider<IUserCommand>(commandAuthentications));
});

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

Step 4: Use in Controller

The controller accepts the interface as parameter. The model binder automatically deserializes to the correct command type:

[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    [HttpPost]
    public IActionResult ProcessUserCommand(IUserCommand command)
    {
        // Check validation
        if (!ModelState.IsValid)
        {
            return BadRequest(ModelState);
        }

        // Use pattern matching to check the concrete type
        return command switch
        {
            CreateUserCommand createCmd => HandleCreateUser(createCmd),
            UpdateUserCommand updateCmd => HandleUpdateUser(updateCmd),
            DeleteUserCommand deleteCmd => HandleDeleteUser(deleteCmd),
            _ => BadRequest("Unknown command type")
        };
    }

    private IActionResult HandleCreateUser(CreateUserCommand command)
    {
        // Create new user
        return Ok(new { message = $"User {command.Username} created" });
    }

    private IActionResult HandleUpdateUser(UpdateUserCommand command)
    {
        // Update user
        return Ok(new { message = $"User {command.UserId} updated" });
    }

    private IActionResult HandleDeleteUser(DeleteUserCommand command)
    {
        // Delete user
        return Ok(new { message = $"User {command.UserId} deleted" });
    }
}

Step 5: Send JSON Request

The JSON must include the $type information so the model binder deserializes to the correct command type:

# CreateUserCommand
curl -X POST https://localhost:5001/api/user \
  -H "Content-Type: application/json" \
  -d '{
    "$type": "MyApp.Commands.CreateUserCommand, MyApp",
    "username": "john.doe",
    "email": "john@example.com",
    "fullName": "John Doe"
  }'

# UpdateUserCommand
curl -X POST https://localhost:5001/api/user \
  -H "Content-Type: application/json" \
  -d '{
    "$type": "MyApp.Commands.UpdateUserCommand, MyApp",
    "userId": 1,
    "username": "jane.doe",
    "email": "jane@example.com"
  }'

# DeleteUserCommand
curl -X POST https://localhost:5001/api/user \
  -H "Content-Type: application/json" \
  -d '{
    "$type": "MyApp.Commands.DeleteUserCommand, MyApp",
    "userId": 1
  }'

Authentication & Authorization

Allow Anonymous Commands

To allow a command without authentication, use the [AllowAnonymous] attribute:

[AllowAnonymous]
public class PublicSearchCommand : IUserCommand
{
    public string Query { get; set; }
}

Require Roles

Use the [Authorize] attribute to require specific roles:

[Authorize(Roles = "Admin")]
public class DeleteUserCommand : IUserCommand
{
    [Required]
    public int UserId { get; set; }
}

Require Claims

Use the [ClaimRequirement] attribute for claim-based authorization:

[ClaimRequirement("department", "hr")]
public class PromoteEmployeeCommand : IHRCommand
{
    public int EmployeeId { get; set; }
    public string NewPosition { get; set; }
}

Custom Authentication

Implement ICommandAuthentication for custom authentication logic:

public class ApiKeyCommandAuth : ICommandAuthentication
{
    public bool Execute(ModelBindingContext bindingContext, object model)
    {
        var httpContext = bindingContext.ActionContext.HttpContext;

        if (!httpContext.Request.Headers.TryGetValue("X-API-Key", out var apiKey))
        {
            bindingContext.ModelState.TryAddModelError("Unauthorized", "Missing API Key");
            return false;
        }

        if (!ValidateApiKey(apiKey.ToString()))
        {
            bindingContext.ModelState.TryAddModelError("Unauthorized", "Invalid API Key");
            return false;
        }

        bindingContext.Result = ModelBindingResult.Success(model);
        return true;
    }

    private bool ValidateApiKey(string apiKey)
    {
        // Your validation logic
        return !string.IsNullOrEmpty(apiKey);
    }
}

// Register in Program.cs
var authentications = new List<ICommandAuthentication>
{
    new ApiKeyCommandAuth(),
    new DefaultCommandAuthentication()
};

builder.Services.AddControllers(options =>
{
    options.ModelBinderProviders.Insert(0, 
        new RequestCommandModelBinderProvider<IUserCommand>(authentications));
});

Data Validation

Use DataAnnotations for automatic validation:

public class CreateUserCommand : IUserCommand
{
    [Required(ErrorMessage = "Username is required")]
    [StringLength(50, MinimumLength = 3, 
        ErrorMessage = "Username must be between 3 and 50 characters")]
    public string Username { get; set; }

    [Required]
    [EmailAddress(ErrorMessage = "Invalid email address")]
    public string Email { get; set; }

    [MinLength(5, ErrorMessage = "FullName must be at least 5 characters")]
    public string FullName { get; set; }
}

Validation in Controller

[HttpPost]
public IActionResult ProcessCommand(IUserCommand command)
{
    if (!ModelState.IsValid)
    {
        var errors = ModelState.Values
            .SelectMany(v => v.Errors)
            .Select(e => e.ErrorMessage);

        return BadRequest(new { errors = errors });
    }

    // Process command
    return Ok();
}

Multiple Command Interfaces

You can register multiple command interfaces:

builder.Services.AddControllers(options =>
{
    var defaultAuth = new List<ICommandAuthentication>
    {
        new DefaultCommandAuthentication()
    };

    // Register different command interfaces
    options.ModelBinderProviders.Insert(0, 
        new RequestCommandModelBinderProvider<IUserCommand>(defaultAuth));
    options.ModelBinderProviders.Insert(1, 
        new RequestCommandModelBinderProvider<IOrderCommand>(defaultAuth));
    options.ModelBinderProviders.Insert(2, 
        new RequestCommandModelBinderProvider<IProductCommand>(defaultAuth));
});

Error Handling

The model binder provides informative error messages in ModelState:

Handle errors in your controller:

[HttpPost]
public IActionResult ProcessCommand(IUserCommand command)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(new 
        { 
            errors = ModelState
                .Where(ms => ms.Value.Errors.Count > 0)
                .ToDictionary(
                    kvp => kvp.Key,
                    kvp => kvp.Value.Errors.Select(e => e.ErrorMessage))
        });
    }

    // Process command
    return Ok();
}

Complete Configuration Example

using ATK.Command.AspNet.ModelBinder;
using ATK.Command.AspNet.ModelBinder.CommandAuthentications;
using MyApp.Commands;

var builder = WebApplicationBuilder.CreateBuilder(args);

// Setup authentication
builder.Services.AddAuthentication("Bearer");
builder.Services.AddAuthorization();

// Configure model binder
var commandAuthentications = new List<ICommandAuthentication>
{
    new DefaultCommandAuthentication()
};

builder.Services.AddControllers(options =>
{
    // Register the command interface, not individual classes!
    options.ModelBinderProviders.Insert(0, 
        new RequestCommandModelBinderProvider<IUserCommand>(commandAuthentications));
    options.ModelBinderProviders.Insert(1, 
        new RequestCommandModelBinderProvider<IOrderCommand>(commandAuthentications));
});

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

Best Practices

1. Always register the interface - Not individual command classes

   // ✅ Correct
   new RequestCommandModelBinderProvider<IUserCommand>(auth)
   
   // ❌ Wrong
   new RequestCommandModelBinderProvider<CreateUserCommand>(auth)
   

2. Include $type in JSON - The model binder needs this information

   {
     "$type": "MyApp.Commands.CreateUserCommand, MyApp",
     "username": "john"
   }
   

3. Use pattern matching - For dispatching to the right handlers

   return command switch
   {
       CreateUserCommand cmd => Handle(cmd),
       UpdateUserCommand cmd => Handle(cmd),
       _ => BadRequest()
   };
   

4. Always validate ModelState - Before processing the command

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

5. Authentication is required - Commands require authentication unless [AllowAnonymous] is set

   [AllowAnonymous]
   public class PublicCommand : IUserCommand { }
   

Requirements

• .NET 10.0 or higher
• ASP.NET Core 9.0 or higher
• Dependencies: Newtonsoft.Json, Microsoft.AspNetCore.Mvc.Core

Made with ❤️ for ASP.NET Core developers