Multiple Approaches to Retrieve Configuration Values from appsettings.json in ASP.NET Core

Introduction

In .NET Framework 4.x, developers could use ConfigurationManager.AppSettings["Foo"] to directly read configuration values from the Web.config file and access them easily through static classes. However, in ASP.NET Core, the configuration system has been redesigned with a more flexible and extensible architecture. This article delves into multiple methods for retrieving configuration values from the appsettings.json file in ASP.NET Core, offering detailed implementation examples.

Configuration System Overview

The ASP.NET Core configuration system is based on key-value pairs and supports various configuration sources, including JSON files, environment variables, command-line arguments, and more. By default, applications initialize configuration using the WebApplication.CreateBuilder method, which loads sources in the following order: command-line arguments, non-prefixed environment variables, user secrets (in development environment), appsettings.{Environment}.json, and appsettings.json. This hierarchical structure allows overriding configuration values across different environments.

Using the IOptions Pattern

The IOptions pattern is the recommended approach in ASP.NET Core for reading related configuration values. First, define a POCO class to map the configuration structure:

public class MyConfiguration
{
    public bool MyProperty { get; set; }
}

Add the corresponding configuration section in the appsettings.json file:

{
  "myConfiguration": {
    "myProperty": true 
  }
}

Register the configuration in the ConfigureServices method in Program.cs:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<MyConfiguration>(Configuration.GetSection("myConfiguration"));
}

In controllers or services, use IOptions via dependency injection:

public class ValuesController : Controller
{
    private readonly MyConfiguration _myConfiguration;

    public ValuesController(IOptions<MyConfiguration> myConfiguration)
    {
        _myConfiguration = myConfiguration.Value;
    }
}

Advantages of this method include support for configuration hot-reloading (via IOptionsSnapshot) and better type safety. However, some developers find that IOptions introduces unnecessary complexity.

Direct POCO Class Binding

As an alternative to IOptions, you can directly bind a configuration section to a POCO class and register it as a singleton service. In the ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton(Configuration.GetSection("myConfiguration").Get<MyConfiguration>());
}

Then, inject the POCO class directly in controllers:

public class ValuesController : Controller
{
    private readonly MyConfiguration _myConfiguration;

    public ValuesController(MyConfiguration myConfiguration)
    {
        _myConfiguration = myConfiguration;
    }
}

This approach simplifies dependency injection but loses some advanced features of IOptions, such as configuration change notifications. For easier unit testing, it is advisable to abstract the configuration class with an interface.

Direct Access via IConfiguration

For simple configuration values, you can use the IConfiguration interface directly. First, inject IConfiguration in the controller:

private readonly IConfiguration _configuration;

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

Then, read configuration values by key name:

var value = _configuration["MyKey"];

For hierarchical configurations, use colon-separated key paths:

var title = _configuration["Position:Title"];

You can also use the GetValue<T> method to obtain typed values with a default value:

var number = _configuration.GetValue<int>("NumberKey", 99);

This method is flexible and straightforward but lacks type safety and structured access.

Configuration Binding and Validation

ASP.NET Core supports directly binding configuration sections to object instances. Use the ConfigurationBinder.Bind method:

var options = new MyConfiguration();
Configuration.GetSection("myConfiguration").Bind(options);

Or use the Get<T> extension method:

var options = Configuration.GetSection("myConfiguration").Get<MyConfiguration>();

Configuration classes must meet the following criteria: have a public parameterless constructor, all public read-write properties are bound, and fields are not bound. Constant fields can be used to avoid hardcoding configuration section names.

Environment-Specific Configuration

ASP.NET Core supports environment-specific configuration files, such as appsettings.Development.json and appsettings.Production.json. Configuration values in these files override the same keys in appsettings.json. The environment is determined by IHostingEnvironment.EnvironmentName, typically set via the ASPNETCORE_ENVIRONMENT environment variable.

Configuration Reloading

By default, the appsettings.json and appsettings.{Environment}.json files are enabled with reloadOnChange: true, meaning changes to these files while the application is running are automatically read. For IOptions, use IOptionsSnapshot to obtain the latest values.

Security Considerations

Never store passwords or other sensitive data in configuration files. In development environments, use the Secret Manager tool to manage secrets. In production environments, it is recommended to use Azure Key Vault or environment variables for storing sensitive information.

Conclusion

ASP.NET Core offers multiple methods for reading configuration values from appsettings.json, each with its own suitable scenarios. The IOptions pattern provides the most complete feature set, including type safety and configuration change notifications; direct POCO class binding simplifies dependency injection; and direct access via IConfiguration offers maximum flexibility. Developers should choose the most appropriate method based on the specific needs of their application.