Development documentation · Some APIs may be unreleased Published release →

Guides

Configuration (development)

Import Neo.Configuration.*. Reference Neo.Configuration.Abstractions for consumer contracts; Neo.Configuration supplies defaults and DI integration. Neither assembly depends on the default DI container.

API Members and behavior
Configuration Mutable [key: string]: string?, GetSection(key), GetChildren(). Missing and explicit null both read null. Set writes every provider; an empty root faults on Set.
ConfigurationSection Configuration plus Key, Path and mutable Value. Nonexistent sections are live objects; GetChildren returns immediate descendants.
ConfigurationRoot Configuration plus Disposable, Providers and Reload(). Default roots load each provider on construction; dispose each disposable registration once per root lifetime.
ConfigurationBuilder Sources snapshot, Add(source) returning the builder, Build() returning an independently owned root.
ConfigurationSource Build(builder) creates a provider owned by the returned root.
ConfigurationProvider Find(key): Optional<string?> distinguishes absence from present null; Set(key,value), Load(), GetChildKeys(parentPath: string?): Sequence<string>. Null parent means root; empty string denotes an empty section path.
ConfigurationEntry Immutable Key and nullable Value, constructed with (key, value).
DefaultConfigurationBuilder Parameterless constructor. Stores sources; Build constructs and loads fresh providers in registration order. Sources returns a snapshot.
DefaultConfigurationRoot Constructor (providers: Sequence<ConfigurationProvider>) copies and owns registrations. Later providers win, including Some(null). Providers returns a snapshot of references. Reload calls each Load. Dispose is idempotent; existing sections share its lifetime.
DefaultConfigurationSection Constructor (root: DefaultConfigurationRoot, path: string); Key is the final segment, Path is the full path, Value/indexer delegate to the root. Child sections are live.
MemoryConfigurationSource Constructor (initialData: Sequence<ConfigurationEntry>) snapshots entries. Build creates a new MemoryConfigurationProvider.
MemoryConfigurationProvider Constructor with initialData; copies key/value data. Find/Set use ordinal-ignore-case keys; repeated keys replace earlier values. Load does nothing, preserving in-memory mutations. GetChildKeys returns sorted distinct immediate keys.
MemoryConfigurationExtensions ConfigurationBuilder.AddInMemoryCollection(initialData) snapshots input and appends a source; returns the builder.
ConfigurationExtensions Configuration.GetConnectionString(name): string? reads ConnectionStrings:name.
ConfigurationSectionExtensions Exists() means non-null Value or at least one child. Empty strings exist; a null-only leaf does not.
ConfigurationServices ServiceCollection.AddConfiguration(configuration): Result<unit, ServiceError> preserves an existing Configuration registration. The supplied instance remains caller-owned.

Paths use :; numeric Int32 child segments sort before text. Values and children are independent. Child sequences are snapshots, while sections reflect current values after writes or reloads. Key comparison follows runtime OrdinalIgnoreCase; Unicode normalization is not applied. No concurrent access is supported.

The integrated sample registers a caller-owned configuration root, reads its localization directory at startup and injects Configuration into GreetingService to select the greeting name. Dispose the container before its borrowed configuration root.

Change tokens, environment/command-line configuration providers, binding and options are not implemented. Load/Set/source faults propagate; no rollback is promised. See design and .NET comparison.

Try it

Build configuration from appsettings.json, then read a colon-delimited key. The file is read during Build; use disposes the root.

Run from samples/extensions, containing this appsettings.json:

{
  // Configuration accepts comments and trailing commas, like Microsoft's provider.
  "Greeting": { "Name": "Ada", },
  "Localization": { "Directory": "resources", },
}
module Examples.Extensions.Introductions.Configuration

import System.*
import Neo.Configuration.*

func Main() -> int {
    let builder: ConfigurationBuilder = DefaultConfigurationBuilder()
    _ = builder.AddJsonFile("appsettings.json")
    use configuration = builder.Build()
    Console.WriteLine(configuration["Greeting:Name"] ?? "world")
    return 0
}

Complete sample project · Build and run instructions

JSON file configuration

Reference the optional Neo.Configuration.Json assembly. AddJsonFile is in Neo.Configuration; provider/source/error types are in Neo.Configuration.Json. The abstractions and base implementation do not reference System.Data.

API Members and behavior
JsonConfigurationExtensions builder.AddJsonFile(path: string, optional: bool = false, reloadOnChange: bool = false) adds a file source. Returns the builder; no I/O until Build. Named arguments may skip optional.
JsonConfigurationSource Constructor (path: string, optional: bool = false, reloadOnChange: bool = false), read-only Path/Optional/ReloadOnChange and Build(builder) producing a fresh provider.
JsonConfigurationProvider Constructor (path: string, optional: bool = false, reloadOnChange: bool = false); Path/Optional/ReloadOnChange, Find, Set, GetChildKeys, Load and Dispose. Relative paths use the working directory. Set changes memory only. Load faults on failure; Reload through the root rereads the file.
JsonConfigurationProvider.TryLoad Returns Result<unit, JsonConfigurationError>. Failed reads/parsing preserve previous values. A missing optional file replaces values with an empty provider.
JsonConfigurationProvider.LoadText Parses supplied text with the same rules and atomic replacement; future Load rereads Path. Returns the same Result.
JsonConfigurationError File(FileReadError), Json(JsonError), Watch(FileSystemWatcherError), Disposed, InvalidRoot and DuplicateKey(string). Duplicate flattened keys compare ignoring case.

Objects use colon keys and arrays numeric segments. Strings decode JSON escapes; numbers retain their text, booleans become True/False, null stays null, empty objects yield null and empty arrays yield an empty string. The root must be an object. The provider accepts line/block comments, trailing commas and an initial UTF-8 BOM, using the public JSON document options. Input is limited to 1 MiB and 64 container levels; there is no fixed value or per-container entry limit. Size/depth/syntax failures preserve prior values; they never truncate input. TryLoad reports File(TooLarge) for oversized files; LoadText reports Json(LimitExceeded). The sample's appsettings.json sets Greeting:Name and Localization:Directory.

Automatic reload

Pass reloadOnChange: true to AddJsonFile or JsonConfigurationProvider/Source. Both optional and reloadOnChange default to false. TryLoad/Load starts a watcher on the parent directory, filtered to the file, before the initial read. The parent must exist even for an optional file; watching rejects empty/wildcard filenames. Changes, deletion, rename/replacement and rescan notifications schedule a read after 250 ms without another notification. Callbacks run on the runtime owner thread; the application must keep its asynchronous event loop alive.

Existing sections and DI consumers read the new values without rebuilding services. LastReloadError: Optional<JsonConfigurationError> records the most recent background failure; successful background loading clears it. Malformed JSON or a missing required file leaves the last valid values intact. Deleting an optional file clears its values. Initial Load still faults; use TryLoad for recoverable setup. LoadText does not start watching. Set changes memory only and does not stop watching.

Dispose stops the timer and watcher permanently and is idempotent. Retained provider values remain readable/mutable, but TryLoad and LoadText return Disposed. Disposing the owning configuration root disposes its providers and invalidates its sections. No reload token or application callback API is introduced in this slice.

The integrated sample's --watch mode observes edits for 30 seconds. The localization directory is read at startup; changing it does not rebuild the localization service. The added parameter changes assembly signatures: rebuild callers against the matching compiler and libraries. Existing source calls remain valid through parameter defaults.