Settings nodes are the intermediate representation of configuration data and one of the core concepts of the library. Their main purpose is to abstract away various configuration formats (JSON, XML, etc.) so that binding to model classes can be implemented once without regard to the nature of configuration sources being used.

Key points

• A settings node is a tree with string keys and string values in its leaf nodes.

• Configuration sources produce settings nodes as their primary artifacts.

• Binding is the process of converting a settings node to an arbitrary .NET object.

• Settings nodes are implemented in the abstractions module.

• Settings nodes are immutable objects.

Why is it necessary to learn about settings nodes?

Despite being a somewhat internal API used directly only in a handful of advanced scenarios, settings nodes are crucial for a solid understanding of how configuration data translates to objects in C# code via different node types and scoping.

When is there a need to use settings nodes directly?

• Implementation of a custom configuration source;

• Implementation of a custom model binder;

• Transformation of configuration sources

Node types

There are three types of nodes:

• Value nodes, used to hold data;

• Array nodes, used to represent sequences;

• Object nodes, used to represent objects with named properties.

Users are not expected to implement custom node types.

Null node instances represent absence of settings (e.g. a configuration file that does not exist).

Node interface

All node types implement the ISettingsNode interface and have following properties:

All nodes also implement a merge operation.

Representation

All node types implement a JSON-like ToString() method. Its result may look like this for a sample object node with two nested value nodes:

{
   "A": "1",
   "B": "2"
}

This representation is extensively used on the rest of the pages.

Related pages

Vostok.Configuration in a nutshell

Vostok.Configuration is a set of libraries offering configuration tools to .NET applications. It handles fetching configuration data from files or APIs, parsing and converting it to user-defined model classes.

Guiding design principles

• Configuration data sources should be composable regardless of storage formats.

  • It should be easy to combine settings from JSON files, environment variables and custom APIs. This is achieved with configuration source concept and universal settings nodes abstraction.

• "Hot" configuration updates should be easy to leverage.

  • Hot configuration implies handling changes in settings without application restart. This is enabled by explicitly reactive source design and settings provider methods.

• Rich object models should be supported for user convenience.

  • Binding process supports a wide range of primitives, collections, classes, interfaces and employs a number of conventions for arbitrary types (anything with a TryParse method works).

• It should be possible to extend the library with arbitrary data sources and object models.

  • Two major extensions points are custom configuration sources and binders.

Features

• On-demand and subscription-based methods to obtain settings;

• Support for required and secret settings;

• Support for custom settings validation;

• Wide selection of built-in sources;

• Composable binders;

• Sources can be combined, navigated and transformed;

• Integration with Microsoft configuration system;

Guarantees

See obtain / observe settings scenarios, caching and error handling sections for details.

Good starting points

Array nodes are containers used to represent sequences, such as JSON arrays. Each array node contains an ordered list of child nodes. There is no limit to nesting: arrays can contain other arrays and objects. Elements of an array are not required to have names.

Array nodes are typically mapped to ordered collections during binding.

Properties

Equality

Two array nodes are considered equal if their Children sequences are equal elementwise and their names match up to differences in case.

Representation

Array(Value("1"), Value("2)) --> ["1", "2"]
Array(Object(), Object()) --> [{}, {}]
Array(Array(Value("1")), Array(Value("2"))) --> [["1"], ["2"]]

Related pages

Object nodes are containers used to represent objects with named fields/properties. Each object node contains a map of child nodes with their names as keys. There is no limit to nesting: objects can contain other objects and arrays. Elements of an object are required to have non-null names.

Object nodes are typically mapped to arbitrary classes and structs during binding.

Properties

Equality

Two object nodes are considered equal if their Children sequences are equivalent (contain equal elements but may present different order) and their names match up to differences in case.

Representation

Object(Value("A", "1"), Value("B", "2")) --> { "A": "1", "B": "2" }

Related pages

API

Each node type implements a Merge method that accept another node (right in our terms) and an instance of merge options with following properties:

General merging rules

• If both nodes are null, the result is also null.

• If one of the nodes is null, the non-null node wins:

  • left + null --> left

  • null + right --> right

• If nodes are of different types, the right node always wins:

  • value + array --> array

  • array + object --> object

  • object + value --> value

• If nodes are of same type, special rules apply. They are described in the next sections.

Right node always wins: left value + right value --> right value.

Replace style (default) always preserves the right array:

left array + right array --> right array.

Concat style produces an array containing elements from both arrays. All elements from the left array, then all elements from the second one, preserving order inside arrays.

[1, 2] + [2, 3] --> [1, 2, 2, 3]

Union style produces an array containing unique items from both arrays. The order is the same to Concat style.

[1, 2, 3] + [2, 3, 4] --> [1, 2, 3, 4]

Per element style produces an array containing items obtained by merging corresponding items (by index) from both arrays. If merged arrays have different children count, the "tail" of the longer array is preserved as-is.

[1, 2, 6] + [4, 5] --> [4, 5, 6]

Deep style (default) produces an object with union of the children from both nodes, then merges children with same names recursively.

{A:1} + {B:2} --> {A:1, B:2}

{A: {C:1}, B: {D:2}} + {A: {E:3}, B: {F:4}} --> {A: {C:1, E:3}, B: {D:2, F:4}}

Shallow style compares children of both nodes by names. If the sets of names match, regardless of order, merges the pairs of matching children recursively. Elsewise, just prefers to return the right node.

{A:1} + {B:2} --> {B:2}

{A:1} + {A:2} --> {A:2}

Related pages

On each update, triggered either periodically or by an internal event, the source emits a pair: (settings, null) on success or (null, error) on failure. It's not required to deduplicate settings or errors at this level, although it's never wrong to do so.

Sources must never block indefinitely while waiting for data and should rather publish null settings after a short initial timeout.

Sources must be thread-safe and should be designed to support multiple concurrent observers. It is also expected that every new observer would immediately receive a notification with current state upon subscription.

Here are some of the often used source implementations:

Related pages

node {A: 1, B: 2} --> new CustomModel { A = 1, B = 2}

Binders

Overview

Error handling

In case of failure, a complete list of all errors is presented in resulting exception.

Related pages

Here's the simplest way to experience Vostok.Configuration for the first time:

• Install main, abstractions and sources.json modules:

Install-Package Vostok.Configuration
Install-Package Vostok.Configuration.Abstractions
Install-Package Vostok.Configuration.Sources.Json

• Define a settings model class:

class MySettings 
{
    public string Key1 { get; }
    public string Key2 { get; }
}

• Create a JSON file with settings:

{
    "key1": "value1",
    "key2": "value2"
}

• Obtain a model instance with a configuration provider from a file source and print it:

var provider = new ConfigurationProvider();

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

var settings = provider.Get<MySettings>();

Console.Out.WriteLine(ConfigurationPrinter.Print(settings));

Great job! Here are some possible next steps:

• Learn the most basic concepts: settings nodes, sources, binding, provider;

• Explore available modules and source implementations;

• Go over the basic scenarios section.

Description

This library contains core interfaces (IConfigurationSource, IConfigurationProvider), intermediate data model (settings nodes) and attributes used to annotate user models, such as RequiredAttribute.

Source and packages

GitHub repository: vostok/configuration.abstractions

NuGet package: Vostok.Configuration.Abstractions

Install-Package Vostok.Configuration.Abstractions

Cement users should reference this module with the following command:

cm ref add vostok.configuration.abstractions <path-to-project>

Related pages

Description

This library contains an implementation of configuration provider, binding, and a couple of custom configuration primitives (such as DataSize and DataRate).

Source and packages

GitHub repository: vostok/configuration

NuGet package: Vostok.Configuration

Install-Package Vostok.Configuration

Cement users should reference this module with the following command:

cm ref add vostok.configuration <path-to-project>

Related pages

Configuration providers cache bound settings for each (type, source) pair where sources are compared by reference. Caching ensures a solid performance level: only the first Get call is somewhat expensive while all the subsequent ones are extremely cheap. The cache is automatically updated when the underlying source issues new data.

provider.Get<MySettings>(); // may block and incurs binding costs

provider.Get<MySettings>(); // instantly returns a cached object

// ... the source issues a data update ...

provider.Get<MySettings>(); // instantly returns the old cached object

// ... the cache is automatically updated in background...

provider.Get<MySettings>(); // instantly returns an updated cached object

var settings = new ConfigurationProviderSettings 
{
    MaxSourceCacheSize = 100_000
};

var provider = new ConfigurationProvider(settings);

Related pages

Value nodes are key-value pairs with optional keys. They cannot have child nodes and thus are always the leaves of settings node trees. Standalone values are rare: most of the time value nodes can be found inside objects or arrays.

Value nodes are typically mapped to primitive types during binding.

Properties

Equality

Two value nodes are considered equal if their values match exactly and their names match up to differences in case.

Representation

Value("name", "value") --> "value"
Value("name", null) --> <null>

Related pages

Scoping is the operation of navigating a settings node tree by accessing child nodes of objects via names in a case-insensitive manner. A sequence of names resembling a path in the object structure, such as ["property1", "property2"] is called a scope.

Scoping does not work on value and array nodes (always results in null).

Scoping is used to map object fields/properties to nodes of settings tree during binding. It also allows to scope sources — create a source that returns a subtree of settings returned by the original source.

Examples

• {A: 1} scoped to a is just a value of 1.

• {A: 1} scoped to b is null.

• {A: {B: [1, 2]}} scoped to A is {B: [1, 2]}

• {A: {B: [1, 2]}} scoped to [A, B] is [1, 2]

• {A: {B: [1, 2]}} scoped to [A, B, C] is null.

Related pages

Description

Source and packages

Related pages

Description

Source and packages

Related pages

Description

Source and packages

Related pages

Description

Source and packages

Related pages

Description

Source and packages

Related pages

Overview

Methods

Get method

Fetches the newest version of settings of given type:

Observe method

Allows to subscribe for updates of settings of given type:

Overloads

Both Get and Observe methods have 2 variations:

Related pages

Description

This library provides a one-way integration with Microsoft configuration extensions, allowing to inject Vostok sources as MS configuration providers.

Source and packages

GitHub repository: vostok/configuration.microsoft

NuGet package: Vostok.Configuration.Microsoft

Install-Package Vostok.Configuration.Microsoft

Cement users should reference this module with the following command:

cm ref add vostok.configuration.microsoft <path-to-project>

Location: main sources module.

ObjectSource converts an arbitrary object (including anonymous types) to a settings node:

var source = new ObjectSource(new {A = 1, B = 2, C = new[] {1, 2, 3});

Conversion process obeys the following priority list:

• Objects with overridden ToString are converted to value nodes;

• Dictionaries with primitive key types are converted to object nodes;

  • Conversion is performed recursively for keys and values;

• Objects that implement IEnumerable are converted to array nodes;

  • Conversion is performed recursively for sequence elements;

• Everything else is converted to object nodes;

  • Conversion is performed recursively for public instance fields and properties;

Like constant sources, object source does not produce any updates by itself; conversion exceptions are exposed via (null, error) notifications.

Related pages

Description

This library provides an integration with Vostok logging, allowing to log errors and settings updates.

Source and packages

GitHub repository: vostok/configuration.logging

NuGet package: Vostok.Configuration.Logging

Install-Package Vostok.Configuration.Logging

Cement users should reference this module with the following command:

cm ref add vostok.configuration.logging <path-to-project>

Related pages

Location: main sources module.

ConstantSource

A constant source returns a preconfigured settings node and never issues any updates.

var source = new ConstantSource(new ValueNode("value"));

LazyConstantSource

A lazy constant source does the same but defers the node acquisition until first subscription:

var source = new LazyConstantSource(() => new ValueNode("value"));

Errors in the provided delegate are propagated via (null, error) notification. It's guaranteed to execute not more than once.

Practical use

Constant sources are handy for unit testing and may serve as base classes for custom sources.

Related pages

Description

This library contains a source implementation based on HashiCorp Vault secrets.

Source and packages

GitHub repository: vostok/configuration.sources.vault

NuGet package: Vostok.Configuration.Sources.Vault

Install-Package Vostok.Configuration.Sources.Vault

Cement users should reference this module with the following command:

cm ref add vostok.configuration.sources.vault <path-to-project>

Related pages

Location: Sources.Xml module.

XmlStringSource parses well-formed XML documents from in-memory strings and supports manual external updates:

var source = new XmlStringSource("<xml content>")

source.Push("<xml content>") // update with new content

XmlFileSource parses XML files and automatically watches for changes:

var source = new XmlFileSource("settings/config.xml");

A file that does not exist simply leads to a null node, which implies default settings values unless something is explicitly required.

Related pages

Location: main sources module.

EnvironmentVariablesSource converts process environment variables into settings nodes.

var source = new EnvironmentVariablesSource();

Keys with dots, colons and double underscores are treated as hierarchical and get split into segments:

throttling.capacity=50 --> { "throttling": { "capacity": "50" } }
throttling:capacity=50 --> { "throttling": { "capacity": "50" } }
throttling__capacity=50 --> { "throttling": { "capacity": "50" } }

This source is static and never issues data updates.

Related pages

It can be summarized in two simple rules:

• If an error occurs and no correct settings instance has been observed for the requested type thus far, the error is propagated to the calling code, resulting in exceptions from Get method. A subsequent settings update with correct data automatically "heals" future Get calls.

Related pages

Binders convert settings nodes to objects. There are built-in binders for primitives, collections, classes and structs. One can also extend the library by implementing a custom binder.

Related pages

Location: Sources.Yaml module.

YamlStringSource parses well-formed YAML documents from in-memory strings and supports manual external updates:

var source = new YamlStringSource("<yaml content>")

source.Push("<yaml content>") // update with new content

YamlFileSource parses YAML files and automatically watches for changes:

var source = new YamlFileSource("settings/config.yml");

A file that does not exist simply leads to a null node, which implies default settings values unless something is explicitly required.

Related pages

Supported types

Arrays and lists:

• T[]

• List<T>

• IEnumerable<T> (backed by T[])

• IReadOnlyList<T>(backed by T[])

• IReadOnlyCollection<T>(backed by T[])

• ICollection<T> (backed by List<T>)

• IList<T>(backed by List<T>)

Dictionaries:

• Dictionary<TKey, TValue>

• IDictionary<TKey, TValue> (backed by Dictionary)

• IReadOnlyDictionary<TKey, TValue> (backed by Dictionary)

Sets:

• HashSet<T>

• ISet<T> (backed by HashSet)

Collections can have classes, structs and other collections as elements.

Binder requirements

Collections require binders defined for element types (both keys and values in case of dictionaries).

Node requirements

Array or object node. Empty nodes are converted to empty collections.

Null node handling

An empty collection is returned unless explictly required.

Nulls are not valid as dictionary keys.

Error handling

Any element binding failure results in complete collection binding failure.

Comparer customization

A custom element comparer (such as StringComparer.OrdinalIgnoreCase for case-insensitive dictionary keys) can be achieved by wrapping the collection in a custom type and utilizing the constructor binding convention.

Related pages

How it works

The binder starts off by creating an instance of the bound type with default values of public fields and properties (the same way as Activator.CreateInstance does) and then recursively binds the value of every field and property to a corresponding subsection of the settings tree. See binding nodes to models page for a step-by-step illustration of this process.

Fields and properties don't have to be mutable: readonly fields and properties with private setters (or even without one) are fine.

Following members are ignored: indexers, constants, static and non-public fields and properties, computed properties without backing fields.

Nested classes and collections are supported without restrictions.

Settings tree navigation

When binding a field or property value, the settings tree is scoped to the member name. This imposes a requirement to synchronize naming in configuration data provided by sources and models in the application code. In order to bind a model property named Timeout from a section of JSON file, this section must contain a property with the same name (barring case).

Model                             JSON data source

class Settings                    {
{
    TimeSpan Timeout { get; } -------> "timeout": "2 seconds",
    
    int Parallelism { get; }  -------> "parallelism": 32
}                                 }

Name aliases allow to decouple property names from configuration data names.

Required and optional members

By default all fields and properties are treated as optional: they are just left with default values if no data could be found in the settings tree (default values may come from field and property initializers). It's possible to make members required though. Required members with no data in the settings tree cause the binding process to fail and produce an exception.

Model requirements

Model classes must either have a parameterless constructor, a constructor with a single parameter, or have an OmitConstructorsAttribute (which allows creating an uninitialized object, therefore, no default parameters are present).

Binder requirements

Binders are required for all public fields and properties.

Node requirements

Only object nodes are supported.

Related pages

Location: Sources.Json module.

JsonStringSource parses well-formed JSON documents from in-memory strings and supports manual external updates:

var source = new JsonStringSource("<json content>");

​source.Push("<json content>") // update with new content

​JsonFileSource parses JSON files and automatically watches for changes:

var source = new JsonFileSource("settings/config.json");

A file that does not exist simply leads to a null node, which implies default settings values unless something is explicitly required.

Related pages

Primitive types are parsed from string values in value nodes.

Supported types

DataSize and DataRate are custom new types. They also provide factory extensions and operators:

DataSize size = 50.Megabytes();
DataRate rate = size / 2.Seconds();

Parse method convention

There's also support for types that implement Parse or TryParse method with standard signature:

class/struct T 
{
    public static T Parse(string input) { ... }
    
    public static bool TryParse(string input, out T result) { ... }
}

This allows to use arbitrary types with string representation without resorting to implementation of custom binders.

Node requirements

Value node or a container (array/object) node with a single value node child.

Null node handling

Default value for the type is used unless explictly required.

Explicitly specified null string value has the same effect.

Incorrect format handling

Parsing errors arising from incorrect value formats lead to binder failure and result in exceptions, even for optional members (see classes and structs for more context).

Related pages

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

This technique can also be used for additional initialization or settings data preprocessing:

Related pages

It supports 7 syntax options for key-value parameters:

• --key=value

• --key value

• -key=value

• -key value

• /key=value

• /key value

• key=value

Keys with dots (such as a.b.c) are treated as hierarchical and get split into segments:

Multiple occurrences of the same key are merged into arrays.

This source is static and never issues data updates.

Default keys and values

Standalone keys may optionally be supplied with a default value.

Standalone values may optionally be grouped under default key.

Related pages

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

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 module.

Settings can be obtained on-demand with configuration provider's Get method.

With prior assignment of sources:

var settings = provider.Get<MySettings>();

With sources passed on per-call basis:

var settings = provider.Get<MySettings>(new JsonFileSource("settings.json"));

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;

• First call for a type may block or throw exceptions due to source latency, data unavailability or incorrect data format. This behavior persists until a data update remedies the error;

• Once warmed up, subsequent calls never block or throw errors and are extremely cheap due to caching. Future errors are not propagated to the calling code, but can be logged. Get calls return the last seen correct settings object;

Related pages

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

Requires: main module.

The basic recommended way to get most up-to-date settings in the presence of background updates is to use provider's Get method (see the relevant scenario) on each access attempt. However, it's also possible to obtain an inherently dynamic settings object whose properties are updated under the hood. This requires to use an interface as the settings model:

interface IMySettings
{
    string Option1 { get; }
    string Option2 { get; }
    ISubConfig Section { get; }
}

// Get once, use as a singleton:
var hotSettings = provider.CreateHot<IMySettings>(); 

// Properties of the 'hotSettings' object are mutable. 
// They will automatically return most up-to-date values.

Note that in order to get a guaranteed consistent view of the settings without "tearing" (observing a mix of values from before and after update due to a race condition) when using a nested object (section), it's recommended to access a snapshot of this nested object saved in a variable:

var section = hotSettings.Section;

// access a consistent view of 'section` properties

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

Related pages

It's intended use case is self-sufficient configuration in libraries: library authors may not want to force their users to provide an IConfigurationProvider instance each time they're using library classes. Instead, these classes could just obtain a log from the shared property:

By default this property returns a singleton provider with default settings. It can be configured explicitly in the application:

Related pages

This operation allows to effectively disable data updates on a source:

Related pages

Requires: abstractions module.

Name aliases provide alternative keys to look for in settings nodes when performing binding.

They can be applied to fields and properties with a special attribute:

class MySettings 
{
    [Alias("LegacyTimeout")]
    public TimeSpan Timeout { get; }
}

// The property can be initialized from either "timeout" or "legacytimeout" key

It's allowed to assign multiple aliases to a single member:

[Alias("alias1")]
[Alias("alias2")]
public TimeSpan Timeout { get; }

Aliases do not handle ambiguity. If the source returns data with more than one of the lookup keys assigned to a field or property, binding fails with an error.

Ambiguous data examples:
{ "timeout": "...", "alias1": "..." }
{ "alias1": "...", "alias2": "..." }

Related pages

Constraints

There are also built-in validation constraints you can use to create a custom validator. Just inherit your validator class from ConstraintsValidator and override a method returning constraints to be checked:

Here's a list of all currently implemented constraint types:

• NotNullConstraint for arbitrary reference types;

• NotNullOrEmptyConstraint for strings;

• NotNullOrWhitespaceConstraint for strings;

• RangeConstraint, LessConstraint, LessOrEqualConstraint, GreaterConstraint and GreaterOrEqualConstraint for any types that implement IComparable;

• UniqueConstraint to check that a set of field/properties only contains unique values;

Related pages

Creating a binder for a type is just a matter of implementing an interface:

Custom binders can be applied to specific fields and properties or whole types:

Related pages

Related pages

This operation allows to embed source's data into a nested object section:

Related pages

Requires: sources module.

Sources module offers a couple of base classes to assist in implementing custom configuration sources.

ManualFeedSource

For in-memory sources or sources that can update an in-memory one from a remote API.

class MySource : ManualFeedSource<string>
{
    public MySource()
        : base(Parse) { }

    private static ISettingsNode Parse(string input) { ... }
}

var source = new MySource();

source.Push("input1");
source.Push("input2");

// Push method can be used by an internal periodical/event-based update routine.

FileSource

For sources based on local files. Includes automatic reload on file updates.

class MyFileSource : FileSource
{
    public MyFileSource(string filePath)
        : base(new FileSourceSettings(filePath), Parse) { }
        
    private static ISettingsNode Parse(string input) { ... }
}

Related pages

Related pages