Card image cap

Working with Options pattern in ASP.NET Core - The Complete Guide

ASP.NET Core  • Posted 3 months ago

Accessing an application configuration using IConfiguration service provided by ASP.NET Core which brings up an aggregate of appsettings json file along with several other providers, is simple and useful. However, As the application grows in complexity, so does configuration in most cases: new configurations and sections add up to the size of the appsettings making individual values from the appsettings hard to access. For example, let's assume we have an application whose appsettings json looks like this:

{
  ...

  "Oidc": {
    "Google": {
      "ClientId": "27454jshd64dufmgngterh",
      "ClientSecret": "39jfytittthsd83jgygtttktt7tyy8kthgh8"
    },
    "Facebook": {
      "ClientId": "o375j6593jdgdb254en62rd",
      "ClientSecret": "vhfyrfjhrrfdsow0273485djdgw722pr955ht"
    },
    "Okta": {
      "ClientId": "a1b2c3d4e5f6g7h8i9j03fg",
      "ClientSecret": "hfgfwornrtftfjnsfre693i34543u2gdjfbff"
    }
  },
  "Smtp": {
    "Server": "mail.abc.com",
    "Port": "56",
    "From": "me@abc.com",
    "Username": "me@abc.com",
    "Password": "Abcd@1234",
    "IsSsl": false
  },
  "Jwt": {
    "Audience": "thisisyouraudience",
    "Issuer": "thisisyourissuers",
    "SigningKey": "thiskeyisveryhardtobreak",
    "IsValidateLifetime": true,
    "IsValidateIssuer": true,
    "IsValidateAudience": true
  },

  ...
}

If we are to read the ClientId of the OidcProvider "Google", we should access its value as below using the classic IConfiguration instance:

var googleClientId = Configuration["Oidc:Google:ClientId"].ToString();

As the configuration structure goes diverse with nested sections, its key representation grows lengthy and hard to maintain. In a previous article, we tried to solve this by creating a strongly typed ConfigurationManager class which encapsulates this key access mechanism and also takes care of the datatype casting requirements for non-string properties. An even elegant solution for this is to "configure" these sections against their matching strongly typed classes and let ASP.NET Core handle the heavyloading for us.

Something like:

"if i want to access the section Google from Oidc, i'd configure the section against a known type and each time i request that section the container should provide me an instance of the type i configured before."

This notion is how Options pattern works in ASP.NET Core. The pattern helps in creating a "strongly-typed access" to sections in the configuration through a predefined mapping.

Back in our example, we can create strongly typed classes for the sections in the configuration json we saw before as below:

public class SmtpOptions
{
    public const string SectionName = "Smtp";
    public int Port { get; set; }
    public string From { get; set; }
    public string Server { get; set; }
    public string Username { get; set; }
    public string Password { get; set; }
    public bool IsSsl { get; set; }
}

We'll configure the section name which will be bound to an instance of this class within the class itself, so that we can use this value while "configuring", just to avoid using magic strings.

Just to remind that this class now represents this section of the configuration:

"Smtp": {
    "Server": "mail.abc.com",
    "Port": "56",
    "From": "me@abc.com",
    "Username": "me@abc.com",
    "Password": "Abcd@1234",
    "IsSsl": false
}

Ensure that:

  • The property names and their types match the key names and their value types "exactly" in the configuration.
  • The classes used must be non-abstract with parameterless constructors
  • Only the public accessors (properties) are bound to configuration data but not fields

To create the "binding" we have two approaches:

  1. Use Configuration.Bind() to a new instance of the type and register it as a service
  2. Use the IOptions interface to let ASPNETCORE do the needful for us

In the first approach, we create a new instance of type SmtpOptions and then pass the instance to Configure.Bind() method against the section. Finally, we register this instance as a service of our choice to let the ASPNETCORE container maintain the instance for us.

# Startup.ConfigureServices() Method #

var smtp = new SmtpOptions();
Configuration.Bind(SmtpOptions.SectionName, smtp);
services.AddSingleton(smtp);

It can also be written as following using Get() instead of Bind(), which avoids the use of "new":

# Startup.ConfigureServices() Method #

var smtp = Configuration.GetSection(SmtpOptions.SectionName)
                .Get<SmtpOptions>();

services.AddSingleton(smtp);

To use this instance in our logic, we can just inject the type through the constructor of the component where it is to be used.

public class MailController : ControllerBase
{
    private readonly SmtpOptions smtp;

    public MailController(SmtpOptions smtpOptions)
    {
        this.smtp = smtpOptions;
    }

    ...

Although this approach works, we have two things here which aren't that good:

  1. Using the "new" keyword - even in the world of dependency injection, why to explicitly "new" an instance?
  2. More code written - we're literally instantiating, binding and then registering!

This paves way to the second approach which uses the IOptions set of interfaces. In this approach, we "configure" a type and its corresponding configuration section into the "options", and access via the same.

For example, the above code can be rewritten as:

# Startup.ConfigureServices() Method #

services.Configure<SmtpOptions>(
        Configuration.GetSection(SmtpOptions.SectionName));
public class MailController : ControllerBase
{
    private readonly SmtpOptions smtp;

    public MailController(IOptions<SmtpOptions> smtpOptions)
    {
        this.smtp = smtpOptions;
    }

    ...

Observe the number of lines written - just one. And we're also avoiding the "new" keyword. This makes the Options interface a "better" bet over the former. The IOptions interface is a part of the Microsoft.Extensions.Options namespace, which is implicitly available in ASPNETCORE core package.

Types of Options:

There are three interfaces provided by this namespace as a part of configuring TOptions instances.

  1. IOptions
  2. IOptionsSnapshot and
  3. IOptionsMonitor

We can use IOptionsSnapshot instead of IOptions in the above example to inject in a Controller as below:

public class MailController : ControllerBase
{
    private readonly SmtpOptions smtp;

    public MailController(IOptionsSnapshot<SmtpOptions> smtpOptions)
    {
        this.smtp = smtpOptions.Value;
    }

    ...

IOptionsMonitor is another way we can access the configured options, where the "CurrentValue" of the options is returned each time the service is requested.

public class MailController : ControllerBase
{
    private readonly SmtpOptions smtp;

    public MailController(IOptionsMonitor<SmtpOptions> smtpOptions)
    {
        this.smtp = smtpOptions.CurrentValue;
    }

    ...

When to use IOptions, IOptionsSnapshot and IOptionsMonitor?

IOptionsSnapshot:

  • Enables us to load configuration changes even after app has started
  • It is registered as a ScopedService and can't be injected into Singleton services
  • Since it's a ScopedService, its better suited for scenarios where the configuration needs to be re-read for every request
  • Supports "named" options

IOptions:

  • It is registered as a SingletonService and can be injected into any service
  • Since it's a singleton, configuration changes can't be re-read once instansiated
  • Doesn't support "named" options

IOptionsMonitor:

  • It is registered as a SingletonService similar to IOptions and can be injected into any service
  • It can also be used to read reloaded configurations as opposed to IOptions, hence it gives us the best of both worlds - IOptionsSnapshot and IOptions
  • Also supports "named" options

What are Named Options?

When discussing about IOptionsSnapshot and IOptionsMonitor, we saw that they support "named" options. What is a "named" option?

Until this section, we have been configuring and using options monotonously in a single section - to - single model approach. However, consider the section "Oidc" which has three subsections as below:

...

"Oidc": {
    "Google": {
      "ClientId": "27454jshd64dufmgngterh",
      "ClientSecret": "39jfytittthsd83jgygtttktt7tyy8kthgh8"
    },
    "Facebook": {
      "ClientId": "o375j6593jdgdb254en62rd",
      "ClientSecret": "vhfyrfjhrrfdsow0273485djdgw722pr955ht"
    },
    "Okta": {
      "ClientId": "a1b2c3d4e5f6g7h8i9j03fg",
      "ClientSecret": "hfgfwornrtftfjnsfre693i34543u2gdjfbff"
    }
}

...

All the three sections are formed in the same manner, but they belong to different "scenarios". We can't just clone three different classes of the same structure just to translate this block. In such cases, we use the "named" options overload which is supported by IOptionsSnapshot and IOptionsMonitor options.

Let's create a single template that resembles all three subsections perfectly.

public class OidcProviders
{
    public const string Google = "Google";
    public const string Facebook = "Facebook";
    public const string Okta = "Okta";
}

public class OidcOptions
{
    public const string SectionName = "Oidc";
    public string ClientId { get; set; }
    public string ClientSecret { get; set; }
}

The OidcOptions class mimics each subsection of the "Oidc" section, while OidcProviders represent their subsection key names. We shall now configure these subsections individually as below:

#Oidc:Google#
services.Configure<OidcOptions>(
    OidcProviders.Google, 
    Configuration.GetSection($"{OidcOptions.SectionName}:{OidcProviders.Google}"));

#Oidc:Facebook#       
services.Configure<OidcOptions>(
    OidcProviders.Facebook, 
    Configuration.GetSection($"{OidcOptions.SectionName}:{OidcProviders.Facebook}"));

#Oidc:Okta#        
services.Configure<OidcOptions>(
    OidcProviders.Okta, 
    Configuration.GetSection($"{OidcOptions.SectionName}:{OidcProviders.Okta}"));

To access these options at a required component, we can request an instance tagged to a specific "name", which in this case is the KeyNames declared in the OidcProviders class.

public class OidcOptionsController : ControllerBase
{
    private readonly OidcOptions google, facebook, okta;

    public OidcOptionsController(
            IOptionsSnapshot<OidcOptions> oidcOptions)
    {
        google = oidcOptions.Get(OidcProviders.Google);
        facebook = oidcOptions.Get(OidcProviders.Facebook);
        okta = oidcOptions.Get(OidcProviders.Okta);
    }

    ...
}

Observe that we're requesting objects based on the KeyName constants. Let's see how these objects turn out to be by adding a simple GET endpoint.

[HttpGet, Route("oidc")]
public Dictionary<string, OidcOptions> GetOidcOptions()
{
    return new Dictionary<string, OidcOptions>()
    {
        { OidcProviders.Google, google },
        { OidcProviders.Facebook, facebook },
        { OidcProviders.Okta, okta }
    };
}

The output:

{"Google":{"clientId":"27454jshd64dufmgngterh","clientSecret":"39jfytittthsd83jgygtttktt7tyy8kthgh8"},"Facebook":{"clientId":"o375j6593jdgdb254en62rd","clientSecret":"vhfyrfjhrrfdsow0273485djdgw722pr955ht"},"Okta":{"clientId":"a1b2c3d4e5f6g7h8i9j03fg","clientSecret":"hfgfwornrtftfjnsfre693i34543u2gdjfbff"}}

"Each time an IOptionsSnapshot or IOptionsMonitor is called without a "name" passed, we are actually invoking the "named" overload of the Get() method with the default KeyName, which is String.Empty or ""."

Customizing Options instance - IConfigureNamedOptions:

In the example of Oidc, let's assume that the values ClientId and ClientSecret are actually encrypted and placed in the appsettings, and before using them they must be decrypted and stored in the objects.

This requires us to work a little bit more on the OidcOptions instances before accessing them. Also, this requires an external service say IDecryptService for decrypting the values.

In such scenarios, we make use of the IConfigureNamedOptions interface, which is internally called whenever the IOptionsSnapshot or IOptionsMonitor - the "named" options are called. The implementation is done as below:

public class ConfigureOidcOptions : IConfigureNamedOptions<OidcOptions>
{
    private readonly IDecryptService decrypt;

    public ConfigureOidcOptions(IDecryptService decrypt)
    {
        this.decrypt = decrypt;
    }

    // implementation which is always called
    public void Configure(string name, OidcOptions options)
    {
        options.ClientId = this.decrypt.Decrypt(options.ClientId);
        options.ClientSecret = this.decrypt.Decrypt(options.ClientSecret);
    }

    // implementation just for the interface
    public void Configure(OidcOptions options)
    {
        Configure(Options.DefaultName, options);
    }
}

And we register this implementation of the IConfigureNamedOptions, as a SingletonService resolved for the interface IConfigureOptions. This works because IConfigureNamedOptions is a subtype of IConfigureOptions.

#Oidc:Google#
services.Configure<OidcOptions>(
    OidcProviders.Google, 
    Configuration.GetSection($"{OidcOptions.SectionName}:{OidcProviders.Google}"));

#Oidc:Facebook#       
services.Configure<OidcOptions>(
    OidcProviders.Facebook, 
    Configuration.GetSection($"{OidcOptions.SectionName}:{OidcProviders.Facebook}"));

#Oidc:Okta#        
services.Configure<OidcOptions>(
    OidcProviders.Okta, 
    Configuration.GetSection($"{OidcOptions.SectionName}:{OidcProviders.Okta}"));

services.AddSingleton<IConfigureOptions<OidcOptions>, ConfigureOidcOptions>();

And when we run this and check the value of Oidc resolved using our GET endpoint, the output is as follows:

{"Google":{"clientId":"Mjc0NTRqc2hkNjRkdWZtZ25ndGVyaA==","clientSecret":"MzlqZnl0aXR0dGhzZDgzamd5Z3R0dGt0dDd0eXk4a3RoZ2g4"},"Facebook":{"clientId":"bzM3NWo2NTkzamRnZGIyNTRlbjYycmQ=","clientSecret":"dmhmeXJmamhycmZkc293MDI3MzQ4NWRqZGd3NzIycHI5NTVodA=="},"Okta":{"clientId":"YTFiMmMzZDRlNWY2ZzdoOGk5ajAzZmc=","clientSecret":"aGZnZndvcm5ydGZ0Zmpuc2ZyZTY5M2kzNDU0M3UyZ2RqZmJmZg=="}}

In this way, we can make use of the Options pattern in the ASP.NET Core to leverage the benefits of DI and create a robust and strictly typed configuration system.

The complete example project used in this article is available under https://github.com/referbruv/options-pattern-example

What is the difference between Response.Redirect() and Server.Transfer() ?
How do you handle errors Globally in ASP.NET Core?
How do you design a strongly-typed class for a configuration?
How can you bind a configuration section to an object?
When to use IOptionsMonitor?

options pattern asp.net core options pattern in asp.net core options in .net core options in asp.net core ioptions in .net core ioptions in asp.net core iconfigureoptions .net core iconfigureoptions asp.net core dotnet core iconfigureoptions ioptionsmonitor .net core configureservices in .net core addsingleton in .net core services.configure .net core ioptions in asp.net core ioptions in .net core asp.net core iconfigureoptions ioptionsmonitor .net core ioptions in .net core ioptions in asp.net core .net core configure method dotnet core fundamentals ioptions .net core example

We use cookies to provide you with a great user experience, analyze traffic and serve targeted promotions.   Learn More   Accept