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

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

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

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