FluentValidation in ASP.NET Core: A Complete Guide

Imagine you're building a REST API for an e-commerce platform. Users submit orders with items, quantities, and shipping addresses. Without proper validation, you could end up with negative quantities, empty addresses, or malicious input that crashes your system. Traditional validation using data annotations works for simple cases but quickly becomes messy for complex rules like 'If the order total exceeds $1000, require manager approval' or 'Shipping address must be valid for the selected country'. Enter FluentValidation: a powerful, open-source library that lets you define validation rules in a fluent, readable way. It integrates deeply with ASP.NET Core, automatically validating incoming requests and returning structured error responses. In this tutorial, you'll learn how to set up FluentValidation, write custom rules, handle complex scenarios, and debug validation issues in production. By the end, you'll be able to replace messy if-else chains with clean, testable validator classes.

Setting Up FluentValidation in ASP.NET Core

To get started, install the FluentValidation.AspNetCore NuGet package. This package integrates FluentValidation with ASP.NET Core's validation pipeline. In your Startup.cs (or Program.cs for .NET 6+), add the following configuration:

```csharp // In ConfigureServices services.AddControllers() .AddFluentValidationAutoValidation() .AddFluentValidationClientsideAdapters(); // optional for client-side

// Register validators from the assembly containing your validator services.AddValidatorsFromAssemblyContaining<CreateOrderValidator>(); ```

This automatically validates incoming requests using the registered validators. If validation fails, the API returns a 400 Bad Request with a ValidationProblemDetails response. You can customize the error response by configuring the FluentValidation options.

Now, create a validator class for your model. For example, for an Order model:

``csharp public class CreateOrderValidator : AbstractValidator<CreateOrderRequest> { public CreateOrderValidator() { RuleFor(x => x.CustomerName).NotEmpty().MaximumLength(100); RuleFor(x => x.Email).NotEmpty().EmailAddress(); RuleFor(x => x.TotalAmount).GreaterThan(0); } } ``

That's it! Now every time a CreateOrderRequest is received, FluentValidation will run these rules automatically.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
            .AddFluentValidationAutoValidation()
            .AddFluentValidationClientsideAdapters();
    services.AddValidatorsFromAssemblyContaining<CreateOrderValidator>();
}

Writing Complex Validation Rules

FluentValidation supports a wide range of built-in validators like NotEmpty, GreaterThan, EmailAddress, etc. But real-world scenarios often require custom logic. For example, you might need to validate that a discount code is valid only if the order total exceeds a certain amount.

Use the Must method to define custom validation logic:

``csharp RuleFor(x => x.DiscountCode) .Must((model, discountCode) => { if (string.IsNullOrEmpty(discountCode)) return true; // optional return model.TotalAmount > 100 && IsValidDiscount(discountCode); }) .WithMessage("Discount code is only valid for orders over $100."); ``

For cross-property validation, use RuleFor with Must that takes the entire model:

``csharp RuleFor(x => x.ShippingAddress) .Must((model, address) => { if (model.ShippingMethod == "express" && string.IsNullOrEmpty(address.Phone)) return false; return true; }) .WithMessage("Phone number is required for express shipping."); ``

You can also create custom validators by inheriting from AbstractValidator and using Include to compose validators.

For conditional rules, use When and Unless:

``csharp RuleFor(x => x.ManagerEmail) .NotEmpty() .When(x => x.TotalAmount > 1000) .WithMessage("Manager approval required for orders over $1000."); ``

public class OrderValidator : AbstractValidator<Order>
{
    public OrderValidator()
    {
        RuleFor(x => x.TotalAmount).GreaterThan(0);
        RuleFor(x => x.DiscountCode)
            .Must((model, code) =>
            {
                if (string.IsNullOrEmpty(code)) return true;
                return model.TotalAmount > 100 && IsValid(code);
            })
            .WithMessage("Discount code invalid or not applicable.");
        RuleFor(x => x.ManagerEmail)
            .NotEmpty()
            .When(x => x.TotalAmount > 1000);
    }
    private bool IsValid(string code) => code == "SAVE10";
}

Async Validation and Dependency Injection

Sometimes validation requires async operations, like checking if an email already exists in the database. FluentValidation supports async rules via MustAsync.

First, inject a service into your validator:

``csharp public class CreateUserValidator : AbstractValidator<CreateUserRequest> { private readonly IUserRepository _userRepo; public CreateUserValidator(IUserRepository userRepo) { _userRepo = userRepo; RuleFor(x => x.Email) .MustAsync(async (email, cancellation) => { return !await _userRepo.EmailExistsAsync(email); }) .WithMessage("Email already in use."); } } ``

Make sure your validator is registered in DI. Since we used AddValidatorsFromAssemblyContaining, it will be automatically registered. If you need to manually register, use services.AddTransient<IValidator<CreateUserRequest>, CreateUserValidator>().

Async validation integrates seamlessly with the pipeline. If the async rule throws an exception, it will be caught and returned as a validation error.

Note: Async validation is not supported for client-side adapters. If you need client-side validation, consider using a separate sync rule.

public class CreateUserValidator : AbstractValidator<CreateUserRequest>
{
    private readonly IUserRepository _userRepo;
    public CreateUserValidator(IUserRepository userRepo)
    {
        _userRepo = userRepo;
        RuleFor(x => x.Email)
            .NotEmpty()
            .EmailAddress()
            .MustAsync(async (email, ct) => !await _userRepo.EmailExistsAsync(email))
            .WithMessage("Email already registered.");
    }
}

Customizing Error Responses

By default, FluentValidation returns errors in the standard ASP.NET Core ValidationProblemDetails format. However, you might want to customize the response structure to match your API conventions.

To customize, configure the FluentValidationAutoValidation options:

``csharp services.AddFluentValidationAutoValidation(config => { config.DisableDataAnnotationsValidation = true; // optional config.ValidatorOptions = options => { options.ErrorResponseBuilder = (context) => { var errors = context.Errors .GroupBy(e => e.PropertyName) .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray()); return new { success = false, errors }; }; }; }); ``

You can also set the language for error messages globally:

``csharp ValidatorOptions.Global.LanguageManager = new LanguageManager { Culture = new CultureInfo("en") }; ``

For per-validator customization, use WithMessage and WithErrorCode.

If you need to return a completely different response, you can also implement a custom IValidationFailureFactory.

builder.Services.AddFluentValidationAutoValidation(config =>
{
    config.DisableDataAnnotationsValidation = true;
    config.ValidatorOptions = options =>
    {
        options.ErrorResponseBuilder = (context) =>
        {
            var errors = context.Errors
                .GroupBy(e => e.PropertyName)
                .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray());
            return new { success = false, errors };
        };
    };
});

Testing Validators

One of the biggest advantages of FluentValidation is testability. Validators are plain classes that can be unit tested easily.

Use a testing framework like xUnit and Moq to mock dependencies. For example:

```csharp [Fact] public async Task EmailAlreadyExists_ReturnsValidationError() { // Arrange var userRepo = new Mock<IUserRepository>(); userRepo.Setup(x => x.EmailExistsAsync("test@test.com", It.IsAny<CancellationToken>())) .ReturnsAsync(true); var validator = new CreateUserValidator(userRepo.Object); var request = new CreateUserRequest { Email = "test@test.com" };

// Act var result = await validator.ValidateAsync(request);

// Assert Assert.False(result.IsValid); Assert.Contains(result.Errors, e => e.PropertyName == "Email"); } ```

You can also test complex rules by setting up the model with various states. FluentValidation's TestValidate extension method (from FluentValidation.TestHelper) provides a fluent way to assert specific errors:

``csharp var result = validator.TestValidate(request); result.ShouldHaveValidationErrorFor(x => x.Email); result.ShouldNotHaveValidationErrorFor(x => x.Name); ``

Install the FluentValidation.TestHelper NuGet package to use these extensions.

using FluentValidation.TestHelper;

public class CreateUserValidatorTests
{
    [Fact]
    public void Should_Have_Error_When_Email_Is_Empty()
    {
        var validator = new CreateUserValidator(Mock.Of<IUserRepository>());
        var model = new CreateUserRequest { Email = "" };
        var result = validator.TestValidate(model);
        result.ShouldHaveValidationErrorFor(x => x.Email);
    }

    [Fact]
    public async Task Should_Have_Error_When_Email_Exists()
    {
        var userRepo = new Mock<IUserRepository>();
        userRepo.Setup(x => x.EmailExistsAsync("existing@test.com", default))
                .ReturnsAsync(true);
        var validator = new CreateUserValidator(userRepo.Object);
        var model = new CreateUserRequest { Email = "existing@test.com" };
        var result = await validator.ValidateAsync(model);
        Assert.False(result.IsValid);
    }
}

Performance Considerations and Best Practices

FluentValidation is designed to be fast, but there are pitfalls that can degrade performance in production.

1. Avoid synchronous I/O in Must: If you need to call a database, use MustAsync instead. Synchronous calls block the thread and can cause thread pool starvation.
2. Cache expensive lookups: If multiple rules need the same data (e.g., user roles), fetch it once and pass it to the validator via DI or a scoped service.
3. Use RuleForEach for collections: When validating lists, use RuleForEach(x => x.Items).SetValidator(new ItemValidator()) to avoid redundant code.
4. Limit complexity: Keep validators focused on a single model. For very complex models, consider splitting into sub-validators using Include.
5. Disable Data Annotations if using FluentValidation exclusively: Set DisableDataAnnotationsValidation = true to avoid running both validation systems.
6. Use CascadeMode to stop on first failure: Set CascadeMode = CascadeMode.Stop on the validator to short-circuit validation after the first error for a property.

Example:

``csharp public class OrderValidator : AbstractValidator<Order> { public OrderValidator() { CascadeMode = CascadeMode.Stop; RuleFor(x => x.CustomerName).NotEmpty().MaximumLength(100); // If CustomerName fails, subsequent rules for CustomerName won't run } } ``

public class OrderValidator : AbstractValidator<Order>
{
    public OrderValidator()
    {
        CascadeMode = CascadeMode.Stop;
        RuleFor(x => x.CustomerName).NotEmpty().MaximumLength(100);
        RuleFor(x => x.Email).NotEmpty().EmailAddress();
        RuleForEach(x => x.Items).SetValidator(new OrderItemValidator());
    }
}