# Valiant settings Documentation version: 1. This context contains only this version. Source revision: 34222bb7277ce1a771ae4412d572b56f5eb98237. ## Settings Source: https://valiant.staticnorth.dev/settings/ # Settings with a generated contract Valiant Settings turns strongly typed configuration models into deterministic schemas. Use the same generated metadata for Options binding, validation, documentation, tooling, or the built-in ASP.NET Core settings explorer—without reflection-based assembly scanning. ```csharp using StaticNorth.Valiant.Settings; [ValiantSettings("Payments", configure: true)] public sealed record PaymentSettings { public Uri? Endpoint { get; init; } [ValiantSecret] public string? ApiKey { get; init; } } ``` ## One declaration, several uses | Capability | Result | | --- | --- | | Schema | Model, property, nesting, collection, default, nullability, required, and secret metadata | | Options | Generated section-aware `Configure` registration on opt-in models | | Validation | `IValidateOptions` backed by a generated Valiant validator | | UI | Built-in schema explorer and JSON endpoint with safe secret masking | | Tooling | `IValiantSettingsSchemaProvider` for custom consumers | ## Documentation map - [Quick start](https://valiant.staticnorth.dev/settings/quick-start) - [Runnable samples](https://valiant.staticnorth.dev/settings/samples) - [Schema generation](https://valiant.staticnorth.dev/settings/guides/schema-generation) - [Binding and validation](https://valiant.staticnorth.dev/settings/guides/binding-validation) - [ASP.NET Core UI](https://valiant.staticnorth.dev/settings/guides/aspnetcore-ui) - [Schema API, generation, and diagnostics](https://valiant.staticnorth.dev/settings/reference/schema-api) The [sample catalog](https://valiant.staticnorth.dev/settings/samples) covers every selectable core and ASP.NET Core scenario for schema metadata, binding, validation, and the safe-by-default UI. ## Quick start Source: https://valiant.staticnorth.dev/settings/quick-start # Quick start ## 1. Choose a package ```bash # Schema generation and optional Options binding dotnet add package StaticNorth.Valiant.Settings # Or install a specific integration dotnet add package StaticNorth.Valiant.Settings.AspNetCore dotnet add package StaticNorth.Valiant.Settings.Validation ``` Specific integration packages forward the core runtime, build, and generator assets they depend on. Add multiple integration packages only when the application uses multiple integrations. ## 2. Mark a settings model ```csharp using StaticNorth.Valiant.Settings; [ValiantSettings("Mail", configure: true)] public sealed record MailSettings { public required string Host { get; init; } public int Port { get; init; } = 587; [ValiantSecret] public string? Password { get; init; } } ``` The section path is required. `configure: true` opts this model into generated Options binding; omit it for schema-only metadata. ## 3. Register generated settings ```csharp using StaticNorth.Valiant.Settings.DependencyInjection; builder.Services.AddValiantSettings(builder.Configuration); ``` The generated extension binds opted-in models and registers every generated schema provider. ## 4. Consume the options ```csharp public sealed class MailSender(IOptions options) { private readonly MailSettings _settings = options.Value; } ``` Or enumerate schemas: ```csharp IEnumerable schemas = provider.GetServices(); ``` Next: learn how nested models and collections appear in [Schema generation](https://valiant.staticnorth.dev/settings/guides/schema-generation). ## ASP.NET Core UI Source: https://valiant.staticnorth.dev/settings/guides/aspnetcore-ui # ASP.NET Core UI `StaticNorth.Valiant.Settings.AspNetCore` provides a compact settings explorer and a JSON document backed by generated schema providers. ```csharp using StaticNorth.Valiant.Settings.AspNetCore; using StaticNorth.Valiant.Settings.DependencyInjection; builder.Services.AddValiantSettings(builder.Configuration); var app = builder.Build(); app.MapValiantSettingsUi(); ``` The default routes are: | Route | Purpose | | --- | --- | | `/_valiant/settings` | Interactive schema explorer | | `/_valiant/settings/schemas` | Generated schema JSON document | ## Change the route ```csharp app.MapValiantSettingsUi(options => options.Path = "/admin/settings"); ``` The JSON endpoint follows the prefix at `/admin/settings/schemas`. ## Show current runtime values ```csharp app.MapValiantSettingsUi(options => { options.ShowRuntimeValues = true; }); ``` Runtime values are resolved dynamically from `IOptions` for registered schemas only. If schema-provider registration is disabled, the UI has no generated catalog to display. ## Protect secrets `[ValiantSecret]` properties are masked. Valiant also masks common sensitive names such as `Password`, `Secret`, `Token`, `ApiKey`, `ClientSecret`, and `ConnectionString`. Explicitly permit reveal only when endpoint authorization and hosting policy make it acceptable: ```csharp RouteGroupBuilder settings = app.MapValiantSettingsUi(options => { options.ShowRuntimeValues = true; options.AllowSecretReveal = true; }); settings.RequireAuthorization("SettingsAdministrators"); ``` Secret values remain masked until a user selects reveal. The JSON endpoint accepts `?revealSecrets=true` only when `AllowSecretReveal` is enabled. Masked secret getters are not evaluated. Runtime values are projected through the generated schema: recursive objects beyond the schema boundary become empty objects, and unsupported opaque values become `null`. Options or getter failures return a generic message so exception text cannot expose credentials. Schema responses use `Cache-Control: no-store`, including when secrets are revealed. Direct callers of `ValiantSettingsSchemaDocumentFactory.Create` must also enable both `revealSecrets` and `canRevealSecrets` to reveal values. :::danger Treat the explorer as an administrative endpoint The package does not decide your authorization policy. Protect the returned `RouteGroupBuilder`, especially when runtime values or secret reveal are enabled. ::: Run the default UI, custom authorization, runtime-value masking, and explicit secret-reveal variants from the [Settings sample catalog](https://valiant.staticnorth.dev/settings/samples#aspnet-core-settings). ## Binding and validation Source: https://valiant.staticnorth.dev/settings/guides/binding-validation # Binding and validation ## Generated Options binding Set `configure: true` and register settings once: ```csharp [ValiantSettings("Storage:S3", configure: true)] public sealed record S3Settings { public required string Bucket { get; init; } public string? Region { get; init; } } builder.Services.AddValiantSettings(builder.Configuration); ``` Valiant emits the equivalent section-aware `services.Configure(configuration.GetSection("Storage:S3"))` registration. Schema providers register by default. Disable them when the application only needs binding and validation: ```csharp builder.Services.AddValiantSettings(builder.Configuration, options => { options.RegisterSchemaProviders = false; }); ``` ## Validate Options with Valiant Reference `StaticNorth.Valiant.Settings.Validation` and declare the matching validator: ```csharp [ValiantValidator] public sealed partial class S3SettingsValidator : ValidatorDefinition { public override void Configure(ValidationContext context) { context.Property(settings => settings.Bucket).Required(); context.Property(settings => settings.Region).MaxLength(32); } } ``` Register validators and enable the adapter: ```csharp builder.Services.AddValiantValidators(); builder.Services.AddValiantSettings(builder.Configuration, options => { options.ValidateWithValiant = true; }); ``` Generated settings registration adds `IValidateOptions` for configured settings models. It resolves a matching `IValidator` from DI and translates Valiant errors to normal Options validation failures. ## Require matching validators By default, validation succeeds when no validator is registered. Make missing validators a configuration error: ```csharp builder.Services.AddValiantSettings(builder.Configuration, options => { options.ValidateWithValiant = true; options.RequireValidators = true; }); ``` Only models with `configure: true` receive Options binding and validation adapters. Schema-only models remain metadata contracts. ## Schema generation Source: https://valiant.staticnorth.dev/settings/guides/schema-generation # Schema generation `[ValiantSettings]` is the generator discovery boundary. It produces a deterministic `ValiantSettingsSchema` for the marked type. ```csharp [ValiantSettings("Search")] public sealed record SearchSettings { public required Uri Endpoint { get; init; } public SearchRetrySettings Retry { get; init; } = new(); public string[] Indexes { get; init; } = []; } public sealed record SearchRetrySettings { public int Attempts { get; init; } = 3; public TimeSpan Delay { get; init; } = TimeSpan.FromSeconds(1); } ``` The model schema contains its CLR type, display name, section path, and ordered property schemas. Each property records: - CLR name and configuration key; - type display name and normalized kind; - required and nullable flags; - secret flag and known default value; - nested object properties or collection item schema. Public instance properties with public getters are included, including inherited properties. The most derived declaration wins when a property is overridden or hidden. Overrides retain an inherited `[ValiantSecret]` marker. ## Property kinds | Kind | Represents | | --- | --- | | `String` | Text and string-like configuration values | | `Boolean` | Boolean values | | `Integer` | Integral numeric values | | `Number` | Floating-point and decimal values | | `Enum` | Enum values | | `Object` | Nested settings object | | `Array` | Array or collection with an item schema | | `Unknown` | A type without a more specific schema classification | ## Schema-only or configured Schema generation always occurs. Binding is opt-in: ```csharp [ValiantSettings("Features")] public sealed record FeatureCatalog; // schema only [ValiantSettings("Features", configure: true)] public sealed record BoundFeatureCatalog; // schema + Options binding ``` This lets libraries publish metadata without changing the host's service graph. ## Secret metadata ```csharp [ValiantSecret] public string? ClientSecret { get; init; } ``` `ValiantSecret` tells schema consumers that runtime values must be hidden. The ASP.NET Core UI also masks common sensitive names defensively, but explicit attributes are the durable contract for custom tools. :::info Deterministic output Generated schemas are stable enough for tooling to sort, diff, cache, and render. No runtime type scan is required to discover marked settings models. ::: ## Schema API, generation, and diagnostics Source: https://valiant.staticnorth.dev/settings/reference/schema-api # Schema API, generation, and diagnostics ## Provider contract Each generated provider implements: ```csharp public interface IValiantSettingsSchemaProvider { Type SettingsType { get; } string? SectionPath { get; } ValiantSettingsSchema Schema { get; } } ``` Resolve all providers to build custom documentation, editors, configuration audits, or deployment tooling: ```csharp foreach (var provider in services.GetServices()) { Console.WriteLine($"{provider.Schema.Name}: {provider.SectionPath}"); foreach (var property in provider.Schema.Properties) { Console.WriteLine($" {property.ConfigurationKey} ({property.Kind})"); } } ``` ## Model schema `ValiantSettingsSchema` exposes `SettingsType`, `Name`, `SectionPath`, and `Properties`. `ValiantSettingsPropertySchema` exposes: - `Name`, `ConfigurationKey`, and `TypeName`; - `Kind`, `IsRequired`, `IsNullable`, and `IsSecret`; - `DefaultValue` when it is known at generation time; - `Item` for arrays/collections; - `Properties` for nested objects. ## ASP.NET Core document The UI JSON endpoint returns `ValiantSettingsSchemaDocument`. It contains ordered `ValiantSettingsSchemaEntry` values and indicates whether secrets can be revealed and whether the current response contains revealed values. Each entry can include masked runtime values or a runtime-value resolution error. ## Packages | Package | Use it for | Target | | --- | --- | --- | | `StaticNorth.Valiant.Settings` | Schema generation and optional Options binding | .NET 8 and .NET Standard 2.0 | | `StaticNorth.Valiant.Settings.AspNetCore` | Built-in explorer and JSON schema endpoint | .NET 8 | | `StaticNorth.Valiant.Settings.Validation` | Options validation through Valiant validators | .NET 8 | Integration packages forward their parent runtime and generator assets. `StaticNorth.Valiant.Settings.Validation` also carries the core Valiant Validation assets it integrates with. ## Generator scope and diagnostics Only types marked with `[ValiantSettings]` enter the incremental generator pipeline. Generated output includes the schema provider and, when the required Microsoft configuration/DI APIs are referenced, the aggregated `AddValiantSettings` registration surface. | ID | Meaning | | --- | --- | | `VLS001` | Generic settings model types are not supported | | `VLS002` | The settings section path is empty | The section path is deliberately required so generated binding and external tooling share one unambiguous configuration identity. ## Samples Source: https://valiant.staticnorth.dev/settings/samples # Settings samples Settings has separate console and ASP.NET Core sample projects. In each project, select one delegate or startup near the top of `Program.cs`. Settings source generation is assembly-wide. Selecting one scenario changes which code runs, but every `[ValiantSettings]` model in that project contributes to `ValiantSettingsSchemas` and the generated `AddValiantSettings` method. The samples therefore use distinct section paths. ## Core settings Run the console project: ```bash dotnet run --project settings/samples/StaticNorth.Valiant.Settings.Samples ``` Select one delegate in [`Program.cs`](https://github.com/static-north-dev/valiant/blob/main/settings/samples/StaticNorth.Valiant.Settings.Samples/Program.cs): | Delegate | Demonstrates | Source | | --- | --- | --- | | `Basic.Sample.Run` | The normal configured-settings flow: `[ValiantSettings(..., configure: true)]`, `AddValiantSettings(configuration)`, and `IOptions` consumption | [`Basic`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.Samples/Basic) | | `RegistrationOptions.Sample.Run` | Default schema-provider registration compared with `RegisterSchemaProviders = false`, while configured Options still bind | [`RegistrationOptions`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.Samples/RegistrationOptions) | | `SchemaRegistry.Sample.Run` | `ValiantSettingsSchemas.All`, `Get`, and successful and unsuccessful `TryGet` lookups | [`SchemaRegistry`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.Samples/SchemaRegistry) | | `SchemaMetadata.Sample.Run` | Property kinds, nested objects, collections, nullability, required members, and secret metadata | [`SchemaMetadata`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.Samples/SchemaMetadata) | `SchemaMetadata` also shows that a runtime property initializer is not emitted as schema `DefaultValue` metadata. ## ASP.NET Core settings Run the web project: ```bash dotnet run --project settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples ``` Select one startup type in [`Program.cs`](https://github.com/static-north-dev/valiant/blob/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Program.cs): | Startup | Demonstrates | Source | | --- | --- | --- | | `Basic.Startup` | `AddValiantSettings()` and the default `/_valiant/settings` explorer and schema routes | [`Basic`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Basic) | | `Configuration.Startup` | A custom `/admin/settings` path and authorization conventions on the returned `RouteGroupBuilder` | [`Configuration`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Configuration) | | `RuntimeValues.Startup` | `ShowRuntimeValues = true`, explicit secret masking, defensive name-based masking, and reveal disabled | [`RuntimeValues`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/RuntimeValues) | | `SecretReveal.Startup` | `AllowSecretReveal = true` with explicit `?revealSecrets=true` opt-in | [`SecretReveal`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/SecretReveal) | | `Validation.Startup` | `ValidateWithValiant = true` with permissive behavior when a configured model has no validator | [`Validation`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Validation) | | `Validation.InvalidStartup` | Valiant failures translated into `OptionsValidationException` failures | [`Validation`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Validation) | | `Validation.RequiredStartup` | `RequireValidators = true` failing when a configured settings model has no matching validator | [`Validation`](https://github.com/static-north-dev/valiant/tree/main/settings/samples/StaticNorth.Valiant.Settings.AspNetCore.Samples/Validation) | The three validation startups intentionally share one folder because they use the same settings models and validators while exercising different registration policies. ## Try the web scenarios With the HTTP launch profile running on port `5194`: ```bash curl -i http://localhost:5194/_valiant/settings curl -i -H "X-Settings-Admin: true" http://localhost:5194/admin/settings curl -s http://localhost:5194/runtime-values/schemas curl -s "http://localhost:5194/secret-reveal/schemas?revealSecrets=true" curl -i http://localhost:5194/validation/invalid ``` The configuration sample uses a deliberately small header-based demo authentication handler. Replace it with the host application's real authentication and authorization policy. Runtime values and secret reveal are administrative capabilities. Protect the returned route group before enabling either outside local development. See [ASP.NET Core UI](https://valiant.staticnorth.dev/settings/guides/aspnetcore-ui) and [Binding and validation](https://valiant.staticnorth.dev/settings/guides/binding-validation) for the production configuration.