# Cocoar.Configuration > Reactive Configuration for .NET Strongly-typed, layered, reactive. Zero ceremony configuration that updates itself. ## Table of Contents ### Introduction - [Getting Started](/guide/getting-started.md): Install Cocoar.Configuration packages, define a POCO config class, wire FromFile rules in ASP.NET Core, console, and DI setups - [Why Cocoar.Configuration?](/guide/why-cocoar.md): Cocoar versus IOptions — direct injection, ordered rule layering, IReactiveConfig updates, atomic multi-config tuples, required rollback, built-in flags and secrets - [Working with Certificates](/guide/certificates.md): X.509 certificates in Cocoar — why password-less, protecting PFX via file permissions on Linux/macOS/Windows and Docker/Kubernetes ### Configuration - [Rules & Layering](/guide/configuration/rules.md): Rule anatomy with For().FromFile, top-to-bottom property-by-property JSON merge layering, last-write-wins, and Select to extract a sub-document - [Required vs Optional Rules](/guide/configuration/required-optional.md): Optional rules degrade gracefully to empty {} with Degraded health, Required() rolls back the recompute on failure with Unhealthy status and startup exception - [Setup & Type Exposure](/guide/configuration/setup.md): Auto-registration of rule types as Scoped, the setup lambda with ConcreteType().ExposeAs(), Interface().DeserializeTo(), lifetimes, disabling auto-registration - [Config-Aware Rules](/guide/configuration/config-aware.md): Rules that read earlier results via IConfigurationAccessor (GetConfig/TryGetConfig) to derive dynamic file paths and HTTP endpoints, with COCFG002 order enforcement - [Conditional Rules](/guide/configuration/conditional-rules.md): Conditionally enable rules with .When(accessor) over earlier config state, Skipped health status, dynamic source selection, COCFG002 rule-order checking - [Aggregate Rules ](/guide/configuration/aggregate-rules.md): Group sub-rules into one unit with FromFiles file-layering shorthand and Aggregate() over mixed providers, aggregate-level vs sub-rule Required semantics ### Providers - [Providers Overview](/guide/providers/overview.md): Provider contract (FetchConfigurationBytesAsync, ChangesAsBytes), built-in providers, key-based instance caching, provider vs query options, lifecycle - [File Provider](/guide/providers/file.md): FromFile JSON provider, directory file watcher, AppContext.BaseDirectory path resolution, debouncing, path-traversal protection, Kubernetes ConfigMap symlink support (followSymlinks), optional vs Required, dynamic paths - [YAML Provider](/guide/providers/yaml.md): FromYamlFile provider (Cocoar.Configuration.Yaml) — reactive .yaml/.yml watching, YAML core-schema scalar type-inference (bool/number/null), quoted/block scalars stay strings - [TOML Provider](/guide/providers/toml.md): FromTomlFile provider (Cocoar.Configuration.Toml) — reactive .toml watching, TOML typed values (string/int/float/bool/datetime/array/table) mapped to JSON, arrays-of-tables, Kubernetes ConfigMap support - [Dotenv (.env) Provider](/guide/providers/dotenv.md): FromDotEnv provider (core, no dependency) — .env KEY=value parsing, # comments, export prefix, single/double quotes, inline comments, :/__ key nesting, reactive file-watching - [INI Provider](/guide/providers/ini.md): FromIniFile provider (core, no dependency) — .ini [section] headers, key=value, ;/# whole-line comments, :/. nesting, quote stripping, connection-string-safe (no inline-comment stripping), reactive watching - [Environment Variables Provider](/guide/providers/environment.md): FromEnvironment provider, case-insensitive prefix filtering, __ and : nesting to JSON, final-override pattern, dynamic per-tenant prefix - [Command Line Provider](/guide/providers/command-line.md): FromCommandLine provider, switch-prefix filtering, key=value/key value/boolean-flag formats, : and __ nesting, custom prefixes, highest-priority override - [HTTP Provider](/guide/providers/http-polling.md): FromHttp provider — one-time fetch, polling, SSE, SSE-with-fallback, failure threshold, dynamic endpoints, client-certificate and encrypted-secret token auth - [Microsoft IConfiguration Adapter](/guide/providers/microsoft-adapter.md): FromIConfiguration adapter bridging Microsoft IConfiguration, colon-key flattening to nested JSON, .Select section filtering, GetReloadToken change detection, gradual migration - [Static & Observable Providers](/guide/providers/static-observable.md): FromStaticJson/FromStatic fixed-value providers and FromObservable wrapping IObservable or IObservable, BehaviorSubject for WebSocket/gRPC/queue/test updates - [Writable Store Provider](/guide/providers/writable-store.md): FromStore writable override layer, sparse leaf persistence, IWritableStore SetAsync/ResetAsync/PatchAsync, reset vs explicit null, DescribeAsync provenance, secrets, IStoreBackend - [Marten Store](/guide/providers/marten-store.md): Marten/PostgreSQL writable-store backend, FromMartenStore service-backed rule, database-per-tenant via .TenantScoped, CocoarConfigDocument storage model, single-process reactivity and HA notes - [Building Custom Providers](/guide/providers/custom.md): Extend ConfigurationProvider, FetchConfigurationBytesAsync/ChangesAsBytes, GenerateProviderKey caching, fluent FromProvider extension, service-backed DI providers, change detection, secret envelopes ### Dependency Injection - [DI Setup](/guide/di/setup.md): AddCocoarConfiguration for Microsoft.Extensions.DI — auto-registration, ConcreteType/ExposeAs/Interface DeserializeTo, DisableAutoRegistration, flags, secrets - [ASP.NET Core Integration](/guide/di/aspnetcore.md): Cocoar.Configuration.AspNetCore — WebApplicationBuilder.AddCocoarConfiguration, health endpoint, feature flag and entitlement REST endpoints, injecting config - [Lifetimes & Registration](/guide/di/lifetimes.md): DI lifetimes — Scoped config types, Singleton IReactiveConfig, AsSingleton/AsTransient/AsScoped, keyed services, exposed-type lifetimes, deterministic ordering - [Service-Backed Configuration](/guide/di/service-backed.md): Two-layer DI-aware config (ADR-006) — UseServiceBackedConfiguration with (sp,a) factories, FromHttp via IHttpClientFactory, FromStore, FromService, host-start activation ### Reactive Updates - [IReactiveConfig\](/guide/reactive/basics.md): IReactiveConfig : IObservable — CurrentValue, Subscribe, replay-1 BehaviorSubject semantics, reference-equality change detection, atomic swap, Scoped vs Singleton - [Reactive Tuples](/guide/reactive/tuples.md): IReactiveConfig<(T1, T2)> for atomic multi-config updates — same-snapshot guarantee, per-element change detection, 2–8+ arities, automatic DI registration - [Debouncing](/guide/reactive/debouncing.md): Trailing-edge debounce coalescing rapid source changes — 300ms default, UseDebounce config, cross-provider coalescing, recompute-from-earliest-changed-rule, during-run changes ### Feature Flags & Entitlements - [Feature Flags vs Entitlements](/guide/flags/concepts.md): Feature flags vs entitlements as pure functions over config, FeatureFlag/Entitlement delegates, ExpiresAt health signal, the litmus test, Cocoar vs LaunchDarkly - [Defining Feature Flags](/guide/flags/defining-flags.md): Defining IFeatureFlags partial classes, FeatureFlag and FeatureFlag delegates, tuple multi-config, ExpiresAt, source-generated Config property - [Defining Entitlements](/guide/flags/defining-entitlements.md): Defining IEntitlements partial classes, Entitlement and Entitlement delegates, tuple multi-config, permanent business logic with no ExpiresAt - [Registration](/guide/flags/registration.md): Registering flags/entitlements via UseFeatureFlags/UseEntitlements, Register, global/class/property-level resolvers, priority cascade, Core-only no-DI overload - [Context Resolvers](/guide/flags/context-resolvers.md): IContextResolver hydrating request DTOs into domain context, global/class/property registration levels, Scoped lifetime, evaluation pipeline for contextual flags - [REST Evaluation Endpoints](/guide/flags/rest-endpoints.md): MapFeatureFlagEndpoints/MapEntitlementEndpoints GET/POST routes, custom path prefixes, RequireAuthorization and middleware chaining, error status codes, resolver-backed POST evaluation - [Expiry & Health](/guide/flags/expiry-health.md): Flag ExpiresAt lifecycle, Degraded health when expired, IFeatureFlagsDescriptors.All/Expired, health endpoint integration, compile-time static-date validation, define-to-cleanup lifecycle ### Multi-Tenancy - [Multi-Tenancy](/guide/multi-tenancy/overview.md): Per-tenant pipeline bundles on a shared global base, .TenantScoped() rules, accessor.Tenant, …ForTenant reads, scoped ITenantReactiveConfig, per-tenant flags/secrets/WritableStore, global fan-out ### Secrets - [Secrets Overview](/guide/secrets/overview.md): Built-in encrypted-at-rest secrets via X.509 certificates and cocoar.secret envelopes, Secret properties, lease-based decrypted access with memory zeroing - [Secret\ & Leases](/guide/secrets/secret-type.md): Declaring Secret and ISecret properties for strings, byte arrays and numbers, Open() leases and SecretLease that zero decrypted bytes on dispose - [Encryption Setup](/guide/secrets/encryption-setup.md): UseSecretsSetup with X.509 hybrid encryption (RSA-OAEP + AES-256-GCM), UseCertificateFromFile/WithKeyId single-cert, PFX/PEM formats, certificate-folder mode - [Publishing Encryption Keys ](/guide/secrets/key-publishing.md): Exposing public keys via MapSecretEncryptionKey and MapTenantSecretEncryptionKey on /.well-known/cocoar/encryption-key, single- vs multi-tenant, ITenantContext, response shape - [Browser & Client Encryption ](/guide/secrets/client-encryption.md): @cocoar/secrets TypeScript library — fetchEncryptionKey and encryptSecret build cocoar.secret envelopes client-side via WebCrypto so plaintext never reaches the server, multi-tenant - [CLI Tools](/guide/secrets/cli.md): cocoar-secrets global .NET tool — encrypt values to JSON envelopes (incl. from stdin), generate self-signed certs, convert password-protected PFX to password-less - [Certificate Caching](/guide/secrets/certificate-caching.md): UseCertificatesFromFolder time-limited private-key caching (cacheDurationSeconds), FileSystemWatcher auto-discovery, two-level cache, zero-downtime certificate rotation - [Security Model](/guide/secrets/security-model.md): Memory-safety guarantees of the lease pattern (Array.Clear/ZeroMemory, stackalloc keys), hybrid RSA-OAEP-SHA256 + AES-256-GCM encryption, certificate rotation ### Health Monitoring - [Health Monitoring](/guide/health/overview.md): HealthStatus enum (Unknown/Healthy/Degraded/Unhealthy), per-rule required vs optional outcomes, expired feature flags, startup-throw vs runtime-rollback, accessing health via ConfigManager - [ASP.NET Core Health Checks](/guide/health/aspnetcore.md): AddCocoarConfigurationHealthCheck() for ASP.NET Core health checks, custom name and tags, HealthStatus to HealthCheckResult mapping, /health endpoint integration - [Logging & Diagnostics](/guide/health/logging.md): Microsoft.Extensions.Logging with source-generated LoggerMessage, Cocoar.Configuration log categories, event IDs by Debug/Information/Warning level, filtering by prefix - [Performance Characteristics](/guide/health/performance.md): Partial re-evaluation, SHA-256 hash-based change detection, zero steady-state cost, one instance per config type, provider sharing by key, reference-equality reactive pipeline, 300ms debounce ### Testing - [Test Overrides](/guide/testing/overrides.md): CocoarTestConfiguration with AsyncLocal isolation, ReplaceConfiguration vs AppendConfiguration, independent ReplaceSecretsSetup with AllowPlaintext for parallel-safe tests - [Integration Testing](/guide/testing/integration.md): Bridging the xUnit AsyncLocal context gap, TestConfigurationContext fixture pattern, CocoarTestConfiguration.Apply/Clear in constructors, WebApplicationFactory integration tests - [Testing Strategy](/guide/testing/strategy.md): Test-at-the-right-layer principles, test project structure, in-memory TestProviders with no I/O in Core.Tests, trait filters (Unit/Stress), deterministic active-waiting over fixed delays ### Analyzers - [Analyzers & Source Generator](/guide/analyzers/overview.md): Built-in Roslyn analyzers (COCFG001-006) and the flags/entitlements source generator, diagnostics-at-a-glance table, suppression via pragma, attribute, and .editorconfig - [Configuration Diagnostics](/guide/analyzers/configuration.md): COCFG diagnostics reference — COCFG001 secret path conflicts, COCFG002 rule dependency ordering, COCFG003 required-rule validation, COCFG005/006 duplicate and static-provider ordering - [Flags Diagnostics & Source Generator](/guide/analyzers/flags.md): COCFLAG diagnostics — COCFLAG001 non-static ExpiresAt, COCFLAG002 abstract type in Register, COCFLAG003 missing summary docs, plus the flags/entitlements source generator ### How-To - [Migrating from IOptions](/guide/how-to/from-ioptions.md): Incremental IOptions/IConfiguration migration — FromIConfiguration bridge, IOptionsMonitor to IReactiveConfig, PostConfigure as last-write-wins rule, mapping table ### Migration - [Migration v4 → v5](/guide/migration/v4-to-v5.md): v4 to v5 — ConfigManager.Create builder API, 10+ packages consolidated to 7, feature flags & entitlements, HttpPolling renamed to Http, Flag to FeatureFlag, health and resolver API renames - [Migration v3 → v4](/guide/migration/v3-to-v4.md): v3 to v4 — no public API breaks; adds test overrides, Secret X.509 encryption, secrets CLI, COCFG analyzers; internal provider contract moves from JsonElement to byte[] (custom providers only) - [Migration v2 → v3](/guide/migration/v2-to-v3.md): v2 to v3 Type-First API migration — rule.File().For() becomes rule.For().FromFile(), config-aware .When(IConfigurationAccessor), provider-method rename table ### Reference - [Package Overview](/reference/packages.md): NuGet package breakdown — Abstractions, Core, DI, AspNetCore, Http, MicrosoftAdapter, WritableStore.Marten, Analyzers, Secrets CLI; dependency graph and which to install - [Health API Reference](/reference/health-api.md): Health API reference — HealthStatus enum, ConfigManager.IsHealthy, IFlagsHealthSource, ASP.NET Core health check, OpenTelemetry meters and Activity source - [CLI Commands Reference](/reference/cli-commands.md): cocoar-secrets CLI reference — encrypt, decrypt, generate-cert, convert-cert, cert-info; options, exit codes, RSA-OAEP-SHA256 + AES-256-GCM envelope - [Analyzer Diagnostics Reference](/reference/analyzer-diagnostics.md): Roslyn diagnostics reference — COCFG001-006 (secret conflicts, rule ordering, required rules, duplicates) and COCFLAG001-003 flags; severities and suppression - [Examples](/reference/examples.md): Runnable example projects in src/Examples — file layering, conditional rules, providers (command-line, HTTP, custom), tuple reactive, secrets, ASP.NET Core, testing overrides ### Roadmap - [Roadmap](/roadmap/overview.md): Roadmap overview and priorities — ConfigHub portal, cloud KMS providers (Azure Key Vault, AWS), database provider; current limitations and Apache-2.0 commitment - [ConfigHub](/roadmap/confighub.md): ConfigHub management portal (commercial) — push config to fleets via FromConfigHub(), secret/cert lifecycle, feature flag control, health dashboard, OTLP telemetry - [Cloud Providers](/roadmap/cloud-providers.md): Planned native cloud KMS providers — FromAzureKeyVault (Managed Identity, rotation) and FromAwsSecretsManager (IAM, ARN), layered via the existing rule system - [Database Provider](/roadmap/database-provider.md): Planned FromDatabase() provider over ADO.NET (SQL Server, PostgreSQL, MySQL, SQLite) — JSON columns, polling, config-aware queries, LISTEN/NOTIFY, multi-tenant config ### Architecture Decision Records - [Architecture Decision Records](/adr.md): Index of Cocoar.Configuration's Architecture Decision Records (ADR-001 through ADR-006) capturing the rationale behind key design choices - [ADR-001: Using Cocoar.Capabilities for Cross-Assembly Extensibility](/adr/ADR-001-capabilities-system.md): Use the Cocoar.Capabilities library for type-safe metadata attachment to builders across assembly boundaries, avoiding circular dependencies - [ADR-002: Atomic Reactive Configuration Updates](/adr/ADR-002-atomic-reactive-updates.md): Transactional all-or-nothing recompute with tuple-reactive subscriptions and reference-equality change detection; no IOptionsMonitor partial-update races - [ADR-003: Fix Provider Inconsistency - Optional Rules Always Return Objects](/adr/ADR-003-provider-consistency-empty-objects.md): All providers return empty JSON objects on missing/unavailable data so types always carry C# defaults; failures tracked separately via health monitoring - [ADR-004: Aggregate Rules with Isolated Execution Boundary](/adr/ADR-004-aggregate-rules.md): AggregateRuleManager wraps N sub-rules, byte-merges their results, and contains inner Required failures within the aggregate boundary; FromFiles sugar - [ADR-005: Multi-Tenant Configuration](/adr/ADR-005-multi-tenant-configuration.md): Per-tenant pipeline bundles on a shared global base, one flat rule list with .TenantScoped(), explicit …ForTenant(id) reads, automatic fan-out, eventual consistency - [ADR-006: DI-aware Configuration (Two-Layer Model)](/adr/ADR-006-di-aware-configuration.md): Two-layer model — eager no-DI UseConfiguration plus lazy UseServiceBackedConfiguration whose (sp,a) factories resolve container services, activated by a hosted service ### Other - [What's Next](/guide/roadmap.md): Pointer to the full roadmap — ConfigHub, cloud providers, database provider, and other planned features