Samples
The repository’s samples/ folder has three projects
that use Optionary on its own, with Microsoft’s configuration providers and no host framework.
| Project | Shows |
|---|---|
Optionary.Samples.Library |
A library’s declarations, its validator, and the public AddSampleLibrary() that calls the generated registration method. |
Optionary.Samples.Console |
A console host that binds the library’s options from appsettings.json through IOptions<T> and IOptionsMonitor<T>, and prints them on reload. |
Optionary.Samples.Web |
An ASP.NET Core host with a declaration of its own that fails the application at startup when it is invalid (ValidateOnStart). |
Run them
Section titled “Run them”mise run sample:console # prints the bound optionsmise run sample:console --watch # and prints them again when an appsettings*.json file changesmise run sample:web # serves the bound options as JSON on http://localhost:5180Without mise, use dotnet run --project samples/Optionary.Samples.Console (add -- --watch to watch) and
dotnet run --project samples/Optionary.Samples.Web.
The console sample shows layering with Microsoft’s providers: run it with DOTNET_ENVIRONMENT=Development and
appsettings.Development.json overrides the greeting, or set Greetings__Message=Hi to override it from the environment.
The library
Section titled “The library”Optionary.Samples.Library
declares four sections:
GreetingsOptions: the class form,[Optionary], with[Description]and[Range]that reach the schema. SectionGreetings.FarewellOptions: a record. The generated binder calls its constructor. SectionFarewell.RetryPolicyOptions:KeyStyle = ConfigurationKeyStyle.Underscore, so the section isretry_policyand its keys aremax_attemptsanddelay(see key styles).ClockSettings: no attribute of its own, declared with[assembly: Optionary<ClockSettings>("Samples:Clock")], the form for types you can’t annotate (see declarations).
GreetingsOptionsValidator is an [OptionsValidator], which the registration method registers with the library’s options.
AddSampleLibrary() calls the internal, generated AddOptionaryConfigurationOptions(), as
registering from a library describes.
Its build writes the library schema, ConfigurationSchema.json, under obj/. The samples aren’t packable, so CI never
publishes them; to see the file at the package root, run
dotnet pack samples/Optionary.Samples.Library -p:SamplePack=true.
The hosts
Section titled “The hosts”Both applications are hosts, so each build writes obj/appsettings.schema.json, merged from the host’s own declarations and
the library’s, with SchemaStore’s appsettings.json schema for Logging and the other framework sections. The console
sample adds a Console section of its own, and the web sample a Site section with ValidateOnStart = true and its own
validator. The web sample also calls AddOptions<GreetingsOptions>().ValidateOnStart(), to validate a library’s options at
startup when the library didn’t ask for it. Start it with an empty title to see it fail:
Site__Title= dotnet run --project samples/Optionary.Samples.WebThe repository’s checked-in .vscode/settings.json
maps each sample’s appsettings*.json to its schema, with the same json.schemas entries OptionaryScaffoldEditorSettings
writes (see schema and editors). Build the samples once, open the
repository in VS Code, and the files get completion, hover documentation and checks for unknown keys and out-of-range
values.
How they consume Optionary
Section titled “How they consume Optionary”The samples use Optionary from this repository’s source, wired as the package wires itself into a consumer:
samples/Directory.Build.propsimports the package’sbuild/Optionary.props;samples/Directory.Build.targetsreferences the runtime project and the generator as an analyzer, and imports the package’sbuild/Optionary.targetswith the MSBuild tasks built in the repository.
In your own projects, dotnet add package Optionary does all of this (see getting started).