Sondor.Options
2.1.0
Prefix Reserved
dotnet add package Sondor.Options --version 2.1.0
NuGet\Install-Package Sondor.Options -Version 2.1.0
<PackageReference Include="Sondor.Options" Version="2.1.0" />
<PackageVersion Include="Sondor.Options" Version="2.1.0" />
<PackageReference Include="Sondor.Options" />
paket add Sondor.Options --version 2.1.0
#r "nuget: Sondor.Options, 2.1.0"
#:package Sondor.Options@2.1.0
#addin nuget:?package=Sondor.Options&version=2.1.0
#tool nuget:?package=Sondor.Options&version=2.1.0
Sondor.Options
Options bound from a configuration section by convention and validated when the host starts. A section can be required
or optional, so a feature can switch on by being configured. It is the standard IOptions pattern with a few decisions
made for you, so every service in a fleet configures itself the same way.
dotnet add package Sondor.Options
services.AddSondorOptions<DatabaseOptions>() // section "DatabaseOptions", required
.Validate(options => options.Timeout > 0, "Timeout must be positive.");
services.AddSondorOptions<ExportOptions>("Features:Export", SectionRequirement.Optional); // on when "Features:Export" is configured
AddSondorOptions returns the framework's OptionsBuilder<T>, so Validate, ValidateDataAnnotations, PostConfigure and the
rest chain as usual. For FluentValidation use Sondor.Options.FluentValidation. The options type needs a public parameterless
constructor (the framework creates it, then binds the section onto it); init properties and records with them work.
What it does
- The section is named after the type unless you name it.
Messaging:Brokerstyle paths work. - The host does not start with bad options. Validation runs at startup (
ValidateOnStart), not at first use. - A required section that is missing fails with its name (
The configuration section 'DatabaseOptions' is required ...), instead of silently binding a default object. IOptions<T>,IOptionsSnapshot<T>andIOptionsMonitor<T>are all available and behave as documented by Microsoft.
Optional sections: opt in by configuration
A section is configured when it has at least one key or value. "Feature": {} is not; "Feature": { "Enabled": true } or
the environment variable Feature__Enabled=true is.
| Required | Optional | |
|---|---|---|
| Section missing | Startup fails, naming the section | Nothing fails; no validation runs; options are a default instance |
| Section there, invalid | Startup fails | Startup fails: switching a feature on with a bad value is an error |
Two ways to use it, for two questions.
Should this feature's services exist at all? Ask while registering:
if (builder.Configuration.HasSondorSection<ExportOptions>("Features:Export"))
{
services.AddSondorOptions<ExportOptions>("Features:Export");
services.AddExporter();
}
This reads the configuration once, at startup.
Is it on right now? Register it as optional and ask ISondorOptionsState<T>, which reads the live configuration:
public sealed class Sink(IOptionsMonitor<ExportOptions> options, ISondorOptionsState<ExportOptions> state)
{
public void Write(string line)
{
if (!state.IsConfigured) return; // the feature is off
// use options.CurrentValue
}
}
Configuration that changes while the service runs
Azure App Configuration, a mounted file or any provider that reloads works: the options follow through IOptionsMonitor<T>
(CurrentValue, OnChange) and through IOptionsSnapshot<T> (the next scope). With Azure App Configuration, register the
sentinel key as the refresh trigger as usual (ConfigureRefresh(refresh => refresh.Register("Sentinel", refreshAll: true))):
when the sentinel changes, the provider reloads, and the options are rebuilt and validated once for that change.
A bad change does not take the service down. The framework's behaviour is that, after a reload into invalid options,
IOptionsMonitor<T>.CurrentValue throws for every reader until someone fixes the configuration, and the exception also surfaces
from the code that triggered the refresh. Here, by default, an invalid change is rejected: the options last found valid stay
in use, and a warning is logged with the reason (category Sondor.Options, never the values). The next valid change applies.
That covers a failed validator, a value that does not convert ("ten" for an int) and a required section that disappears.
services.AddSondorOptions<DatabaseOptions>(onInvalidReload: InvalidReloadBehavior.Fail); // the framework's behaviour
Startup is always strict, whichever you choose: there is nothing valid to keep yet. Watch for the warning in your logs, because a rejected change means the service is running on older settings than the store holds.
IOptions<T> is fixed when first read, as always; use IOptionsMonitor<T> or IOptionsSnapshot<T> for settings that should change.
Notes
- Named options of the same type (
services.Configure<T>("name", ...)) are not tied to the section and behave as the framework's do. - Calling
AddSondorOptionstwice for one type: the last call decides the requirement and the reload behaviour. - Depends only on Microsoft's
Microsoft.Extensions.Options.ConfigurationExtensionsandLogging.Abstractions.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Options (>= 10.0.15)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.15)
-
net11.0
NuGet packages (7)
Showing the top 5 NuGet packages that depend on Sondor.Options:
| Package | Downloads |
|---|---|
|
Sondor.Translations
Sondor translations is aims to provide an easy solution to managing translations, offering easy to use solutions for static and dynamic translations. |
|
|
Sondor.Logging.Loki
The Sondor Loki package, provides a simple and easy to use way to write logs to an instance of Grafana Loki. |
|
|
Sondor.Cache.Redis
Package Description |
|
|
Sondor.Tracing.OpenTelemetry
The Sondor Tracing Open Telemetry package, simplifies adding tracing to a .NET solution. Adding support to write traces to a configured Open Telemetry instance. |
|
|
Sondor.Mediator
The Sondor Mediator package provides common, useful behaviors, request types and extensions for the Mediatr package. |
GitHub repositories
This package is not used by any popular GitHub repositories.