Classes and structs

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

Binding nodes to models

Make settings required

Make settings secret

Use name aliases

Apply custom binders