Take your .NET configuration to the next level with value substitution
Tags: dotnet, csharp, aspdotnet, configuration
Published: 2023-04-11 12:30:00

[Configuration in .NET](https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration) 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](https://github.com/gsoft-inc/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](https://github.com/gsoft-inc/gsoft-extensions-configuration-substitution/) is a value substitution configuration provider implementation for [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/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_:

```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](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets) or [Azure App Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.AzureAppConfiguration).

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}`.

![GSoft.Extensions.Configuration.Substitution is aware of other .NET configuration providers](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/d4jdahwpoyisk8sr8ti2.png)

## 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:

```csharp
// 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](https://github.com/gsoft-inc/gsoft-extensions-configuration-substitution/) library is a powerful addition to the [Microsoft.Extensions.Configuration](https://learn.microsoft.com/en-us/dotnet/core/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](https://github.com/gsoft-inc/gsoft-extensions-configuration-substitution/) and consider giving it a star ⭐ to show your support!