Requires: main module.

When using configuration providers, Get and Observe method overloads without parameters require an explicit association of the model type with a configuration source.

// This simply won't work (no source defined):

provider.Get<MySettings>();
provider.Observe<MySettings>();

// This will work as expected:

provider.SetupSourceFor<MySettings>(new JsonFileSource("settings.json"));

provider.Get<MySettings>();
provider.Observe<MySettings>();

A source can only be assigned to a type before any Get or Observe calls are made for that type:

provider.SetupSourceFor<MySettings>(source1); // succeeds

provider.SetupSourceFor<MySettings>(source2); // succeeds, overwrites

provider.Get<MySettings>();

provider.SetupSourceFor<MySettings>(source3); // fails

Requires: main module.

Settings models can be printed in JSON or YAML formats to generate configuration file examples.

var printSettings = new PrintSettings 
{
    Format = PrintFormat.Json
};

var defaultSettings = new MySettings();

var printed = ConfigurationPrinter.Print(defaultSettings);

Console.Out.WriteLine(printed);

With sources passed on per-call basis:

Get method behavior

• Always returns the most recent version of settings (updates may happen in background):

  • Call Get on every settings access for "hot" configuration;

  • Call Get once and cache the result for "cold" configuration;

Related pages

Requires: main sources module.

A source can be scoped just like settings nodes can. Resulting source's data is exactly base source's data scoped to given path:

var baseSource = new JsonFileSource("settings.json");
var scopedSource = baseSource.ScopeTo("secrets");
var scopedTooFarSource = baseSource.ScopeTo("timeouts", "unknown-section");

Data in baseSource:

{
    "Timeouts":
    {
        "DbTimeout": "20 seconds"
    },
    "Secrets":
    {
        "ApiKey": "xxxx-xxxx-xxxx"
    } 
}

Data in scopedSource:

{
    "Secrets":
    {
        "ApiKey": "xxxx-xxxx-xxxx"
    }
}

Data in scopedTooFarSource:

{
}

Related pages

Requires: abstractions module.

By default all settings are optional; that is, absence of relevant data in the source results in default values during binding and does not produce errors.

Some parts of configuration may be crucial to the application to the point that it's pointless to start without them being initialized. These fields and properties should be annotated with [Required] attribute:

class MySettings 
{
    [Required]
    public string DbConnectionString { get; }
    
    [Required]
    public MySecrets Secrets { get; }
}

class MySecrets 
{
    public string ApiKey { get; }
    public string Login { get; }
    public string Password { get; }
}

provider.Get<MySettings>(); // will throw if DbConnectionString or Secrets are not initialized 

Changing defaults

Default behavior can be inverted in the scope of a type with [RequiredByDefault] attribute. Individual fields and properties can then be made optional with [Optional] attribute:

[RequiredByDefault]
class MySettings 
{
    [Optional]
    public TimeSpan Timeout { get; } = TimeSpan.FromSeconds(30);
}

Related pages

Requires: logging module.

See logging documentation for the log interface required here.

var providerSettings = new ConfigurationProviderSettings();

providerSettings = providerSettings.WithSettingsLogging(log);

var provider = new ConfigurationProvider(providerSettings);

Requires: abstractions module.

By default settings are subject to logging, which is generally not appropriate for secrets. This can be fixed either by disabling logging entirely on the configuration provider or by annotating fields and properties of the model with [Secret] attribute:

class MySettings 
{
    [Secret]
    public MySecrets Secrets { get; } = new MySecrets();
    
    public TimeSpan Timeout { get; } = TimeSpan.FromSeconds(30);
    
    [Secret]
    public string EncryptionKey { get; }
}

class MySecrets 
{
    public string ApiKey { get; }
    public string Login { get; }
    public string Password { get; }
}

Related pages

Requires: main module.

One can subscribe to settings updates for a type with configuration provider's Observe method.

With prior assignment of sources:

provider.Observe<MySettings>().Subscribe(newSettings => {});

With sources passed on per-call basis:

provider.Observe<MySettings>(new JsonFileSource("settings1.json"))
    .Subscribe(newSettings => {});

Temporary subscriptions should be disposed of as they might hold on to resources in sources:

var subscription = provider.Observe<MySettings>().Subscribe(OnNewSettings);

using (subscription)
{
    // ...
}

Observe method behavior

• OnError and OnCompleted notifications are never produced. Only successful settings updates are propagated to the observers. This means that there will be no notifications if initial attempt to provide settings fails with an error and no further data updates are published by the source.

  • The only way to notice errors when using Observe is to enable error logging.

• The subscription is not guaranteed to immediately produce a notification. The first notification may be delayed due to data not having been fetched from the source yet. However, once a valid settings instance has been observed, all new observers receive a notification with current actual settings upon subscription. This notification is published on a background thread, so don't count on it being delivered after Subscribe call completes.

Best practices

It's recommended to obtain initial settings instance with Get method before subscribing to updates with Observe. This practice ensures correct error propagation, warms up the cache and eliminates situations where the settings are not ready yet on access attempt.

private volatile MySettings settings;
 
public Task InitializeAsync(IConfigurationProvider provider)
{
    OnSettingsUpdated(settings = provider.Get<MySettings>());
         
    provider.Observe<MySettings>()
      .Subscribe(newSettings => OnSettingsUpdated(settings = newSettings));
 
    return Task.CompletedTask;
}
 
private void OnSettingsUpdated(MySettings settings) 
{
    // ... 
}

Related pages

Requires: logging module.

See error handling for cases where this logging is useful.

See logging documentation for the log interface required here.

var providerSettings = new ConfigurationProviderSettings();

providerSettings = providerSettings.WithErrorLogging(log);

var provider = new ConfigurationProvider(providerSettings);

Requires: main sources module.

Multiple configuration sources can be combined into a single composite source whose data is produced by merging the settings trees provided by original sources.

var source1 = new JsonStringSource(...);
var source2 = new YamlStringSource(...);
var source3 = new XmlStringSource(...);

var combined = source1.CombineWith(source2, source3);

// combined == Merge(source1, source2, source3)

// combined.Data == Merge(Merge(source1.data, source2.data), source3.data)

Order of the sources is important: settings from sources that come later in the list have greater priority, hence the rightmost source should be the most specific/significant. In other words, merging is performed in a left-to-right fashion.

Updates are pushed to subscribers each time one of the component sources generates new settings.

Related pages