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

A type that has exactly one constructor with a single argument of a type that can be bound can also be bound with argument injection. This is especially useful for collection customization:

class PerServiceSettings : Dictionary<string, string>
{
    public PerServiceSettings(Dictionary<string, string> dictionary)
        : base(dictionary, StringComparer.OrdinalIgnoreCase)
    {
    }
}

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

class PerServiceSettings
{
    public PerServiceSettings(Dictionary<string, string> data)
    {
        Index = data;
        
        InvertedIndex = Index.ToDictionary(
            pair => pair.Value,
            pair => pair.Key
        );
    }

    public Dictionary<string, string> Index { get; }
    
    public Dictionary<string, string> InvertedIndex { get; }
}

Related pages

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)

Binder requirements

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

Node requirements

Null node handling

Nulls are not valid as dictionary keys.

Error handling

Any element binding failure results in complete collection binding failure.

Comparer customization

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