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

2018-01-292018-02-28 TPodolakASP.NET Core1 Comment

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>

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

    public ValuesController(IOptions<PaymentOptions> paymentOptions, IOptions<NotificationOptions> notificationOptions)
    {
        _paymentOptions = paymentOptions ?? throw new ArgumentNullException(nameof(paymentOptions));
        _notificationOptions = notificationOptions ?? throw new ArgumentNullException(nameof(notificationOptions));
    }

    // GET api/values
    [HttpGet]
    public IEnumerable<string> Get()
    {
        var notificationOptions = _notificationOptions.Value;
        var paymentOptions = _paymentOptions.Value;
            
        return new string[] {"value1", "value2"};
    }
}

[Route("api/[controller]")]

public class ValuesController : Controller

{

private readonly IOptions<PaymentOptions> _paymentOptions;

private readonly IOptions<NotificationOptions> _notificationOptions;

public ValuesController(IOptions<PaymentOptions> paymentOptions, IOptions<NotificationOptions> notificationOptions)

{

_paymentOptions = paymentOptions ?? throw new ArgumentNullException(nameof(paymentOptions));

_notificationOptions = notificationOptions ?? throw new ArgumentNullException(nameof(notificationOptions));

}

// GET api/values

[HttpGet]

public IEnumerable<string> Get()

{

var notificationOptions = _notificationOptions.Value;

var paymentOptions = _paymentOptions.Value;

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

}

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

public class Startup
{
    // Rest of the code omitted for brevity
    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddOptions();
        services.AddMvc();
        services.Configure<PaymentOptions>(Configuration.GetSection("PaymentOptions"));
    }
      // Rest of the code omitted for brevity
}

public class Startup

{

// Rest of the code omitted for brevity

// This method gets called by the runtime. Use this method to add services to the container.

public void ConfigureServices(IServiceCollection services)

{

services.AddOptions();

services.AddMvc();

services.Configure<PaymentOptions>(Configuration.GetSection("PaymentOptions"));

}

// Rest of the code omitted for brevity

}

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.

public static IServiceCollection AddOptions(this IServiceCollection services)
{
    if (services == null)
        throw new ArgumentNullException(nameof (services));

    services.TryAdd(ServiceDescriptor.Singleton(typeof (IOptions<>), typeof (OptionsManager<>)));
    services.TryAdd(ServiceDescriptor.Scoped(typeof (IOptionsSnapshot<>), typeof (OptionsManager<>)));
    services.TryAdd(ServiceDescriptor.Singleton(typeof (IOptionsMonitor<>), typeof (OptionsMonitor<>)));
    services.TryAdd(ServiceDescriptor.Transient(typeof (IOptionsFactory<>), typeof (OptionsFactory<>)));
    services.TryAdd(ServiceDescriptor.Singleton(typeof (IOptionsMonitorCache<>), typeof (OptionsCache<>)));
    return services;
}

public static IServiceCollection AddOptions(this IServiceCollection services)

{

if (services == null)

throw new ArgumentNullException(nameof (services));

services.TryAdd(ServiceDescriptor.Singleton(typeof (IOptions<>), typeof (OptionsManager<>)));

services.TryAdd(ServiceDescriptor.Scoped(typeof (IOptionsSnapshot<>), typeof (OptionsManager<>)));

services.TryAdd(ServiceDescriptor.Singleton(typeof (IOptionsMonitor<>), typeof (OptionsMonitor<>)));

services.TryAdd(ServiceDescriptor.Transient(typeof (IOptionsFactory<>), typeof (OptionsFactory<>)));

services.TryAdd(ServiceDescriptor.Singleton(typeof (IOptionsMonitorCache<>), typeof (OptionsCache<>)));

return services;

}

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

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

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

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

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

public class Startup
{      
    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddTransient(typeof(IOptionsFactory<>), typeof(ValidatableOptionsFactory<>));
        services.AddOptions();
    }
}

public class ValidatableOptionsFactory<TOptions> : OptionsFactory<TOptions> where TOptions : class, new()

{

private static readonly string NamespacePrefix = typeof(Program).Namespace.Split('.').First();

public ValidatableOptionsFactory(IEnumerable<IConfigureOptions<TOptions>> setups, IEnumerable<IPostConfigureOptions<TOptions>> postConfigures)

: base(setups, postConfigures)

{

if (typeof(TOptions).Namespace.StartsWith(NamespacePrefix) && setups.Any() == false && postConfigures.Any() == false)

{

throw new InvalidOperationException($"No configuration options or post configuration options was found to configure {typeof(TOptions)}");

}

public class Startup

{

// This method gets called by the runtime. Use this method to add services to the container.

public void ConfigureServices(IServiceCollection services)

{

services.AddTransient(typeof(IOptionsFactory<>), typeof(ValidatableOptionsFactory<>));

services.AddOptions();

}

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)

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

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

        var optionValueTypes = constructorParameterTypes.Where(parameterType => IsAssignableToGenericType(parameterType, optionsType))
                .Select(options => options.GetGenericArguments().Single())
                .Distinct();
            
        var postConfigureOptionsType = typeof(IPostConfigureOptions<>);
        var configureOptionsType = typeof(IConfigureOptions<>);

        var postConfiguration = optionValueTypes.Select(type => new
        {
            optionsType = type,
            configureOptionsType = _webHost.Value.Services.GetServices(configureOptionsType.MakeGenericType(type)),
            postConfigureServices = _webHost.Value.Services.GetServices(postConfigureOptionsType.MakeGenericType(type))
        });

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

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

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

        if (interfaceTypes.Any(it => it.IsGenericType && it.GetGenericTypeDefinition() == genericType))
        {
            return true;
        }

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

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

        return IsAssignableToGenericType(baseType, genericType);
    }
}

public class OptionsTests

{

private readonly Lazy<IWebHost> _webHost = new Lazy<IWebHost>(Program.BuildWebHost(null));

// this test will fail as not every option in assembly is configured

[Fact]

public void AllConfigurationOptions_HasConfigurationServicesDefined()

{

var optionsType = typeof(IOptions<>);

var constructorParameterTypes = typeof(Program).Assembly.GetExportedTypes()

.SelectMany(type => type.GetConstructors().SelectMany(ctor => ctor.GetParameters()))

.Select(parameter => parameter.ParameterType);

var optionValueTypes = constructorParameterTypes.Where(parameterType => IsAssignableToGenericType(parameterType, optionsType))

.Select(options => options.GetGenericArguments().Single())

.Distinct();

var postConfigureOptionsType = typeof(IPostConfigureOptions<>);

var configureOptionsType = typeof(IConfigureOptions<>);

var postConfiguration = optionValueTypes.Select(type => new

{

optionsType = type,

configureOptionsType = _webHost.Value.Services.GetServices(configureOptionsType.MakeGenericType(type)),

postConfigureServices = _webHost.Value.Services.GetServices(postConfigureOptionsType.MakeGenericType(type))

});

var emptyConfigurations =

postConfiguration.Where(item => item.configureOptionsType.Any() == false && item.postConfigureServices.Any() == false)

.Select(item => item.optionsType);

emptyConfigurations.Should().BeEmpty("All options should be configured");

}

// https://stackoverflow.com/questions/74616/how-to-detect-if-type-is-another-generic-type/1075059#1075059

public static bool IsAssignableToGenericType(Type givenType, Type genericType)

{

var interfaceTypes = givenType.GetInterfaces();

if (interfaceTypes.Any(it => it.IsGenericType && it.GetGenericTypeDefinition() == genericType))

{

return true;

}

if (givenType.IsGenericType && givenType.GetGenericTypeDefinition() == genericType)

return true;

var baseType = givenType.BaseType;

if (baseType == null) return false;

return IsAssignableToGenericType(baseType, genericType);

}

Running the test shows that NotificationOptions was not configured

Source code for this post can be found here

ASP.NET Core – passing command-line arguments to Startup class

2018-01-162018-01-16 TPodolakASP.NET Core1 Comment

1. Introduction

I usually pass configuration to my web API via JSON files, but recently I needed to pass them also via command-line arguments. As the solution for ASP.NET Core 2.x is quite different than for ASP.NET Core 1.x I decided to describe both methods in here.

2. ASP.NET Core 2.x

For the newest version of ASP.NET Core, the solution is pretty straightforward as IConfiguration is injected by default to the Startup class. All we have to do is to add CommandLineConfigurationSource to IConfigurationBuilder when configuring IWebHost. CommandLineConfigurationSource is part of the Microsoft.Extensions.Configuration.CommandLine package and can be easily used by AddCommandLine extension method

public class Program
{
    public static void Main(string[] args)
    {
        BuildWebHost(args).Run();
    }
	
    public static IWebHost BuildWebHost(string[] args)
    {
        var webHost = new WebHostBuilder()
	     .UseKestrel()
	     .UseContentRoot(Directory.GetCurrentDirectory())
	     .ConfigureAppConfiguration((hostingContext, config) =>
	     {
	         var env = hostingContext.HostingEnvironment;
	         config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
	               .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true);
	         config.AddEnvironmentVariables();
	         config.AddCommandLine(args);
	     }).UseStartup<Startup>()
	       .Build();
        return webHost;
    }
}

public class Program

{

public static void Main(string[] args)

{

BuildWebHost(args).Run();

}

public static IWebHost BuildWebHost(string[] args)

{

var webHost = new WebHostBuilder()

.UseKestrel()

.UseContentRoot(Directory.GetCurrentDirectory())

.ConfigureAppConfiguration((hostingContext, config) =>

{

var env = hostingContext.HostingEnvironment;

config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)

.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true);

config.AddEnvironmentVariables();

config.AddCommandLine(args);

}).UseStartup<Startup>()

.Build();

return webHost;

}

Now we can access our command-line arguments just like any other configuration

public class Startup
{
    private readonly IConfiguration _configuration;

    public Startup(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory, IApplicationLifetime applicationLifetime)
    {
        loggerFactory.AddConsole();
        loggerFactory.AddDebug();
        applicationLifetime.ApplicationStarted.Register(() => loggerFactory.CreateLogger<Startup>().LogInformation("CommandLine argument {0}: ", _configuration["usecustomschema"]));
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseMvc();
    }
}

public class Startup

{

private readonly IConfiguration _configuration;

public Startup(IConfiguration configuration)

{

_configuration = configuration;

}

// This method gets called by the runtime. Use this method to add services to the container.

public void ConfigureServices(IServiceCollection services)

{

services.AddMvc();

}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory, IApplicationLifetime applicationLifetime)

{

loggerFactory.AddConsole();

loggerFactory.AddDebug();

applicationLifetime.ApplicationStarted.Register(() => loggerFactory.CreateLogger<Startup>().LogInformation("CommandLine argument {0}: ", _configuration["usecustomschema"]));

if (env.IsDevelopment())

{

app.UseDeveloperExceptionPage();

}

app.UseMvc();

}

3. ASP.NET Core 1.x

The solution for ASP.NET Core 1.x requires a bit more work but it is possible to achieve the same result. We still will be using CommandLineConfigurationSource from Microsoft.Extensions.Configuration.CommandLine package, however this time we have to manually create IConfiguration object and register it in the container before the Startup class is created. This is possible because the WebHostBuilder exposes ConfigureServices method.

public class Program
{
    public static void Main(string[] args)
    {
        var host = new WebHostBuilder()
             .UseKestrel()
             .UseContentRoot(Directory.GetCurrentDirectory())
             UseIISIntegration()
             .ConfigureServices(serviceCollection =>
                 serviceCollection.AddSingleton<IConfiguration>(new ConfigurationBuilder().AddCommandLine(args).Build()))
             .UseStartup<Startup>()
             .Build();

          host.Run();
    }
}

public class Program

{

public static void Main(string[] args)

{

var host = new WebHostBuilder()

.UseKestrel()

.UseContentRoot(Directory.GetCurrentDirectory())

UseIISIntegration()

.ConfigureServices(serviceCollection =>

serviceCollection.AddSingleton<IConfiguration>(new ConfigurationBuilder().AddCommandLine(args).Build()))

.UseStartup<Startup>()

.Build();

host.Run();

}

Having our service registered now we can easily access IConfiguration object in our application

public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        // Add framework services.
        services.AddMvc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IHostingEnvironment hostingEnvironment, IConfiguration configuration, ILoggerFactory loggerFactory, IApplicationLifetime applicationLifetime)
    {
        loggerFactory.AddConsole();
        loggerFactory.AddDebug();
        applicationLifetime.ApplicationStarted.Register(() =>
                loggerFactory.CreateLogger<Startup>().LogInformation("CommandLine argument {0}: ", configuration["usecustomschema"]));

        if (hostingEnvironment.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseMvc();
    }
}

public class Startup

{

// This method gets called by the runtime. Use this method to add services to the container.

public void ConfigureServices(IServiceCollection services)

{

// Add framework services.

services.AddMvc();

}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.

public void Configure(IApplicationBuilder app, IHostingEnvironment hostingEnvironment, IConfiguration configuration, ILoggerFactory loggerFactory, IApplicationLifetime applicationLifetime)

{

loggerFactory.AddConsole();

loggerFactory.AddDebug();

applicationLifetime.ApplicationStarted.Register(() =>

loggerFactory.CreateLogger<Startup>().LogInformation("CommandLine argument {0}: ", configuration["usecustomschema"]));

if (hostingEnvironment.IsDevelopment())

{

app.UseDeveloperExceptionPage();

}

app.UseMvc();

}

Source code for this post can be found here

ASP.NET Core – retrieving swagger specification without hosting API

2018-01-082018-01-15 TPodolakASP.NET Core, swagger

1. Introduction

I am currently exploring possible ways of removing a repetitive work when it comes to creating integration tests for our API. The one thing which usually takes some time when testing a new endpoint is a process of creating response and request classes (as we don’t share the models between API project and integration test project). That is why I would like to have some kind of a tool (AutoRest or NSwag) which would do it for us (possibly, in a prebuild step). As those tools generate API clients based on swagger specification and I wanted this process to be as fast as possible I decided to figure out the way how to retrieve swagger specs without hosting the API.

2. Implementation

After taking a look at Swashbuckle.AspNetCore.Swagger source code it turned out that Swashbuckle.AspNetCore.Swagger.ISwaggerProvider is responsible for creating a SwaggerDocument class. JSON representation of that class is a swagger specification. Having all of that in mind I wrote following piece of code.

public class SchemaRetriever
{
    private readonly Lazy<IWebHost> _webHostProxy = new Lazy<IWebHost>(() => Program.BuildWebHost(new string[0]));

    private IWebHost WebHost => _webHostProxy.Value;
        
    public string RetrieveSchema(string swaggerDocument)
    {
        using (var scope = WebHost.Services.CreateScope())
        {
            var serviceProvider = scope.ServiceProvider;
            var swaggerProvider = serviceProvider.GetRequiredService<ISwaggerProvider>();
            var mvcJsonOptions = serviceProvider.GetRequiredService<IOptions<MvcJsonOptions>>();
            var document = swaggerProvider.GetSwagger(swaggerDocument, null, "/");

            var serializer = new JsonSerializer
                {
                    NullValueHandling = NullValueHandling.Ignore,
                    Formatting = mvcJsonOptions.Value.SerializerSettings.Formatting,
                    ContractResolver = new SwaggerContractResolver(mvcJsonOptions.Value.SerializerSettings)
                };

            using (var stringWriter = new StringWriter())
            {
                serializer.Serialize(stringWriter, document);
                return stringWriter.ToString();
            }   
        }
    }
}

public class Program
{
    public static void Main(string[] args)
    {
        BuildWebHost(args).Run();
    }

    public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
}

public class SchemaRetriever

{

private readonly Lazy<IWebHost> _webHostProxy = new Lazy<IWebHost>(() => Program.BuildWebHost(new string[0]));

private IWebHost WebHost => _webHostProxy.Value;

public string RetrieveSchema(string swaggerDocument)

{

using (var scope = WebHost.Services.CreateScope())

{

var serviceProvider = scope.ServiceProvider;

var swaggerProvider = serviceProvider.GetRequiredService<ISwaggerProvider>();

var mvcJsonOptions = serviceProvider.GetRequiredService<IOptions<MvcJsonOptions>>();

var document = swaggerProvider.GetSwagger(swaggerDocument, null, "/");

var serializer = new JsonSerializer

{

NullValueHandling = NullValueHandling.Ignore,

Formatting = mvcJsonOptions.Value.SerializerSettings.Formatting,

ContractResolver = new SwaggerContractResolver(mvcJsonOptions.Value.SerializerSettings)

};

using (var stringWriter = new StringWriter())

{

serializer.Serialize(stringWriter, document);

return stringWriter.ToString();

}

public class Program

{

public static void Main(string[] args)

{

BuildWebHost(args).Run();

}

public static IWebHost BuildWebHost(string[] args) =>

WebHost.CreateDefaultBuilder(args)

.UseStartup<Startup>()

.Build();

}

The Program class is an entry point of the API. The only one difference compared to default ASP.NET Core template is the fact that I made the BuildWebHost method public. Thanks to that we can build the host (but without running) and get our hands on the DI container of our application. From that point the rest is easy, I retrieve the ISwaggerProvider from the container so I can get the swagger document for given id.

In order to make sure that the SchemaRetriever works as expected I wrote simple integration test which makes sure that swagger specs from hosted API is the same as the one retrieved without hosting.

[Fact]
public async Task RetrieveSchema_RetrievesSwaggerSchema_SameAsDeployedSchema()
{
    var swaggerSchemaWithoutHosting = _subject.RetrieveSchema(_swaggerDocumentName);
    using (var testServer = new TestServer(new WebHostBuilder().UseStartup<Startup>()))
    {
        using (var httpClient = testServer.CreateClient())
        {
            var response = await httpClient.GetAsync($"swagger/{EscapeDataString(_swaggerDocumentName)}/swagger.json");
            response.EnsureSuccessStatusCode();
            var content = await response.Content.ReadAsStringAsync();

            swaggerSchemaWithoutHosting.Should().Be(content);
        }
    }
}

[Fact]

public async Task RetrieveSchema_RetrievesSwaggerSchema_SameAsDeployedSchema()

{

var swaggerSchemaWithoutHosting = _subject.RetrieveSchema(_swaggerDocumentName);

using (var testServer = new TestServer(new WebHostBuilder().UseStartup<Startup>()))

{

using (var httpClient = testServer.CreateClient())

{

var response = await httpClient.GetAsync($"swagger/{EscapeDataString(_swaggerDocumentName)}/swagger.json");

response.EnsureSuccessStatusCode();

var content = await response.Content.ReadAsStringAsync();

swaggerSchemaWithoutHosting.Should().Be(content);

}

Source code for this post can be found here

.NET BLOG

.NET, C# blog

Month: January 2018

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

1. Introduction

2. Problem

3. Ensuring initialization

ASP.NET Core – passing command-line arguments to Startup class

1. Introduction

2. ASP.NET Core 2.x

3. ASP.NET Core 1.x

ASP.NET Core – retrieving swagger specification without hosting API

1. Introduction

2. Implementation