Configuration with Optionary
Configuration with Optionary
Section titled “Configuration with Optionary”Dovetail’s options binding and configuration schema moved to their own package, Optionary. Optionary’s source generator
reads an options type and produces a reflection-free binder that registers it as IOptions<T>, and a JSON Schema fragment that its
build merges into each application’s appsettings.schema.json for editor completion and validation. Optionary works without
Dovetail; Dovetail registers what Optionary generates for you and tells it which projects are applications.
Dovetail doesn’t depend on Optionary. Add it to the projects that declare options:
<ItemGroup> <PackageReference Include="Optionary" Version="0.1.1" /></ItemGroup>Then put [Optionary] on the options type, or [assembly: Optionary<T>("Section")] for a type you don’t own:
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> public string Message { get; set; } = "Hello";}Consume it the usual way, with IOptions<GreetingsOptions>, IOptionsSnapshot<T> or IOptionsMonitor<T>. Section names, key styles,
validation, supported types, the schema and editor setup are all described in Optionary’s documentation.
The SdkSample.Greetings
project is a working example.
What Dovetail adds
Section titled “What Dovetail adds”- The joint. Optionary emits
OptionaryConfigurationOptions.AddOptionaryConfigurationOptions(services)in the project’sRootNamespace. When an assembly declares at least one[Optionary]type, Dovetail’s generator exports a joint that calls it, listed first so options are bound before other joints configure them in code. Every host that references the assembly registers its options, so there is nothing to call. Below C# 12 Dovetail emits nothing and reportsDT0006. - Host detection. An application the Dovetail SDK detects (ASP.NET Core, the generic host, Blazor
WebAssembly, MAUI, Uno) is an Optionary schema host: Dovetail sets
OptionarySchemaHosttotrueunless the project set it. - Embedded hosts. A host that embeds its configuration (
DovetailEmbedConfiguration, which the SDK sets for MAUI and Uno applications) keeps the schema inobj/for editors: Dovetail setsOptionarySchemaCopyToOutputtofalse. - ZeroAlloc.
DovetailEnableZeroAllocValidation=falsealso setsOptionaryZeroAllocValidationtofalse, so Optionary doesn’t callValidateWithZeroAlloc()either. See ZeroAlloc. - Serilog.
Joinery.Dovetail.Serilogships a schema fragment for theSerilogsection, which Optionary merges into an application’s schema like any other. See Serilog. - The schema endpoint, below.
- Configuration files. Shipping a library’s
appsettingsfiles in JSON, YAML or TOML stays in Dovetail: see Configuration Files.
These hook properties have no effect in a project that doesn’t reference Optionary, and Dovetail adds no warnings about it: an application without Optionary just has no schema.
The schema endpoint
Section titled “The schema endpoint”An application can also serve the schema Optionary writes, for tools that read it over HTTP. This needs an ASP.NET Core application that references Joinery.Dovetail.Hosting, and is off by default:
<PropertyGroup> <DovetailConfigurationSchemaEndpoint>true</DovetailConfigurationSchemaEndpoint> <!-- Optional: serve it only in these environments --> <DovetailConfigurationSchemaEndpointEnvironments>Development;Staging</DovetailConfigurationSchemaEndpointEnvironments></PropertyGroup>| Property | Default | Effect |
|---|---|---|
DovetailConfigurationSchemaEndpoint | off | true generates a joint that maps the endpoint. Only projects with OutputType Exe or WinExe that reference ASP.NET Core and Joinery.Dovetail.Hosting get it. |
DovetailConfigurationSchemaEndpointEnvironments | every environment | A semicolon-separated list of environment names (Development;Staging, compared ignoring case). The endpoint is mapped only when the host environment is one of them. |
DovetailConfigurationSchemaEndpointSourceFallback | true except below | Whether the project’s obj/ directory is compiled into the application as a place to look for the schema. By default it is, except in publish builds and ContinuousIntegrationBuild builds, so a build machine path isn’t shipped. false never embeds it. |
The route is GET /.well-known/dovetail/configuration-schema:
- It looks for
appsettings.schema.jsonin the application’s output directory first, then in the embeddedobj/fallback directory, which is how it works when run from source with no copy beside the assembly. A published application serves the copy published with it. - The response is
application/schema+jsonwith a strongETagandCache-Control: no-cache. A request with a matchingIf-None-Matchgets304 Not Modified. The file is re-read when it changes on disk. - It answers
404when neither location has the file, which is always the case in an application that doesn’t reference Optionary.
Point a mapping at the URL, for example "url": "http://localhost:5000/.well-known/dovetail/configuration-schema" in
json.schemas.
To map it yourself, call the extension on the WebApplication (or any IEndpointRouteBuilder) instead of setting the
property. Joinery.Dovetail.Hosting emits it into every ASP.NET Core project that references it, as an internal type. Both arguments are optional, and the method returns null when environments excludes the current
environment:
using Joinery.Dovetail.Hosting;
app.MapDovetailConfigurationSchema(fallbackDirectory: null, environments: "Development") ?.RequireAuthorization();Upgrading from Dovetail 0.6
Section titled “Upgrading from Dovetail 0.6”This is a clean break: nothing old keeps working alongside the new names. Add the Optionary package to every project that declares
configuration, then rename:
| Dovetail 0.6 | Optionary |
|---|---|
Joinery.Dovetail.Attributes.DovetailConfigurationAttribute | Optionary.OptionaryAttribute |
Joinery.Dovetail.Attributes.DovetailConfigurationAttribute<T> | Optionary.OptionaryAttribute<T> |
Joinery.Dovetail.Attributes.ConfigurationKeyStyle | Optionary.ConfigurationKeyStyle (same values) |
DovetailConfigurationOptionsExtensions.AddDovetailConfigurationOptions<T> | OptionaryServiceCollectionExtensions.AddOptionaryOptions<T> |
Assembly metadata prefix Dovetail.ConfigurationSchema.v1: | Optionary.Schema.v1: |
DovetailConfigurationSchema | OptionarySchema |
DovetailConfigurationSchemaHost | OptionarySchemaHost |
DovetailConfigurationSchemaStrict | OptionarySchemaStrict |
DovetailConfigurationSchemaIncludeSchemaStore | OptionarySchemaIncludeSchemaStore |
DovetailConfigurationSchemaRequired | OptionarySchemaRequired |
DovetailConfigurationSchemaVisualStudio | OptionarySchemaVisualStudio |
DovetailScaffoldEditorSettings | OptionaryScaffoldEditorSettings |
DovetailEditorSettingsDirectory | OptionaryEditorSettingsDirectory |
DovetailConfigurationReferenceDocumentation | OptionaryReferenceDocumentation |
AdditionalFiles metadata DovetailReferenceDocumentation | OptionaryReferenceDocumentation |
DT0007–DT0016, DT0018 | OPT0002–OPT0012 (diagnostics) |
- A library packed with Dovetail 0.6 or earlier carries
Dovetail.ConfigurationSchema.v1:fragments, which Optionary doesn’t read. Its sections are missing from the merged schema until it is rebuilt with Optionary. Binding is unaffected for libraries you rebuild:[DovetailConfiguration]no longer compiles, so nothing is lost silently. DovetailEnableZeroAllocValidation,DovetailEmbedConfigurationand theDovetailConfigurationSchemaEndpoint*properties keep their names: they are Dovetail’s.- The generated joint is now
OptionaryConfigurationOptionsJoint; nothing should refer to it by name.