Configuration

HatTrick.Configuration is a .NET 9 library for application configuration backed by JSON files and environment variables. Each source has its own manager: JsonConfigManager for plain C# types backed by JSON files, EnvVarConfigManager for named environment variables read back as strings. Both share a common builder pattern, validation model, and AES-256-GCM encryption. Ships as a single ~27 KB assembly with no external runtime dependencies.

Why HatTrick.Configuration

• One source per registration, no provider chain: Register<T>("app-settings.json") reads exactly one file, so where a value originates is always explicit, never the result of merge or override precedence across multiple sources.
• No DI container required: BuildInstance/GetInstance work the same in a console app, a class library, or a service, with no dependency on a DI framework or container to get validated configuration.
• One builder shape, two sources: BuildInstance(name) → register → Build() is identical for JSON and environment variables, so using either, or both, in the same app stays simple and consistent.
• Fail fast, not partial: every registered type or variable is validated once, at Build() time; failures aggregate into a single ConfigValidationException and the build leaves no instance behind.
• Authenticated encryption, opt-in per registration: AES-256-GCM with PBKDF2-derived keys. A wrong key and tampered ciphertext are indistinguishable failure modes by design, both throwing CryptographicException rather than yielding garbage plaintext.
• Optimistic concurrency on writes: Put<T> compares the file’s on-disk content against what was last read and returns false without writing if it changed, rather than silently discarding a concurrent edit. Useful for values a running process adjusts itself, for example a background thread lowering a timeout after observing a rise in network failure rates, not just values fixed once at startup.
• Hot reload without eager reads: a modified JSON file invalidates the affected type’s cache entry; the next Get<T> picks it up lazily, no restart or polling required.
• Thread-safe by default: every operation on a built instance is internally synchronized; no external locking required to share an instance across threads.

When to use

Good fit:

• Applications that require typed settings from JSON files, string values from environment variables, or both
• Secrets (connection strings, API keys) that need to live encrypted at rest, whether in a JSON file or an environment variable
• Services where configuration should be validated once at startup rather than discovered piecemeal at first use
• Long-running processes that want configuration changes picked up without a restart
• Processes that need to persist their own runtime-adjusted settings back to a JSON file, not just read them at startup

Not a good fit:

• Configuration sources beyond JSON files and environment variables (XML, YAML, remote config servers)
• Multi-process coordination around the same config files: writes are safe within a process, not across processes
• Implicit source discovery: every JSON file and environment variable must be named explicitly via Register, never scanned or inferred

Where to find HatTrick.Configuration

Documentation