ASP.NET Core - make sure IOptions<T> is initialized

1. Introduction#

As most people know IOptions<T> is a convenient way of handling configuration options in your application. Even though I’ve been using it for quite some time, last week I was unpleasantly surprised by a production bug caused by wrong usage of this mechanism.

2. Problem#

Let’s say we have a simple controller which depends on two instances of IOptions<T>

1
[Route("api/[controller]")]
2
public class ValuesController : Controller
3
{
4
    private readonly IOptions<PaymentOptions> _paymentOptions;
5
    private readonly IOptions<NotificationOptions> _notificationOptions;
6

7
    public ValuesController(IOptions<PaymentOptions> paymentOptions, IOptions<NotificationOptions> notificationOptions)
8
    {
9
        _paymentOptions = paymentOptions ?? throw new ArgumentNullException(nameof(paymentOptions));
10
        _notificationOptions = notificationOptions ?? throw new ArgumentNullException(nameof(notificationOptions));
11
    }
12

13
    // GET api/values
14
    [HttpGet]
15
    public IEnumerable<string> Get()
16
    {
17
        var notificationOptions = _notificationOptions.Value;
18
        var paymentOptions = _paymentOptions.Value;
19

20
        return new string[] {"value1", "value2"};
21
    }
22
}

Then we add only IOptions in Startup class - IOptions<PaymentOptoins>

1
public class Startup
2
{
3
    // Rest of the code omitted for brevity
4
    // This method gets called by the runtime. Use this method to add services to the container.
5
    public void ConfigureServices(IServiceCollection services)
6
    {
7
        services.AddOptions();
8
        services.AddMvc();
9
        services.Configure<PaymentOptions>(Configuration.GetSection("PaymentOptions"));
10
    }
11
      // Rest of the code omitted for brevity
12
}

Now, when we run the app and hit one of the endpoints in ValuesController I was expecting to get an exception, as I didn’t register IOptions<NotificationOptions>. Surprisingly for me, the application was running normally and IOptions<NotificationOptions> was created with the new instance of NotificationOptions class(with all the properties defaulted).

In order to find out why it behaves like that we have to take a look how services responsible for handling IOptions<T> are registered in the container.

1
public static IServiceCollection AddOptions(this IServiceCollection services)
2
{
3
    if (services == null)
4
        throw new ArgumentNullException(nameof (services));
5

6
    services.TryAdd(ServiceDescriptor.Singleton(typeof (IOptions<>), typeof (OptionsManager<>)));
7
    services.TryAdd(ServiceDescriptor.Scoped(typeof (IOptionsSnapshot<>), typeof (OptionsManager<>)));
8
    services.TryAdd(ServiceDescriptor.Singleton(typeof (IOptionsMonitor<>), typeof (OptionsMonitor<>)));
9
    services.TryAdd(ServiceDescriptor.Transient(typeof (IOptionsFactory<>), typeof (OptionsFactory<>)));
10
    services.TryAdd(ServiceDescriptor.Singleton(typeof (IOptionsMonitorCache<>), typeof (OptionsCache<>)));
11
    return services;
12
}

As you can see AddOptions method registers open generics for (among others) IOptions<> which means that you don’t have to register specific types of IOptions<T>, however, you are responsible for its configuration with

1
services.Configure<T>(Configuration.GetSection("Section"));

I was always convinced that services.Configure registers and configure IOptions<T> but apparently, I was wrong.

3. Ensuring initialization#

As these kind of errors are rather difficult to catch(at least in case of our application) I wanted to minimize the risk of doing the same bug again. The idea was to make sure that at least one IConfigureOptions<T> or IPostConfigureOptions<T> service is registered in the container (as these are the services which are responsible for setting the values of T class). My first approach was to replace default OptionsFactory<T> with a custom one

1
public class ValidatableOptionsFactory<TOptions> : OptionsFactory<TOptions> where TOptions : class, new()
2
{
3
    private static readonly string NamespacePrefix = typeof(Program).Namespace.Split('.').First();
4

5
    public ValidatableOptionsFactory(IEnumerable<IConfigureOptions<TOptions>> setups, IEnumerable<IPostConfigureOptions<TOptions>> postConfigures)
6
            : base(setups, postConfigures)
7
    {
8
        if (typeof(TOptions).Namespace.StartsWith(NamespacePrefix) && setups.Any() == false && postConfigures.Any() == false)
9
        {
10
            throw new InvalidOperationException($"No configuration options or post configuration options was found to configure {typeof(TOptions)}");
11
        }
12
    }
13
}
14

15
public class Startup
16
{
17
    // This method gets called by the runtime. Use this method to add services to the container.
18
    public void ConfigureServices(IServiceCollection services)
19
    {
20
        services.AddTransient(typeof(IOptionsFactory<>), typeof(ValidatableOptionsFactory<>));
21
        services.AddOptions();
22
    }
23
}

This method works fine (although probably needs smarter TOptions filter)

however I got to conclusion that there is no point to do validation in a runtime, and the integration test might be a better choice. I came up with following code (I am assuming that all configuration options are stored in the same assembly, as this is convention in my project)

1
public class OptionsTests
2
{
3
    private readonly Lazy<IWebHost> _webHost = new Lazy<IWebHost>(Program.BuildWebHost(null));
4

5
    // this test will fail as not every option in assembly is configured
6
    [Fact]
7
    public void AllConfigurationOptions_HasConfigurationServicesDefined()
8
    {
9
        var optionsType = typeof(IOptions<>);
10
        var constructorParameterTypes = typeof(Program).Assembly.GetExportedTypes()
11
                .SelectMany(type => type.GetConstructors().SelectMany(ctor => ctor.GetParameters()))
12
                .Select(parameter => parameter.ParameterType);
13

14
        var optionValueTypes = constructorParameterTypes.Where(parameterType => IsAssignableToGenericType(parameterType, optionsType))
15
                .Select(options => options.GetGenericArguments().Single())
16
                .Distinct();
17

18
        var postConfigureOptionsType = typeof(IPostConfigureOptions<>);
19
        var configureOptionsType = typeof(IConfigureOptions<>);
20

21
        var postConfiguration = optionValueTypes.Select(type => new
22
        {
23
            optionsType = type,
24
            configureOptionsType = _webHost.Value.Services.GetServices(configureOptionsType.MakeGenericType(type)),
25
            postConfigureServices = _webHost.Value.Services.GetServices(postConfigureOptionsType.MakeGenericType(type))
26
        });
27

28
        var emptyConfigurations =
29
                postConfiguration.Where(item => item.configureOptionsType.Any() == false && item.postConfigureServices.Any() == false)
30
                    .Select(item => item.optionsType);
31

32
        emptyConfigurations.Should().BeEmpty("All options should be configured");
33
    }
34

35
    // https://stackoverflow.com/questions/74616/how-to-detect-if-type-is-another-generic-type/1075059#1075059
36
    public static bool IsAssignableToGenericType(Type givenType, Type genericType)
37
    {
38
        var interfaceTypes = givenType.GetInterfaces();
39

40
        if (interfaceTypes.Any(it => it.IsGenericType && it.GetGenericTypeDefinition() == genericType))
41
        {
42
            return true;
43
        }
44

45
        if (givenType.IsGenericType && givenType.GetGenericTypeDefinition() == genericType)
46
            return true;
47

48
        var baseType = givenType.BaseType;
49
        if (baseType == null) return false;
50

51
        return IsAssignableToGenericType(baseType, genericType);
52
    }
53
}

Running the test shows that NotificationOptions was not configured

Source code for this post can be found here