Configuration: providers and hierarchical settings
Development (2026-10-29): Neo.Configuration composes ordered configuration sources behind provider-independent contracts. Later providers take precedence; colon paths provide sections and immediate child enumeration. Sections remain live after writes and explicit reloads. In-memory and optional JSON file providers supply the initial implementation.
Consumer contracts live in Neo.Configuration.Abstractions. The implementation
assembly supplies the default builder/root/sections, memory source/provider and
AddConfiguration integration with DI abstractions. The container borrows the
configuration root; the application controls its lifetime.
The integrated sample reads appsettings.json to choose a greeting name and JSON localization directory, then injects Configuration alongside typed logging and localization into its service.
See the configuration API reference for members, ownership and null semantics. The JSON file provider accepts comments, trailing commas and a UTF-8 BOM, like Microsoft.Extensions.Configuration. It reads up to 1 MiB with a maximum nesting depth of 64. Change notifications, binding and options remain future work; access is synchronous and serialized.
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
Watching configuration files (development)
A single Subscribe callback receives the FileSystemNotification union.
The standalone FileSystemWatcher sample
shows debounced reload with failure preservation using the current JSON provider.
That sample demonstrates application-controlled policy. AddJsonFile now also offers
built-in opt-in reload, described below.
See the watcher contract.
Reload appsettings.json
Automatic reload is opt-in in the development API:
_ = builder.AddJsonFile("appsettings.json", reloadOnChange: true)
The watcher reloads after a 250 ms quiet period. Existing sections and injected
Configuration instances see new values. Failed background reads/parsing retain the
last valid data and populate the provider's LastReloadError; a successful reload
clears it. Dispose the root to stop watching. Optional files use optional: true;
deleting one clears its values. Keep the app's asynchronous event loop running.
Try the integrated DI sample
with --watch; it reads the greeting name repeatedly for 30 seconds.
See the complete reload contract.
The sample returns Task<Result<(), ServiceError>> from Main, so service failures
propagate with ?. See entry-point results and exit codes.