Getting started
Requirements
Section titled “Requirements”- A project targeting
net10.0ornet11.0. - C# 12 or later. With an older
LangVersionthe generator binds nothing and reportsOPT0001. - A compiler that can load Roslyn 5.0 or later analyzers (the .NET 10 SDK or later). With an older one, the generator isn’t
loaded and the build fails with
OPT1001.
Add the package
Section titled “Add the package”dotnet add package OptionaryThe package carries the runtime library, the source generator and the MSBuild targets that write the schema. Its build assets flow transitively, so a project that references a library built with Optionary merges that library’s fragments into its own application schema.
Declare an options type
Section titled “Declare an options type”Put [Optionary] on the class (or record) that holds the section’s values:
using System.ComponentModel.DataAnnotations;using Optionary;
namespace MyApp;
/// <summary>Options for the greetings this application prints.</summary>[Optionary] // section "Greetings": the type name without its "Options" suffixpublic 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 declarations guide covers explicit section paths, the assembly form for types you don’t own, and the other attribute properties.
Register it
Section titled “Register it”The generator writes a registration method into the assembly: an internal extension method,
AddOptionaryConfigurationOptions(), in a class named OptionaryConfigurationOptions in the project’s RootNamespace. Call it
once on the service collection:
using MyApp; // the project's RootNamespace, where the registration method lives
var builder = Host.CreateApplicationBuilder(args);builder.Services.AddOptionaryConfigurationOptions();Then read the options the usual way, through IOptions<GreetingsOptions>, IOptionsSnapshot<T> or IOptionsMonitor<T>:
public sealed class Greeter(IOptions<GreetingsOptions> options){ public string Greet(string name) => $"{options.Value.Message}, {name}";}The binder is generated code, so nothing here uses reflection. A library calls its own registration method from a public extension method instead; see registering from a library.
Write the configuration
Section titled “Write the configuration”{ "Greetings": { "Message": "Howdy", "Repeat": 2 }}Point your editor at the schema
Section titled “Point your editor at the schema”Build the project once. An application or test project is a host, and its build writes the application schema to
obj/appsettings.schema.json, merged from its own fragments and those of every assembly it references.
- Visual Studio picks it up for
appsettings*.jsonwith no setup. - VS Code needs a mapping in
.vscode/settings.json, which Optionary can write for you: set<OptionaryScaffoldEditorSettings>true</OptionaryScaffoldEditorSettings>. - Rider needs a JSON Schema mapping.
Schema and editors has the details for each.