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.
On the type: [Optionary]
Section titled “On the type: [Optionary]”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.
On the assembly: [assembly: Optionary<T>]
Section titled “On the assembly: [assembly: Optionary<T>]”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).
The section path
Section titled “The section path”| 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
Greetingsandgreetingsare 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 calledOptions) is rejected withOPT0003. Give it a path.
What can be declared
Section titled “What can be declared”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.
One section per type
Section titled “One section per type”[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
Tin two assembly attributes isOPT0010too.
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.
Attribute properties
Section titled “Attribute properties”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.