在启动期间验证 ASP.NET Core 选项

Question

Core2 has a hook for validating options read from appsettings.json :

services.PostConfigure<MyConfig>(options => {
  // do some validation
  // maybe throw exception if appsettings.json has invalid data
});

This validation code triggers on first use of MyConfig , and every time after that. So I get multiple runtime errors.

However it is more sensible to run validation during startup - if config validation fails I want the app to fail immediately. The docs imply that is how it works, but that is not what happens.

So am I doing it right? If so and this is by design, then how can I change what I'm doing so it works the way I want?

(Also, what is the difference between PostConfigure and PostConfigureAll ? There is no difference in this case, so when should I use either one?)

Answer 1

There is no real way to run a configuration validation during startup. As you already noticed, post configure actions run, just like normal configure actions, lazily when the options object is being requested. This completely by design, and allows for many important features, for example reloading configuration during run-time or also options cache invalidation.

What the post configuration action is usually being used for is not a validation in terms of “if there's something wrong, then throw an exception” , but rather “if there's something wrong, fall back to sane defaults and make it work” .

For example, there's a post configuration step in the authentication stack, that makes sure that there's always a SignInScheme set for remote authentication handlers:

options.SignInScheme = options.SignInScheme ?? _authOptions.DefaultSignInScheme ?? _authOptions.DefaultScheme;

As you can see, this will not fail but rather just provides multiple fallbacks.

In this sense, it's also important to remember that options and configuration are actually two separate things. It's just that the configuration is a commonly used source for configuring options. So one might argue that it is not actually the job of the options to validate that the configuration is correct.

As such it might make more sense to actually check the configuration in the Startup, before configuring the options. Something like this:

var myOptionsConfiguration = Configuration.GetSection("MyOptions");

if (string.IsNullOrEmpty(myOptionsConfiguration["Url"]))
    throw new Exception("MyOptions:Url is a required configuration");

services.Configure<MyOptions>(myOptionsConfiguration);

Of course this easily becomes very excessive, and will likely force you to bind/parse many properties manually. It will also ignore the configuration chaining that the options pattern supports (ie configuring a single options object with multiple sources/actions).

So what you could do here is keep your post configuration action for validation, and simply trigger the validation during startup by actually requesting the options object. For example, you could simply add IOptions<MyOptions> as a dependency to the Startup.Configure method:

public void Configure(IApplicationBuilder app, IOptions<MyOptions> myOptions)
{
    // all configuration and post configuration actions automatically run

    // …
}

If you have multiple of these options, you could even move this into a separate type:

public class OptionsValidator
{
    public OptionsValidator(IOptions<MyOptions> myOptions, IOptions<OtherOptions> otherOptions)
    { }
}

At that time, you could also move the logic from the post configuration action into that OptionsValidator . So you could trigger the validation explicitly as part of the application startup:

public void Configure(IApplicationBuilder app, OptionsValidator optionsValidator)
{
    optionsValidator.Validate();

    // …
}

As you can see, there's no single answer for this. You should think about your requirements and see what makes the most sense for your case. And of course, this whole validation only makes sense for certain configurations. In particular, you will have difficulties when working configurations that will change during run-time (you could make this work with a custom options monitor, but it's probably not worth the hassle). But as most own applications usually just use cached IOptions<T> , you likely don't need that.

---

As for PostConfigure and PostConfigureAll , they both register an IPostConfigure<TOptions> . The difference is simply that the former will only match a single named option (by default the unnamed option—if you don't care about option names), while PostConfigureAll will run for all names.

Named options are for example used for the authentication stack, where each authentication method is identified by its scheme name. So you could for example add multiple OAuth handlers and use PostConfigure("oauth-a", …) to configure one and PostConfigure("oauth-b", …) to configure the other, or use PostConfigureAll(…) to configure them both.

Answer 2

On an ASP.NET Core 2.2 project I got this working doing eager validation by following these steps...

Given an Options class like this one:

public class CredCycleOptions
{
    [Range(1753, int.MaxValue, ErrorMessage = "Please enter a valid integer Number.")]
    public int VerifiedMinYear { get; set; }
    [Range(1753, int.MaxValue, ErrorMessage = "Please enter a valid integer Number.")]
    public int SignedMinYear { get; set; }
    [Range(1753, int.MaxValue, ErrorMessage = "Please enter a valid integer Number.")]
    public int SentMinYear { get; set; }
    [Range(1753, int.MaxValue, ErrorMessage = "Please enter a valid integer Number.")]
    public int ConfirmedMinYear { get; set; }
}

In Startup.cs add these lines to ConfigureServices method:

services.AddOptions();

// This will validate Eagerly...
services.ConfigureAndValidate<CredCycleOptions>("CredCycle", Configuration);

ConfigureAndValidate is an extension method from here .

public static class OptionsExtensions
{
    private static void ValidateByDataAnnotation(object instance, string sectionName)
    {
        var validationResults = new List<ValidationResult>();
        var context = new ValidationContext(instance);
        var valid = Validator.TryValidateObject(instance, context, validationResults);

        if (valid)
            return;

        var msg = string.Join("\n", validationResults.Select(r => r.ErrorMessage));

        throw new Exception($"Invalid configuration for section '{sectionName}':\n{msg}");
    }

    public static OptionsBuilder<TOptions> ValidateByDataAnnotation<TOptions>(
        this OptionsBuilder<TOptions> builder,
        string sectionName)
        where TOptions : class
    {
        return builder.PostConfigure(x => ValidateByDataAnnotation(x, sectionName));
    }

    public static IServiceCollection ConfigureAndValidate<TOptions>(
        this IServiceCollection services,
        string sectionName,
        IConfiguration configuration)
        where TOptions : class
    {
        var section = configuration.GetSection(sectionName);

        services
            .AddOptions<TOptions>()
            .Bind(section)
            .ValidateByDataAnnotation(sectionName)
            .ValidateEagerly();

        return services;
    }

    public static OptionsBuilder<TOptions> ValidateEagerly<TOptions>(this OptionsBuilder<TOptions> optionsBuilder) where TOptions : class
    {
        optionsBuilder.Services.AddTransient<IStartupFilter, StartupOptionsValidation<TOptions>>();

        return optionsBuilder;
    }
}

I plumbed ValidateEargerly extension method right inside ConfigureAndValidate . It makes use of this other class from here :

public class StartupOptionsValidation<T> : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
    {
        return builder =>
        {
            var options = builder.ApplicationServices.GetService(typeof(IOptions<>).MakeGenericType(typeof(T)));

            if (options != null)
            {
                // Retrieve the value to trigger validation
                var optionsValue = ((IOptions<object>)options).Value;
            }

            next(builder);
        };
    }
}

This allows us to add data annotations to the CredCycleOptions and get nice error feedback right at the moment the app starts making it an ideal solution.

If an option is missing or have a wrong value, we don't want users to catch these errors at runtime. That would be a bad experience.

Answer 3

This NuGet package provides a ConfigureAndValidate<TOptions> extension method which validates options at startup using an IStartupFilter .

It is based on based on Microsoft.Extensions.Options.DataAnnotations. But unlike Microsoft's package, it can even validate nested properties. It is compatible with .NET Core 3.1 and .NET 5.

Documentation & source code (GitHub)

TL;DR

1. Create your options class(es)
2. Decorate your options with data annotations
3. Call ConfigureAndValidate<T>(Action<T> configureOptions) on your IServiceCollection

ConfigureAndValidate will configure your options (calling the base Configure method), but will also check that the built configuration respects the data annotations, otherwise an OptionsValidationException (with details) is thrown as soon as the application is started. No misconfiguration surprise at runtime!

Use

ServiceCollection extension

services.ConfigureAndValidate<TOptions>(configureOptions)

Is syntactic sugar for

services
    .AddOptions<TOptions>()
        .Configure(configureOptions) // Microsoft
        .ValidateDataAnnotationsRecursively() // Based on Microsoft's ValidateDataAnnotations, but supports nested properties
        .ValidateEagerly() // Validate on startup
        .Services

OptionsBuilder extensions

ValidateDataAnnotationsRecursively

This method register this options instance for validation of its DataAnnotations at the first dependency injection. Nested objects are supported.

ValidateEagerly

This method validates this options instance at application startup rather than at the first dependency injection.

Custom validation

You can combine with your own option validations:

services
    .AddOptions<TOptions>()
        .Configure(configureOptions)
        //...
        .Validate(options => { /* custom */ }, message)
        .Validate<TDependency1, TDependency2>((options, dependency1, dependency2) =>
            { 
                // custom validation
            },
            "Custom error message")
        //...
        .ValidateDataAnnotationsRecursively()
        .ValidateEagerly()

Microsoft options validation documentation

Answer 4

There are easy way to validating with using IStartupFilter and IValidateOptions .

You can just put below code your ASP.NET Core project.

public static class OptionsBuilderExtensions
{
    public static OptionsBuilder<TOptions> ValidateOnStartupTime<TOptions>(this OptionsBuilder<TOptions> builder)
        where TOptions : class
    {
        builder.Services.AddTransient<IStartupFilter, OptionsValidateFilter<TOptions>>();
        return builder;
    }
    
    public class OptionsValidateFilter<TOptions> : IStartupFilter where TOptions : class
    {
        private readonly IOptions<TOptions> _options;

        public OptionsValidateFilter(IOptions<TOptions> options)
        {
            _options = options;
        }

        public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
        {
            _ = _options.Value; // Trigger for validating options.
            return next;
        }
    }
}

And just chain the ValidateOnStartup method on OptionsBuilder<TOptions> .

services.AddOptions<SampleOption>()
    .Bind(Configuration)
    .ValidateDataAnnotations()
    .ValidateOnStartupTime();

If you want to create custom validator for options class. checkout below article.

https://docs.microsoft.com/ko-kr/aspnet/core/fundamentals/configuration/options?view=aspnetcore-5.0#ivalidateoptions-for-complex-validation

Answer 5

Below is a generic ConfigureAndValidate method to validate immediately and "fail fast".

To summarize the steps:

1. Call serviceCollection.Configure for your options
2. Do serviceCollection.BuildServiceProvider().CreateScope()
3. Get the options instance with scope.ServiceProvider.GetRequiredService<IOptions<T>> (remember to take the .Value )
4. Validate it using Validator.TryValidateObject

public static class ConfigExtensions
{
    public static void ConfigureAndValidate<T>(this IServiceCollection serviceCollection, Action<T> configureOptions) where T : class, new()
    {
        // Inspired by https://blog.bredvid.no/validating-configuration-in-asp-net-core-e9825bd15f10
        serviceCollection.Configure(configureOptions);

        using (var scope = serviceCollection.BuildServiceProvider().CreateScope())
        {
            var options = scope.ServiceProvider.GetRequiredService<IOptions<T>>();
            var optionsValue = options.Value;
            var configErrors = ValidationErrors(optionsValue).ToArray();
            if (!configErrors.Any())
            {
                return;
            }

            var aggregatedErrors = string.Join(",", configErrors);
            var count = configErrors.Length;
            var configType = typeof(T).FullName;
            throw new ApplicationException($"{configType} configuration has {count} error(s): {aggregatedErrors}");
        }
    }

    private static IEnumerable<string> ValidationErrors(object obj)
    {
        var context = new ValidationContext(obj, serviceProvider: null, items: null);
        var results = new List<ValidationResult>();
        Validator.TryValidateObject(obj, context, results, true);
        foreach (var validationResult in results)
        {
            yield return validationResult.ErrorMessage;
        }
    }
}

Answer 6

This has been implemented in .NET 6. Now you can just write the following:

services.AddOptions<SampleOption>()
  .Bind(Configuration)
  .ValidateDataAnnotations()
  .ValidateOnStart(); // works in .NET 6

No need for external NuGet Packages or extra code.

See OptionsBuilderExtensions.ValidateOnStart