Skip to content

With Optionary

Optionary writes an appsettings.schema.json for an application from the configuration sections it and its references declare. Chirograph declares each client’s section, Clients:<ClientName>, so an application that references Optionary gets completion and validation for its clients in appsettings.json. Chirograph never references Optionary, and the registration still reads the section from IConfiguration without it.

Reference Optionary in the project that declares the clients:

<ItemGroup>
<PackageReference Include="Optionary" Version="…" />
</ItemGroup>

Build, and the application’s obj/appsettings.schema.json (copied next to the application) holds a Clients section with one entry per client. A library that declares the clients puts them in its own schema instead, and every application that references it merges them, as Optionary does for any section.

The registration reads the whole section (see Registration). The schema describes:

Key Type Meaning
ConnectionString string The client’s connection string. It wins over the other keys, and set (even empty), ConnectionStrings:<ClientName> is not read.
BaseAddress absolute URI The HttpClient.BaseAddress. A Refitter client needs one, here or in a connection string; a Kiota client falls back to its document’s first server.
Endpoint absolute URI An alias of BaseAddress. Set one or the other, not both.
Timeout TimeSpan, hh:mm:ss The HttpClient.Timeout, written as IConfiguration binds a TimeSpan, such as 00:00:30.
DefaultRequestHeaders object of string values Headers sent with every request, each name with its value.
Resilience boolean, or an object when the project references Microsoft.Extensions.Http.Resilience true adds the standard resilience handler; an object sets its settings (Retry, CircuitBreaker, AttemptTimeout, TotalRequestTimeout, RateLimiter). Only takes effect when the project references Microsoft.Extensions.Http.Resilience.
AllowedHosts array of strings More hosts than the BaseAddress host that may receive the client’s credentials: a host alone allows each of its ports, host:port that port.
Authentication None, ApiKey, Bearer, Basic, ClientCredentials, PrivateKeyJwt, AzureDefault, AzureManagedIdentity, AzureWorkloadIdentity, AzureServicePrincipal How the client authenticates. None, the default, takes the authentication from the container. ClientCredentials, PrivateKeyJwt and the Azure methods need the item’s metadata.
ApiKey string The key of ApiKey.
Key string An alias of ApiKey. Set one or the other, not both.
ApiKeyHeader string The header ApiKey sends the key in, X-Api-Key by default.
ApiKeyQuery string The query parameter ApiKey sends the key in, instead of a header.
Token string The token of Bearer.
Username string The user name of Basic.
Password string The password of Basic.
CertificatePath string A client certificate, for mutual TLS or for PrivateKeyJwt or AzureServicePrincipal to sign with: a PKCS#12 (.pfx, .p12) or PEM file. Not with CertificateThumbprint.
CertificatePassword string The password of the PKCS#12 file, or of its encrypted PEM key.
CertificateKeyPath string The PEM private key, when CertificatePath is a PEM certificate without its key.
CertificateThumbprint string A client certificate in CertificateStore, instead of a file.
CertificateStore <location>/<name> The store of CertificateThumbprint: CurrentUser/My (the default) or LocalMachine/My, say.
ClientId string The client id of ClientCredentials and PrivateKeyJwt, or of the application or user-assigned identity of an Azure method.
ClientSecret string The client secret of ClientCredentials or AzureServicePrincipal, not of PrivateKeyJwt. Keep it out of appsettings.json.
Scope string The scopes a token is asked for, space-separated: optional for ClientCredentials and PrivateKeyJwt, needed by an Azure method.
TokenEndpoint absolute URI The token endpoint of ClientCredentials and PrivateKeyJwt. Not with Authority.
Authority absolute https URI The authority whose discovery document gives the token endpoint of ClientCredentials and PrivateKeyJwt. Not with TokenEndpoint.
Resource string The resource ClientCredentials and PrivateKeyJwt ask for.
ClientCredentialStyle Header, Body How ClientCredentials sends the client id and secret.
TenantId string The tenant of an Azure method, its id or a domain.
{
"Clients": {
"RocketsClient": {
"BaseAddress": "https://rockets.example.com/",
"Timeout": "00:00:30",
"DefaultRequestHeaders": { "X-Api-Key": "…" },
"Resilience": true
}
}
}

Beyond the keys, the schema checks what a validator can see in appsettings.json:

  • Authentication takes only the methods the client allows: None, ApiKey, Bearer and Basic.
  • When Authentication names a method, the keys of the other methods are not allowed, and the keys the method needs are required (Username for Basic). A secret is never required, since it belongs elsewhere.
  • A section without Authentication is not checked against the methods: a connection string can name the method.
  • The secrets (ApiKey, Key, Token, Password, CertificatePassword) say in their description to keep them out of appsettings.json, in user secrets, an environment variable or a vault.
  • ConnectionString is a plain string: a schema cannot check what is inside it. ConnectionStrings:<ClientName> is not described, since Optionary describes the sections the application owns.
  • Neither generator requires BaseAddress: a connection string, in the section or in ConnectionStrings:<ClientName>, can give it, and with service discovery the client has a default address. With service discovery, the description of BaseAddress says it may be a service-discovery address, and gives its default, https+http://<ClientName>.

For each client with a valid ClientName, Chirograph writes the client’s schema when the project builds (a design-time build too), into the client’s folder, and adds an OptionarySchemaFragment item at evaluation whose File is that schema:

<OptionarySchemaFragment Include="Clients:RocketsClient" File="obj/Debug/net10.0/openapi/RocketsClient/RocketsClient.schema.json" />
<OptionarySchemaFragment Include="Clients:RocketsRefitClient" File="obj/Debug/net10.0/openapi/RocketsRefitClient/RocketsRefitClient.schema.json" />

The schema is the client’s own: its descriptions name the client and its generator, and its Authentication lists the methods the client allows. Optionary merges a section that several items or options types declare, so your own fragment for Clients:RocketsClient adds to Chirograph’s.

ChirographOptionarySchema=false turns the items and the schemas off for the project. See Properties.