Settings nodes

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:

Property	Type	Description
Name	string	Node name. Case-insensitive.
Value	string	Node value. Only present in value nodes.
Children	IEnumerable<ISettingsNode>	Sequence of child nodes in containers: arrays and objects.
this[name]	ISettingsNode	Name-based indexer used to navigate objects (see scoping).

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

Value nodes

Array nodes

Object nodes

Settings nodes merging

Settings nodes scoping

Configuration sources

Binding nodes to models