Skip to content
RocketSurgeonsGuildPublic

Latest commit

 

History

46 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Optionary

Strongly-typed, AOT-safe configuration options for .NET: a reflection-free options binder and per-application JSON Schema for editor completion, generated from your options types.

It ships as one package, Optionary: the [Optionary] attribute, the source generator, the binder and the schema build. Optionary reads whatever IConfiguration holds and adds no configuration providers of its own; use Microsoft's JSON provider or any other IConfigurationSource for the files.

github-release-badge github-license-badge github-build-badge nuget-Optionary-badge

Documentation: https://rocketsurgeonsguild.github.io/Optionary/

Getting started

Add the package:

dotnet add package Optionary

Put [Optionary] on the class that holds a section's values. The section name is the type name without its Options suffix:

using System.ComponentModel.DataAnnotations;
using Optionary;

namespace MyApp;

/// <summary>Options for the greetings this application prints.</summary>
[Optionary] // section "Greetings"
public sealed class GreetingsOptions
{
    /// <summary>The text that comes before the name.</summary>
    public string Message { get; set; } = "Hello";

    /// <summary>How many times the greeting is said.</summary>
    [Range(1, 5)]
    public int Repeat { get; set; } = 1;
}

The generator writes an internal AddOptionaryConfigurationOptions() extension method into the project's RootNamespace. Call it once, then read the options through IOptions<GreetingsOptions> as usual:

using MyApp;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddOptionaryConfigurationOptions();

Building an application writes obj/appsettings.schema.json, merged from its own options types and those of every library it references, which editors use for completion and validation of appsettings.json. See Getting started for the editor setup, and the samples for a library, a console app and a web app.

Packages

Package NuGet What it does
Optionary nuget-Optionary-badge The [Optionary] attributes, the source-generated binder and the MSBuild targets for the schema

Building

The toolchain comes from mise: mise install, then mise run build (or dotnet build Optionary.slnx). mise run docs serves the documentation site from docs/.

Origins

Optionary started as the configuration schema and binding feature of Dovetail, and was moved into its own library so it can be used without Dovetail. The code was imported from Dovetail at commit 3f512a33b0 as a snapshot, without its history, and then renamed; Dovetail's history up to that commit is where to look for how it came to be. The migration plan tracks what has moved so far.