Key styles
A declaration’s key style picks how the keys of its options type, and of everything nested in it, are spelled. It is
set per declaration with KeyStyle, on [Optionary] and on [assembly: Optionary<T>]. There is no assembly-wide or
MSBuild default.
[Optionary(KeyStyle = ConfigurationKeyStyle.Underscore)]public class HttpClientOptions // section "http_client"{ public int MaxFileSizeMb { get; set; } // key "max_file_size_mb" public RetryPolicy Retry { get; set; } = new(); // "retry:max_attempts" through RetryPolicy.MaxAttempts}The five styles
Section titled “The five styles”ConfigurationKeyStyle |
The key is | MaxFileSizeMb |
HTTPServer |
HttpClientOptions section |
|---|---|---|---|---|
Undefined (default) |
The declared name exactly as written. | MaxFileSizeMb |
HTTPServer |
HttpClient |
Pascal |
The declared name with its first letter upper-cased. | MaxFileSizeMb |
HTTPServer |
HttpClient |
Camel |
Lower camel case (JsonNamingPolicy.CamelCase). |
maxFileSizeMb |
httpServer |
httpClient |
Dash |
Lower-case words joined with - (KebabCaseLower). |
max-file-size-mb |
http-server |
http-client |
Underscore |
Lower-case words joined with _ (SnakeCaseLower). |
max_file_size_mb |
http_server |
http_client |
What the style changes
Section titled “What the style changes”Undefinedrespells nothing. The binder, the schema’s keys and the derived section path use the names as declared. Configuration keys ignore case, somaxfilesizemb,MaxFileSizeMbandMAXFILESIZEMBare the same key. Dashes and underscores are other characters, though:max-file-size-mbdoes not matchMaxFileSizeMb.Pascalis explicit. C# property names already start in upper case, so for themUndefinedandPascalare the same. They differ for a member declared asmyKey: it staysmyKeyunderUndefinedand becomesMyKeyunderPascal.- What it covers. The key of every bound property and constructor parameter of the options type and of every object type nested in it, in lists and dictionary values too. The generated binder reads those keys, and the schema uses them for its properties, its case-insensitive twins and the strict key check.
- What it leaves alone. Dictionary keys, enum values and other data are never restyled, and neither is an explicit
section path:
"Http:Retry"is used as written. - Word splitting is
System.Text.Json’s.HTTPServerbecomeshttpServer,http-serverandhttp_server;Http2Enabledbecomeshttp2Enabled,http2-enabledandhttp2_enabled. - An explicit key name always wins.
[ConfigurationKeyName]is used verbatim, in every style. - Derived section paths follow the style, after the suffix is removed:
HttpClientOptionsisHttpClient,httpClient,http-clientandhttp_client.
Case versus letters
Section titled “Case versus letters”Because keys ignore case, Camel against Undefined or Pascal only changes the spelling the schema suggests:
maxFileSizeMb and MaxFileSizeMb bind the same value. Dash and Underscore change the characters the binder reads: a
value written as MaxFileSizeMb no longer binds (max-file-size-mb or max_file_size_mb does), and the schema only
accepts those keys, in any case.
One spelling per type
Section titled “One spelling per type”The binder is generated once for each type. A type reached from sections that spell its keys differently, such as a
RetryOptions used by a camel section and a dash section, can’t be bound correctly for both. The later declaration is
reported as OPT0011 and contributes nothing.
- The comparison is of the effective keys, not the style names.
UndefinedandPascaldon’t conflict on ordinary names, which spell the same keys, but do on a member declared in lower case. - Fix it by using the same
KeyStylefor every section that reaches the type, or by giving the shared type[ConfigurationKeyName]attributes. A type whose keys don’t depend on the style isn’t a conflict. - Declarations with
RegisterOptions = falsebind nothing, so they can’t conflict.