Skip to content

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.csproj
  • appsettings.{ext} becomes MyLibrary.{ext} (appsettings.Production.json becomes MyLibrary.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): the ApplicationName the runtime conventions look for.
  • The files are packed under contentFiles/any/any/configuration/, copied to a same-solution host’s output directory through a ProjectReference, 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 of configuration/).
  • The generated joint loads, in ascending precedence, MyLibrary.{ext}, MyLibrary.{Environment}.{ext} and MyLibrary.local.{ext}. The local layer is never packed, and the SDK warns when no .gitignore at or above the project ignores appsettings.local.* (a *.local.* entry counts too).
  • YAML has two extensions and one joint. It requires MyLibrary.yaml or MyLibrary.yml, whichever the library has, not both, and reads the environment and local layers with either extension, .yaml before .yml in each layer.
  • A file-based app (dotnet run Build.cs) is named after its assembly, Build, without the .cs: its appsettings.{ext} files, next to Build.cs, are copied to its output directory as Build.{ext}, with or without the Dovetail SDK. At run time, though, the configuration joints read the files from next to Build.cs (the directory the .NET SDK names in the EntryPointFileDirectoryPath AppContext 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, unless SetBasePath or SetFileProvider pointed it somewhere else. dotnet run leaves 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, so dotnet run --project MyApp from any directory, or from the application’s project directory, finds every library’s files.
  • A library ships its appsettings.{ext} files as MyLibrary.{ext}, so its joint looks for that name only: an appsettings.{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 next dotnet run without a rebuild. The application is the project the host is named after, its ApplicationName (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 example Dovetail__ConfigurationDirectory=./config or --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. The Dovetail__ConfigurationDirectory environment 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.

A library’s configuration files can be written under either of two names, and both end up in the same place:

Source fileCopied, packed and embedded asIncluded when
appsettings.{ext}, appsettings.{Environment}.{ext}MyLibrary.{ext}, MyLibrary.{Environment}.{ext}appsettings.{ext} exists
MyLibrary.{ext}, MyLibrary.{Environment}.{ext}the same nameMyLibrary.{ext} exists
appsettings.local.{ext} or MyLibrary.local.{ext}MyLibrary.local.{ext}, never packedas 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).

  • JSON, YAML and TOML are supported. Opt in with DovetailEnableConfiguration; YAML is the default format, and DovetailEnableJsonConfiguration or DovetailEnableTomlConfiguration chooses another. Hosts with no file system (MAUI, Uno) read copies embedded in the assembly: DovetailEmbedConfiguration.
PropertyDefaultPurpose
DovetailEnableConfigurationfalseTurns the pipeline on. Existing consumers see no change until it or a format flag is set.
DovetailEnableYamlConfigurationtrue when no other format is setAdds the YAML provider. Setting it to true also enables the pipeline.
DovetailEnableJsonConfigurationfalseAdds the JSON provider. Setting it to true also enables the pipeline, replacing the YAML default.
DovetailEnableTomlConfigurationfalseAdds the TOML provider. Setting it to true also enables the pipeline, replacing the YAML default.
DovetailPackConfigurationtrue, false if not packablePacks the library’s configuration files into the package.
IdSeverityMeaning
DT0019ErrorA project has both appsettings{suffix}.{ext} and {AssemblyName}{suffix}.{ext}, which land on the same file. Reported by the build; keep one.