Config

Remarks

Matching is fragment based and case-insensitive across keys, config paths, applied paths, and environment variable names. Sensitive values are replaced with a fixed placeholder before rendering. Non-sensitive complex objects may produce a null display value so callers can rely on child entries instead of an unsafe dump. Formatting failures are swallowed intentionally to keep audit generation best-effort.

Remarks

Apply this attribute to a concrete Config{T} or ConfigStruct{T} wrapper when startup should fail if provider/default resolution leaves the wrapper without a value. A Config{T}.DefaultValue or ConfigStruct{T}.DefaultValue satisfies the requirement because the requirement is resolved presence, not provider-source auditing.

This attribute is intentionally separate from scalar value validation attributes such as ConfigValueNotEmptyAttribute. Use ConfigKeyRequiredAttribute when absence should fail, and use value validation when a resolved value must satisfy shape or range rules.

Remarks

This is an internal provider seam, not a consumer-facing configuration API. DefaultConfigManager uses it after direct provider resolution so hierarchical override sources can update only the supplied child values instead of replacing an entire options object.

Remarks

AppSurfaceConfigModule registers core configuration services immediately, then defers typed IConfig discovery through StartupContext.CustomRegistrations so all module dependencies are known first. The deferred scan inspects dependency module assemblies, the entry assembly, and the root module assembly. Pitfall: config dependencies should be registered before the custom registration callback runs; otherwise discovered config objects may activate before their supporting services are available.

Remarks

IEnvironmentConfigProvider composes IConfigProvider with IEnvironmentProvider for implementations that need to resolve configuration and the active environment from the same source. Prefer the composite when environment-aware config lookup should be atomic or co-located in one implementation; use the separate interfaces when configuration and environment ownership differ. Implementations should be safe for repeated reads, define any caching or refresh behavior, and avoid assuming that all configuration is environment-exclusive. Disposal and lifetime follow the concrete provider registration.

Remarks

Reporters inspect known configuration keys, provider provenance, validation diagnostics, and redacted display values. Implementations should return a report with diagnostics for recoverable provider and wrapper failures rather than throwing after argument validation succeeds.

Remarks

This internal reporter treats IEnvironmentConfigProvider as the override provider, excludes manager/internal provider registrations from the displayed provider list, and favors wrapper-discovered audit entries when duplicate keys are registered manually. Provider failures are converted into diagnostics so one broken provider does not prevent operators from seeing the rest of the report.

Remarks

The reporter uses this internal contract to keep value state, provenance, and diagnostics together while it walks providers in precedence order. Missing values should be represented with Missing(string).

Remarks

Implementations should avoid throwing for expected parse or source errors and return diagnostics instead. The reporter catches unexpected exceptions and converts them into provider diagnostics.

Remarks

The environment provider uses this to explain mixed provenance for object values without mutating the provider instance that supplied the base value.

Remarks

Implementations receive the raw provider value and should return structured diagnostics rather than throwing for validation failures. Unexpected exceptions are caught by the wrapper implementations.

Remarks

Implementations should return a stable absolute path that exists and is readable by the process. The default implementation returns AppContext.BaseDirectory. Callers should validate Directory before opening files and report a configuration error when it is null, empty, missing, unreadable, or unsuitable for the current platform. Paths should not depend on the current working directory; symlinks and platform separators are implementation details callers should normalize before comparison.

Remarks

DefaultConfigFileLocationProvider returns AppContext.BaseDirectory from Directory. This is appropriate for simple apps that keep configuration beside application binaries. Use a custom IConfigFileLocationProvider for environment-specific, user-scoped, container-mounted, or service-hosted configuration. Pitfall: AppContext.BaseDirectory is not necessarily System.IO.Directory.GetCurrentDirectory and can vary by deployment model, test runner, or host.

Remarks

Scalar validation runs after provider/default resolution and only when the resolved value is non-null. These attributes validate the value itself; they do not make a missing configuration key required. Use a default value or an application startup presence check when absence should fail.

Validation is intentionally strict about value types. Built-in scalar attributes return validation failures for unsupported runtime types instead of converting values. Use an options object with DataAnnotations when validation spans multiple members, needs nested object traversal, or should model required presence separately from value shape.

The validation context object is the concrete config wrapper and does not provide application dependency injection services. Override Config{T}.ValidateValue or ConfigStruct{T}.ValidateValue for scalar rules that cannot be expressed as reusable attributes.

Remarks

A null value is treated as successful validation so optional or missing scalar values remain optional. Non-null strings must contain non-whitespace characters, and non-null Guid values must not be Guid.Empty.

Runtime type matching is strict: only string and Guid are supported. Applying this attribute to a different scalar value type returns a validation failure rather than attempting a conversion. Use an options object with member-level DataAnnotations when required presence, cross-field rules, or richer object validation is part of the contract.

Remarks

A null value is treated as successful validation so optional or missing scalar values remain optional. Non-null values are compared against the inclusive minimum and maximum supplied to the constructor.

Range validation accepts resolved int and double values. Integer bounds are widened when validating a double value, so attribute arguments such as [ConfigValueRange(1, 5)] work for ConfigStruct<double> wrappers. Unsupported runtime types return validation failures instead of being converted. Use an options object when validation needs multiple numeric fields, required presence, or object-level DataAnnotations.

Remarks

A null value is treated as successful validation so optional or missing scalar values remain optional. Non-null strings must have a length greater than or equal to Length.

Runtime type matching is strict: only string values are supported. Applying this attribute to another scalar value type returns a validation failure rather than converting the value. Use an options object with DataAnnotations when string length is only one part of a larger model contract or when required presence should be represented separately.

Remarks

Reports are immutable snapshots from the caller's perspective: provider order, entries, diagnostics, and redaction policy describe one audit run and should not be treated as live configuration. Use Entries for machine inspection and ConfigAuditTextRenderer when operators need a deterministic text dump.

Remarks

Precedence is the display order used by audit reports. Environment providers are marked as overrides because they are checked before normal priority-ordered providers.

Remarks

State summarizes the entry as a whole. Object entries can contain Children with more specific provenance, including nested ConfigAuditEntryState.PartiallyResolved states when descendants are patched. DisplayValue is already redacted and can be null for complex values; callers should inspect children instead of assuming a full object dump is available.

Remarks

Source records identify where a value came from and how it was applied. File paths, environment variable names, and config paths are optional because not every provider exposes the same provenance. The source role is especially important for mixed values: a base source can be combined with patch sources from higher-priority providers.

Remarks

Diagnostic messages are intended to be display-safe and stable enough for operators. Use Code for programmatic handling, and use Source when a diagnostic can be tied to one provider, file, or environment variable.

Remarks

The built-in policy is always enabled and uses fragment matching before values are exposed through ConfigAuditEntry.DisplayValue. MatchedFragments is a snapshot for explanation, not a mutable policy hook.