Placeholder Provider

The placeholder resolver enables usage of ${....} placeholders in your configuration. The provider lets you define configuration values as placeholders and have them be substituted with evaluated values at runtime during configuration access, based on the values of other configuration keys.

A placeholder takes the form of ${key:subkey1:subkey2?defaultValue}, where key:subkey1:subkey2 represents another key in the configuration. At runtime, when you access a configuration key whose value contains a placeholder, the resolver is called to substitute the placeholder with a value that exists in the configuration. If no value is found at the placeholder key, the placeholder is returned unresolved. But if a default value is specified in the placeholder, that default value is returned instead.

Note that placeholder defaults (for example, defaultValue) can also be defined to be placeholders, and they are resolved as well.

Usage

You should have a good understanding of how the .NET Configuration System works before starting to use this provider.

To use the Steeltoe placeholder resolver provider, you need to:

1. Add the appropriate NuGet package reference to your project.
2. Add the provider to the Configuration Builder.
3. Access substituted values from the IConfiguration.

Add NuGet Reference

To use the provider, you need to add a reference to the Steeltoe.Configuration.Placeholder NuGet package.

Add Configuration Provider

To have placeholders resolved when accessing your configuration data, you need to add the placeholder resolver provider to the ConfigurationBuilder.

using Steeltoe.Configuration.Placeholder;

var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddPlaceholderResolver();

Important

The placeholder resolver works by wrapping and replacing (effectively taking ownership of) all existing configuration sources already added to the ConfigurationBuilder. As a result, you typically will want to add it as the last provider.

Access Configuration Data

Once the configuration has been built, the placeholder resolver is used to resolve any placeholders as you access your configuration data. You can access the configuration data as you normally would, and the resolver tries to resolve any placeholder before returning the value for the key requested.

Consider the following appsettings.json file:

{
  "Spring": {
    "Application": {
      "Name": "myName"
    },
    "Cloud": {
      "Config": {
        "Name" : "${Spring:Application:Name?unknown}",
      }
    }
  }
  ...
}

When using the normal IConfiguration indexer to access the configuration, you see the placeholder resolver do its thing:

var configuration = builder.Build();
string? name = configuration["Spring:Cloud:Config:Name"]; // "myName"