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.