Configuration Files
Configuration Files
Section titled “Configuration Files”A library’s configuration values ship in its own appsettings files, and the Dovetail SDK takes them to every application that
references it. Binding those values to types, and the JSON Schema editors use, come from
Optionary.
Defaults live in a normal appsettings file in the library. The SDK renames it, packs it, and loads it into the
host’s configuration, where the options binding (Optionary’s, or your own) picks it up:
MyLibrary/├── appsettings.yaml├── appsettings.Development.yaml├── appsettings.local.yaml # never packed, never committed└── MyLibrary.csprojappsettings.{ext}becomesMyLibrary.{ext}(appsettings.Production.jsonbecomesMyLibrary.Production.json), so several libraries can ship their own file into one output directory. The name is the project’s assembly name (AssemblyName, which defaults to the project’s name): theApplicationNamethe runtime conventions look for.- The files are packed under
contentFiles/any/any/configuration/, copied to a same-solution host’s output directory through aProjectReference, and restored from the package otherwise. Either way they land at the root of the output directory, next to the application (the package flattens them out ofconfiguration/). - The generated joint loads, in ascending precedence,
MyLibrary.{ext},MyLibrary.{Environment}.{ext}andMyLibrary.local.{ext}. Thelocallayer is never packed, and the SDK warns when no.gitignoreat or above the project ignoresappsettings.local.*(a*.local.*entry counts too). - YAML has two extensions and one joint. It requires
MyLibrary.yamlorMyLibrary.yml, whichever the library has, not both, and reads the environment and local layers with either extension,.yamlbefore.ymlin each layer. - A file-based app (
dotnet run Build.cs) is named after its assembly,Build, without the.cs: itsappsettings.{ext}files, next toBuild.cs, are copied to its output directory asBuild.{ext}, with or without the Dovetail SDK. At run time, though, the configuration joints read the files from next toBuild.cs(the directory the .NET SDK names in theEntryPointFileDirectoryPathAppContext data), under their source names, so an edit takes effect on the next run without a rebuild. A host or pipeline whose configuration was given a base path or file provider of its own keeps it. - Outside a file-based app, the joints read the files through the host’s own file provider, the one its configuration
uses for
appsettings.json: the host roots it at its content root, unlessSetBasePathorSetFileProviderpointed it somewhere else.dotnet runleaves the content root at the current directory, and Aspire starts a project in its project directory. - A joint that doesn’t find its base file (
MyLibrary.{ext}) there reads its files from the application’s output directory (AppContext.BaseDirectory), where the build copied them. That is where a library’s files always are, sodotnet run --project MyAppfrom any directory, or from the application’s project directory, finds every library’s files. - A library ships its
appsettings.{ext}files asMyLibrary.{ext}, so its joint looks for that name only: anappsettings.{ext}where the host reads files is the application’s. The application’s own joint also looks for its source names (appsettings.{ext}), which it finds in its project directory, so an edit there takes effect on the nextdotnet runwithout a rebuild. The application is the project the host is named after, itsApplicationName(the entry assembly’s name unless the host was given another). - To read the files from another directory, set
Dovetail:ConfigurationDirectory(DovetailSettings.ConfigurationDirectory) in the host’s configuration, for exampleDovetail__ConfigurationDirectory=./configor--Dovetail:ConfigurationDirectory=./config. A relative path is resolved against the current directory. It wins over everything above for the files it holds; a project whose base file it doesn’t hold reads its files from the output directory, so the directory need only hold the files you override. TheDovetail__ConfigurationDirectoryenvironment variable is read directly too, for hosts whose configuration doesn’t read environment variables. - Every host that reads the files from disk (the generic host, ASP.NET Core, ModularPipelines, Uno) picks the
directory in the same order:
Dovetail:ConfigurationDirectory, then the directory of a file-based app’s entry point file, then the host’s own file provider, and each joint falls back to the output directory. Configuration embedded in the application (MAUI and Uno apps) still wins over all of them: a MAUI app always reads its embedded copies, and a browser (WebAssembly) host fetches its files over HTTP.
Naming the source files
Section titled “Naming the source files”A library’s configuration files can be written under either of two names, and both end up in the same place:
| Source file | Copied, packed and embedded as | Included when |
|---|---|---|
appsettings.{ext}, appsettings.{Environment}.{ext} | MyLibrary.{ext}, MyLibrary.{Environment}.{ext} | appsettings.{ext} exists |
MyLibrary.{ext}, MyLibrary.{Environment}.{ext} | the same name | MyLibrary.{ext} exists |
appsettings.local.{ext} or MyLibrary.local.{ext} | MyLibrary.local.{ext}, never packed | as above |
MyLibrary is the assembly name, as above: in a lib.csproj whose AssemblyName is Contoso.Library, Contoso.Library.yaml
is configuration and lib.yaml is an ordinary file, because nothing would load a lib.yaml. A file-based app’s Build.yaml, next
to Build.cs, is included the same way. Files named after the assembly are treated exactly like the appsettings ones: copied
to the output directory, packed under contentFiles/any/any/configuration/, embedded, loaded by the generated joint, and added to a
file-based app’s items. MyLibrary.schema.json and a file-based app’s Build.run.json (its launch profiles) are not
configuration and are left alone. appsettings.local.* doesn’t ignore MyLibrary.local.{ext}, so when one exists the SDK
warns, naming the file, until a .gitignore has MyLibrary.local.* or *.local.*, which covers both.
Each pair of names that would land on the same file, such as appsettings.yaml and MyLibrary.yaml, or
appsettings.Development.yaml and MyLibrary.Development.yaml, fails the build with
DT0019; keep one of them. Different extensions are different files, so appsettings.yaml and MyLibrary.yml
coexist, as do appsettings.yaml and MyLibrary.Development.yaml (which is only included next to a MyLibrary.yaml).
Opting in
Section titled “Opting in”- JSON, YAML and TOML are supported. Opt in with
DovetailEnableConfiguration; YAML is the default format, andDovetailEnableJsonConfigurationorDovetailEnableTomlConfigurationchooses another. Hosts with no file system (MAUI, Uno) read copies embedded in the assembly:DovetailEmbedConfiguration.
| Property | Default | Purpose |
|---|---|---|
DovetailEnableConfiguration | false | Turns the pipeline on. Existing consumers see no change until it or a format flag is set. |
DovetailEnableYamlConfiguration | true when no other format is set | Adds the YAML provider. Setting it to true also enables the pipeline. |
DovetailEnableJsonConfiguration | false | Adds the JSON provider. Setting it to true also enables the pipeline, replacing the YAML default. |
DovetailEnableTomlConfiguration | false | Adds the TOML provider. Setting it to true also enables the pipeline, replacing the YAML default. |
DovetailPackConfiguration | true, false if not packable | Packs the library’s configuration files into the package. |
Diagnostics
Section titled “Diagnostics”| Id | Severity | Meaning |
|---|---|---|
DT0019 | Error | A project has both appsettings{suffix}.{ext} and {AssemblyName}{suffix}.{ext}, which land on the same file. Reported by the build; keep one. |