Your app starts fine. The first few requests work. Then, hours later, one feature reaches for a setting that was never configured - and throws, deep in a request, far from the real cause.

I've been through this multiple times.

Configuration is just JSON or strings until you validate it.

ASP .NET Core can check your configuration the moment the app starts, so a typo in appsettings.json stops the app right away instead of returning a 500 Internal Error later.

There are two ways to do this: Data Annotations and FluentValidation.

In this post, we will explore:

• Why configuration validation matters
• Validate with Data Annotations
• Fail fast at startup with ValidateOnStart
• Validate with FluentValidation
• Cross-field rules and named options
• Data Annotations vs FluentValidation: when to use each

Let's dive in.

Most apps bind configuration to a strongly typed class with the Options pattern.

Here is a settings class for talking to the GitHub API:

csharp
1public sealed class GitHubSettings
2{
3    public string Token { get; set; } = string.Empty;
4    public string BaseUrl { get; set; } = string.Empty;
5    public int RetryCount { get; set; }
6    public int RetryDelaySeconds { get; set; }
7}

It is bound from appsettings.json:

json
1{
2  "GitHubSettings": {
3    "Token": "ghp_xxx",
4    "BaseUrl": "https://api.github.com",
5    "RetryCount": 3,
6    "RetryDelaySeconds": 2
7  }
8}

csharp
1builder.Services
2    .AddOptions<GitHubSettings>()
3    .Bind(builder.Configuration.GetSection(nameof(GitHubSettings)));

This binds the section, but it does not check anything.

If Token is missing or RetryCount is 0, binding still succeeds - you get an empty string and a zero. The problem only shows up later, when some code actually uses those values.

An empty Token sails through binding and only fails when you make your first GitHub call - as a 401, or a NullReferenceException three layers deep, with nothing pointing back to the real cause: a missing config value.

Validation closes that gap. It turns a silent, half-configured object into an immediate failure.

If the Options pattern is new to you, start with Master Configuration in ASP .NET Core with the Options Pattern.

The quickest way to validate is with Data Annotations - the same attributes you already use on request models.

Add them to the settings class:

csharp
1using System.ComponentModel.DataAnnotations;
2
3public sealed class GitHubSettings
4{
5    [Required]
6    public string Token { get; set; } = string.Empty;
7
8    [Required]
9    [Url]
10    public string BaseUrl { get; set; } = string.Empty;
11
12    [Range(1, 10)]
13    public int RetryCount { get; set; }
14
15    public int RetryDelaySeconds { get; set; }
16}

Then tell the Options builder to validate them with ValidateDataAnnotations:

csharp
1builder.Services
2    .AddOptions<GitHubSettings>()
3    .Bind(builder.Configuration.GetSection(nameof(GitHubSettings)))
4    .ValidateDataAnnotations();

Now [Required] rejects a missing token, [Url] rejects a malformed base URL, and [Range(1, 10)] keeps the retry count sane.

When validation fails, ASP .NET Core throws an OptionsValidationException with a message describing exactly which rule failed.

For a missing token, it looks like this:

1OptionsValidationException: DataAnnotation validation failed for 'GitHubSettings' members:
2'Token' with the error: 'The Token field is required.'

There is one catch: by default, that exception is not thrown until something first resolves IOptions<GitHubSettings>. Let's fix that next.

By default, the Options system validates the first time the configuration is resolved - which might be on the first request that needs it, or much later. You want the opposite: a bad configuration should stop the app from starting at all.

ValidateOnStart does that. Chain it onto the builder:

csharp
1builder.Services
2    .AddOptions<GitHubSettings>()
3    .Bind(builder.Configuration.GetSection(nameof(GitHubSettings)))
4    .ValidateDataAnnotations()
5    .ValidateOnStart();

Now validation runs during application startup. If the configuration is invalid, the host throws an OptionsValidationException and the app refuses to start.

This is exactly what you want: a broken deployment fails immediately and visibly during application startup.

Note: ValidateOnStart is the single most valuable line here. Always add it. Catching a configuration mistake at startup makes a real difference between a failed deploy and a runtime incident.

Data Annotations are fine for simple, per-property checks. But they have limits.

They scatter validation rules across your settings class as attributes, they cannot express rules that span several properties, and complex conditions get awkward fast. And if you already use FluentValidation in your project, you will want your configuration validated the same way.

First, install the packages:

bash
1dotnet add package FluentValidation
2dotnet add package FluentValidation.DependencyInjectionExtensions

Write a validator for the settings class - the same AbstractValidator<T> you use everywhere else:

csharp
1using FluentValidation;
2
3public sealed class GitHubSettingsValidator : AbstractValidator<GitHubSettings>
4{
5    public GitHubSettingsValidator()
6    {
7        RuleFor(x => x.Token).NotEmpty();
8
9        RuleFor(x => x.BaseUrl)
10            .NotEmpty()
11            .Must(url => Uri.TryCreate(url, UriKind.Absolute, out _))
12            .WithMessage("BaseUrl must be a valid absolute URL.");
13
14        RuleFor(x => x.RetryCount).InclusiveBetween(1, 10);
15    }
16}

Here is the gap: FluentValidation has no built-in support for the Options pattern.

The Options system validates through the IValidateOptions<TOptions> interface, and FluentValidation does not implement it. So we provide a small, reusable bridge that runs any FluentValidation validator as an Options validator:

csharp
1using FluentValidation;
2using Microsoft.Extensions.Options;
3
4namespace Configuration.Validation;
5
6public class FluentValidateOptions<TOptions> : IValidateOptions<TOptions>
7    where TOptions : class
8{
9    private readonly IServiceProvider _serviceProvider;
10    private readonly string? _name;
11
12    public FluentValidateOptions(IServiceProvider serviceProvider, string? name)
13    {
14        _serviceProvider = serviceProvider;
15        _name = name;
16    }
17
18    public ValidateOptionsResult Validate(string? name, TOptions options)
19    {
20        if (_name is not null && _name != name)
21        {
22            return ValidateOptionsResult.Skip;
23        }
24
25        ArgumentNullException.ThrowIfNull(options);
26
27        using var scope = _serviceProvider.CreateScope();
28
29        var validator = scope.ServiceProvider.GetRequiredService<IValidator<TOptions>>();
30
31        var result = validator.Validate(options);
32        if (result.IsValid)
33        {
34            return ValidateOptionsResult.Success;
35        }
36
37        var type = options.GetType().Name;
38        var errors = new List<string>();
39        foreach (var failure in result.Errors)
40        {
41            errors.Add($"Validation failed for {type}.{failure.PropertyName} " +
42                $"with the error: {failure.ErrorMessage}");
43        }
44
45        return ValidateOptionsResult.Fail(errors);
46    }
47}

A few things make this work:

• It implements IValidateOptions<TOptions>, the hook the Options system calls.
• IValidateOptions is registered as a singleton, but FluentValidation validators are usually scoped - so we open a scope with _serviceProvider.CreateScope() and resolve IValidator<TOptions> from it. Resolving a scoped service straight into a singleton would throw.
• The _name check returns ValidateOptionsResult.Skip for named options that do not match, which we will use shortly.

Now wrap it in an extension method, so registering it reads cleanly:

csharp
1public static class OptionsBuilderExtensions
2{
3    public static OptionsBuilder<TOptions> ValidateFluentValidation<TOptions>(
4        this OptionsBuilder<TOptions> builder)
5        where TOptions : class
6    {
7        builder.Services.AddSingleton<IValidateOptions<TOptions>>(
8            serviceProvider => new FluentValidateOptions<TOptions>(
9                serviceProvider,
10                builder.Name));
11
12        return builder;
13    }
14}

Finally, register the validator itself and enable validation. This is the step that is easy to forget - without it, the IValidator<GitHubSettings> resolve inside the bridge fails:

csharp
1builder.Services.AddValidatorsFromAssemblyContaining<GitHubSettingsValidator>();
2
3builder.Services
4    .AddOptions<GitHubSettings>()
5    .Bind(builder.Configuration.GetSection(nameof(GitHubSettings)))
6    .ValidateFluentValidation()
7    .ValidateOnStart();

AddValidatorsFromAssemblyContaining scans the assembly and registers every validator, including GitHubSettingsValidator.

ValidateFluentValidation plugs the bridge in, and ValidateOnStart runs it at startup - so the same fail-fast behavior you got from Data Annotations now applies to your FluentValidation rules.

Now, an invalid configuration fails at boot with the message your bridge is formatted:

1OptionsValidationException: Validation failed for GitHubSettings.Token
2with the error: 'Token' must not be empty.

Note: validation runs against the final bound object, so it works the same no matter where the values come from - appsettings.json, environment variables, or a secret store like Azure Key Vault.

This is where FluentValidation earns its place.

A rule that depends on more than one property is hard to express with attributes but trivial in a validator. Say RetryDelaySeconds only matters when retries are enabled - add this rule to the validator:

csharp
1RuleFor(x => x.RetryDelaySeconds)
2    .GreaterThan(0)
3    .When(x => x.RetryCount > 1);

The delay must be positive, but only when RetryCount is greater than 1. There is no clean way to write that with Data Annotations.

The bridge also supports named options.

If you register the same settings type more than once under different names, each gets its own configuration and its own validation:

csharp
1builder.Services
2    .AddOptions<GitHubSettings>("Primary")
3    .Bind(builder.Configuration.GetSection("GitHub:Primary"))
4    .ValidateFluentValidation()
5    .ValidateOnStart();

Because FluentValidateOptions captures the builder's name and compares it in Validate, returning ValidateOptionsResult.Skip when the names do not match, each named instance is validated independently.

One reusable bridge covers every setting type and every name.

Both approaches fail fast at startup. The difference lies in how the rules are written and how far they stretch.

Use Data Annotations when the rules are simple per-property checks and you want zero extra setup.

Use FluentValidation when rules span multiple properties, depend on conditions, or when your project already standardizes on it - so configuration is validated the same way as everything else.

One more advantage: a validator is a plain class, so you can unit-test your configuration rules directly, with no host or DI container:

csharp
1var validator = new GitHubSettingsValidator();
2
3var result = validator.TestValidate(new GitHubSettings { Token = "" });
4
5result.ShouldHaveValidationErrorFor(x => x.Token);

Note: you do not have to choose globally. Validate simple settings with attributes and complex ones with FluentValidation, in the same app.

For a deeper tour of FluentValidation itself, see The Best Way to Validate Objects in .NET.

Let's recap the key takeaways:

• Validate your configuration. Binding succeeds even when values are missing or out of range - validation is what turns a half-configured object into an immediate, clear error.
• Fail fast with ValidateOnStart. It moves validation to application startup, so a bad deploy stops at startup instead of failing later in production. Always add it.
• Use Data Annotations for simple rules. [Required], [Url], and [Range] plus ValidateDataAnnotations cover most per-property checks with no setup.
• Use FluentValidation for complex rules. The reusable FluentValidateOptions<T> bridge runs any validator as an options validator, and handles cross-field rules, conditions, and named options.

Bad configuration is one of the most common ways a deployment breaks. Validating it at startup takes a few lines of code and pays for itself the first time it prevents a broken config from reaching production.

Hope you find this newsletter useful. See you next time.