Take your .NET configuration to the next level with value substitution

Configuration in .NET is a powerful pattern that allows .NET developers to manage application settings from various sources, such as JSON files, environment variables, and more. However, sometimes developers need a way to reference and substitute configuration values from other settings, which is not provided out of the box. That’s where the GSoft.Extensions.Configuration.Substitution library comes in!

In this blog post, we will explore how the GSoft.Extensions.Configuration.Substitution library works, its benefits, and how to get started with it.

How value substitution works

GSoft.Extensions.Configuration.Substitution is a value substitution configuration provider implementation for Microsoft.Extensions.Configuration. With this library, you can reference configuration values inside other configuration values using a simple syntax: ${ReferencedConfigurationKey}.

For example, consider this appsettings.json:

{
  "MyService": {
    "BaseUrl": "https://localhost:1234"
  },
  "OpenId": {
    "Authority": "${MyService:BaseUrl}",
    "ClientId": "0be8388b-8651-45e7-af85-0081bb96d708",
    "TenantId": "338287dd-5982-4900-a973-f3851325e6b3",
    "MetadataAddress": "${MyService:BaseUrl}/.well-known/openid-configuration?tenantId=${OpenId:TenantId}"
  }
}

Evaluating the configuration value OpenId:MetadataAddress would return https://localhost:1234/.well-known/openid-configuration?tenantId=338287dd-5982-4900-a973-f3851325e6b3. Override MyService:BaseUrl and OpenId:TenantId in an environment-specific appsettings.{Environment}.json, and you’ll obtain a new metadata address.

This substitution also works with arrays and across multiple configuration providers, so you could easily reference values stored in various locations, such as Azure Key Vault secrets or Azure App Configuration.

Internally, the substitution algorithm recursively replaces referenced values. If a value is missing, it will throw an exception. In cases of circular dependency, an exception will also be thrown, providing information about the referenced values that led to this situation. To prevent a value from being substituted, you can escape it using double curly braces, such as ${{Foo}}. In this case, the returned value will be ${Foo}.

Benefits of using GSoft.Extensions.Configuration.Substitution

1. Streamlined configuration management: Using value substitution streamlines the process of referencing and reusing values from various configuration sources, leading to cleaner and more manageable configuration files.

2. Elimination of redundant values: Value substitution prevents the need for duplicating values across configuration files, centralizing the data.

3. Improved multi-environment support: Set up configuration values in appsettings.json to reference values specific to different environment configurations.

4. Versatility: The library is compatible with all configuration providers, allowing seamless integration with your preferred data source.

5. Enhanced team collaboration: GSoft.Extensions.Configuration.Substitution promotes better collaboration among project team members by maintaining clear and comprehensible configuration files, making it simpler for them to understand and adjust the application settings.

Getting started

To get started with GSoft.Extensions.Configuration.Substitution, follow these steps:

dotnet add package GSoft.Extensions.Configuration.Substitution

Then, add the substitution provider to your application’s configuration:

// Example for an ASP.NET Core web application
var builder = WebApplication.CreateBuilder(args);

// Setup your configuration
builder.Configuration.AddJsonFile("appsettings.json");
builder.Configuration.AddEnvironmentVariables();
builder.Configuration.AddSubstitution(); // <-- Add this AFTER other configuration providers

And that’s it! You can now use value substitution in your configuration files and enjoy cleaner, more maintainable settings.

Conclusion

The GSoft.Extensions.Configuration.Substitution library is a powerful addition to the Microsoft.Extensions.Configuration ecosystem. By allowing value substitution across multiple configuration providers, it simplifies configuration management and improves maintainability. Give it a try, and let this library streamline your .NET configuration experience!

For the full documentation, be sure to check out the project’s README on GitHub and consider giving it a star ⭐ to show your support!