.NET › Configuration & Options

How does configuration hot-reload work with reloadOnChange for appsettings.json, and what are its limitations?

Advanced

Answer

When appsettings.json is registered with reloadOnChange: true (the default), a file system watcher detects changes to the file and triggers IConfiguration to reload its values in-memory without an application restart -- code using IOptionsSnapshot<T> or IOptionsMonitor<T> automatically picks up the new values, but IOptions<T> (computed once, cached forever) does not, and structural changes requiring different binding (like adding a new required section) may not always propagate cleanly to already-running dependent objects.
builder.Configuration.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);

// A service using IOptionsMonitor will see updated values automatically:
public MyService(IOptionsMonitor<FeatureSettings> monitor) {
    monitor.OnChange(settings => _logger.LogInformation("Config reloaded: {Settings}", settings));
}
Real-world example An ops team updates a feature toggle percentage directly in a mounted ConfigMap-backed appsettings.json file in a running Kubernetes pod, and the application picks up the change within seconds via hot-reload, without needing to restart the pod.

Common follow-ups: Why doesn't IOptions<T> reflect hot-reloaded changes?;What are the risks of enabling hot-reload for security-sensitive settings?