Skip to content

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.

  • The joint. Optionary emits OptionaryConfigurationOptions.AddOptionaryConfigurationOptions(services) in the project’s RootNamespace. 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 reports DT0006.
  • 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 OptionarySchemaHost to true unless 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 in obj/ for editors: Dovetail sets OptionarySchemaCopyToOutput to false.
  • ZeroAlloc. DovetailEnableZeroAllocValidation=false also sets OptionaryZeroAllocValidation to false, so Optionary doesn’t call ValidateWithZeroAlloc() either. See ZeroAlloc.
  • Serilog. Joinery.Dovetail.Serilog ships a schema fragment for the Serilog section, which Optionary merges into an application’s schema like any other. See Serilog.
  • The schema endpoint, below.
  • Configuration files. Shipping a library’s appsettings files 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.

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>
PropertyDefaultEffect
DovetailConfigurationSchemaEndpointofftrue 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.
DovetailConfigurationSchemaEndpointEnvironmentsevery environmentA semicolon-separated list of environment names (Development;Staging, compared ignoring case). The endpoint is mapped only when the host environment is one of them.
DovetailConfigurationSchemaEndpointSourceFallbacktrue except belowWhether 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.json in the application’s output directory first, then in the embedded obj/ 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+json with a strong ETag and Cache-Control: no-cache. A request with a matching If-None-Match gets 304 Not Modified. The file is re-read when it changes on disk.
  • It answers 404 when 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();

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.6Optionary
Joinery.Dovetail.Attributes.DovetailConfigurationAttributeOptionary.OptionaryAttribute
Joinery.Dovetail.Attributes.DovetailConfigurationAttribute<T>Optionary.OptionaryAttribute<T>
Joinery.Dovetail.Attributes.ConfigurationKeyStyleOptionary.ConfigurationKeyStyle (same values)
DovetailConfigurationOptionsExtensions.AddDovetailConfigurationOptions<T>OptionaryServiceCollectionExtensions.AddOptionaryOptions<T>
Assembly metadata prefix Dovetail.ConfigurationSchema.v1:Optionary.Schema.v1:
DovetailConfigurationSchemaOptionarySchema
DovetailConfigurationSchemaHostOptionarySchemaHost
DovetailConfigurationSchemaStrictOptionarySchemaStrict
DovetailConfigurationSchemaIncludeSchemaStoreOptionarySchemaIncludeSchemaStore
DovetailConfigurationSchemaRequiredOptionarySchemaRequired
DovetailConfigurationSchemaVisualStudioOptionarySchemaVisualStudio
DovetailScaffoldEditorSettingsOptionaryScaffoldEditorSettings
DovetailEditorSettingsDirectoryOptionaryEditorSettingsDirectory
DovetailConfigurationReferenceDocumentationOptionaryReferenceDocumentation
AdditionalFiles metadata DovetailReferenceDocumentationOptionaryReferenceDocumentation
DT0007–DT0016, DT0018OPT0002–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, DovetailEmbedConfiguration and the DovetailConfigurationSchemaEndpoint* properties keep their names: they are Dovetail’s.
  • The generated joint is now OptionaryConfigurationOptionsJoint; nothing should refer to it by name.