Skip to content

Declarations

A declaration marks an options type with its section. There are two forms, and a type has exactly one section, so it is declared once.

Put [Optionary] on a class or record you own:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using Optionary;
/// <summary>Options for the greetings this library prints.</summary>
[Optionary]
public sealed class GreetingsOptions
{
/// <summary>What the greeting says before the name.</summary>
[Description("The text that comes before the name, e.g. \"Hello\".")]
public string Message { get; set; } = "Hello";
/// <summary>How many times the greeting is said.</summary>
[Range(1, 5)]
public int Repeat { get; set; } = 1;
}

Records and other immutable types work too; see binding:

[Optionary]
public sealed record FarewellOptions(string Message, [property: Range(0, 5)] int Exclamations);

[Optionary] can’t be repeated on a type.

To declare a type you don’t own, use the generic attribute on the assembly. This declares HostOptions under Hosting:

[assembly: Optionary<HostOptions>("Hosting")]

Repeat the attribute for each type. Descriptions for a type from a package come from the XML documentation file that ships with the package, when there is one (see OptionaryReferenceDocumentation in the MSBuild reference).

Declaration Section path
[Optionary] The type name with one Configuration, Settings, Options or Config suffix removed, spelled in the declaration’s key style: GreetingsOptions is Greetings.
[Optionary("Http:Retry")] The path you give, used as written. : nests sections.
[assembly: Optionary<T>] The same rule as the class form, applied to T.
[assembly: Optionary<T>("Hosting")] The path you give.
  • There is no prefix: a library’s sections sit at the configuration root unless you give a path.
  • Configuration keys ignore case, so Greetings and greetings are the same section.
  • The suffix is matched case-sensitively, and only one is removed.
  • A path that is empty, has an empty segment (A::B), or a type name that would be empty without its suffix (a class called Options) is rejected with OPT0003. Give it a path.

An options type is a class or record class that configuration can create. These are rejected with OPT0002: interfaces, static and abstract classes, structs, enums, open generic types and collections. A type that can’t be created from configuration (no public constructor, several public constructors with parameters and none without, or a constructor parameter that matches no property) is rejected with OPT0006.

A rejected declaration is reported and contributes nothing: no fragment and no registration. The assembly still gets its registration method.

  • [Optionary] and [assembly: Optionary<T>] for the same type is an error, OPT0010, reported on the assembly attribute. The class declaration is the one that produces the fragment and the registration; the assembly attribute produces nothing.
  • Naming the same T in two assembly attributes is OPT0010 too.

At run time each assembly reads only its own sections from the application’s complete IConfiguration. Optionary doesn’t order, de-duplicate or merge sections at run time; the registration method registers an assembly’s types by section path, then type name, and the standard options pipeline does the rest.

Both forms have the same members.

Member Default Effect
Section derived The section path, from the constructor argument. Left out, it is derived from the type name.
KeyStyle Undefined How keys are spelled. See key styles.
RegisterOptions true false only describes the section in the schema. Nothing is registered, so you bind the type yourself (see binding).
ValidateOnStart false Validates the options when the host starts, instead of the first time they are read.

The attributes are [Conditional("CodeGeneration")]: the generator reads them from source, and they never reach the compiled assembly’s metadata.