📌 What is AspNetCore.Scalar?

AspNetCore.Scalar is a lightweight, extensible, and highly-focused library for ASP.NET Core applications that simplifies model binding, input validation, and data sanitization at the property level.

It introduces the concept of “Scalars”, which are strongly-typed wrappers around primitive data types like strings, integers, booleans, etc., adding value like automatic validation, normalization, and rich error handling — all without cluttering your core domain models.

In simple terms:

AspNetCore.Scalar helps you validate and normalize user input early, safely, and elegantly in your ASP.NET Core Web APIs and MVC apps.

Instead of spreading validation logic across your controllers, services, or view models, Scalar centralizes and automates it, keeping your application clean, secure, and easy to maintain.

📌 Major Use Cases of AspNetCore.Scalar

You can use AspNetCore.Scalar in a wide range of modern ASP.NET Core application scenarios:

• Web API Input Validation
  Validate user-provided API request fields (e.g., email addresses, usernames, phone numbers) early during model binding.
• Sanitize User Input
  Normalize or clean up raw data inputs like trimming whitespaces, enforcing case rules (lowercase, uppercase), or formatting numbers before they hit your application logic.
• Microservices Input Contracts
  Enforce strict input contracts between services by making sure incoming data follows expected formats and constraints.
• Security Hardening
  Prevent injection attacks and other input-related vulnerabilities by validating and sanitizing at the first point of entry.
• Domain-Driven Design (DDD)
  Encapsulate validation rules inside value objects without bloating the domain entities.
• Developer Productivity
  Reduce repetitive validation code and avoid cluttering controllers and DTOs with manual if-else checks.
• Error Reporting
  Provide clear and structured error messages on invalid user input automatically.

Overall, AspNetCore.Scalar is ideal for any project where input validation, data quality, and code maintainability are top priorities.

📌 How AspNetCore.Scalar Works (Architecture Overview)

AspNetCore.Scalar operates through a simple but powerful architectural flow:

🔹 Core Components:

• Scalar Types
  Custom classes that wrap a primitive type (like Email, PhoneNumber, Username).
• Scalar Model Binders
  Intercept incoming HTTP request data during the ASP.NET Core model binding pipeline and instantiate scalar types automatically.
• Scalar Validators
  Run predefined or custom validation rules (length checks, format validation, etc.) on the bound input data.
• Scalar Normalizers
  Optionally sanitize/transform input (e.g., trimming spaces, converting to lowercase).
• Integration with ModelState
  Scalar errors are pushed automatically into ModelState for seamless error reporting in APIs or MVC views.

🛠️ Internal Workflow:

1. Request data (query, body, route) arrives.
2. Model binding detects scalar types.
3. Scalars validate and normalize the data.
4. If validation passes, the scalar is injected into the controller action.
5. If validation fails, errors are added to ModelState, and appropriate HTTP 400 responses are generated.

This tight integration allows input processing before your application logic sees any data — keeping your business layer pure and safe.

📌 Basic Workflow of AspNetCore.Scalar

Here’s how a typical AspNetCore.Scalar interaction looks like:

1. Define a Scalar Class
   Create a strongly typed wrapper for a specific kind of input (like EmailAddress, Username).
2. Configure Scalar Bindings
   Register scalar types into the ASP.NET Core dependency injection system.
3. Bind Scalars in Controllers
   Use scalar types as parameters in API or MVC controller actions.
4. Validation and Normalization Happen Automatically
   Scalars validate incoming user input at the model-binding stage.
5. Handle Errors
   If input fails validation, ASP.NET Core automatically returns an error response, or you can customize the response.
6. Use Validated Data
   Valid scalar values are available in controller methods for further business processing.

📌 Step-by-Step Getting Started Guide for AspNetCore.Scalar

Here’s how you can easily get started:

1️⃣ Install AspNetCore.Scalar

You can install via NuGet:

dotnet add package AspNetCore.Scalar

Or in Visual Studio, search for AspNetCore.Scalar in the NuGet package manager.

2️⃣ Create Your First Scalar

using Scalar;

public class Email : ScalarOf<string>
{
    public Email(string value) : base(value) {}

    protected override void Validate()
    {
        if (string.IsNullOrWhiteSpace(Value))
            throw new ScalarValidationException("Email is required.");

        if (!Value.Contains("@"))
            throw new ScalarValidationException("Email must contain @ symbol.");
    }

    protected override string Normalize(string value)
    {
        return value.Trim().ToLower();
    }
}

3️⃣ Register Scalars in Startup

In your Program.cs or Startup.cs, register scalar model binding:

builder.Services.AddScalarModelBinder();

4️⃣ Use Scalars in Controller Actions

[ApiController]
[Route("[controller]")]
public class UsersController : ControllerBase
{
    [HttpPost]
    public IActionResult Register([FromBody] Email email)
    {
        // If this point is reached, email is already validated
        return Ok($"Registered user with email: {email.Value}");
    }
}

5️⃣ Customize Error Responses (Optional)

Customize model state error behavior:

builder.Services.Configure<ApiBehaviorOptions>(options =>
{
    options.InvalidModelStateResponseFactory = context =>
    {
        var errors = context.ModelState.Values
                       .SelectMany(x => x.Errors)
                       .Select(x => x.ErrorMessage);
        return new BadRequestObjectResult(new { Errors = errors });
    };
});

The post AspNetCore.Scalar Explained: Modern Input Validation and Binding for .NET Web Apps appeared first on scmGalaxy.