---
title: SAIF.NetCore.EnvironmentClient overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.EnvironmentClient
reference_type: package
---

# SAIF.NetCore.EnvironmentClient overview

> **Documentation context:** Packaged Component (NuGet)

`SAIF.NetCore.EnvironmentClient` is the implementation-layer NuGet package that provides `BaseEnvironmentClient` and `SecureEnvironmentClient`, the concrete implementations of the `IEnvironmentClient` contract from `SAIF.NetCore.ServiceContracts`. It resolves which environment "track" the running application belongs to, then lazily downloads, caches, and refreshes named configuration settings — and, for the secure variant, crypto-protected settings — from a central Environment API over HTTP. Every other SAIF NCore library that reads configuration (Logging, AuthService, OIDC, DBConnectionClient, and others) depends on the contract this library implements, making it a foundational provider even though it sits in the implementation layer architecturally.

## Purpose
- Resolve the application's environment host and track at construction time by calling the Environment API's track endpoint and an injected `IHostResolver`, so every setting lookup is scoped to the correct environment.
- Expose a lazily-loaded, refreshable, in-memory cache of named configuration settings through `GetSettingValue`/`GetSettingValueAsync` (string and generic overloads), `GetSectionSettings`, and `HasSetting`.
- Gate access to secure (crypto) settings behind a system hash and a server-enablement flag, implemented only in `SecureEnvironmentClient`; `BaseEnvironmentClient` always denies secure-setting retrieval.
- Support a developer-machine override path — an Active Directory computer-group check unlocking a configuration-file host override and a local JSON settings override file — so a developer workstation can point itself at a different track and substitute setting values without touching the Environment API.

## Responsibilities
- Implement `IEnvironmentClient` and translate every call into Environment API HTTP requests, mediated entirely through the injected `IHttpJsonClient` contract.
- Maintain a two-level cache (loaded sections, and settings keyed `"{section}.{key}"`), refreshed by comparing the server's `lastRefreshed` timestamp to the client's own; an empty cache (including the very first access) always triggers a reload, while a non-empty cache is checked no more than once every 60 seconds.
- Resolve the current host's Active Directory group membership (`Developer_Machine_Users`) through `HostResolver`, and use that result to unlock developer-only configuration and secure-client construction paths.
- Cache secure-setting values per `"{section}.{key}"` independent of which system hash requested them, re-fetching only when the non-secure cache refreshes.
- Define the key-addressing contract (`"{section}.{key}"` for a named section; track-section-scoped when `GetSettingValue`/`GetSettingValueAsync` are called with the section omitted, but the **bare, unprefixed key** — a distinct "root" section — when `HasSetting` is called with its optional `section` parameter omitted or an explicit `""`, which both default/resolve to `""`; `GetSectionSettings(string section)` takes a **required** argument with no default, so it never resolves to `""` implicitly, but a caller that explicitly passes `""` reaches that same bare-key root loading path, with output then filtered by the `"."`-prefix bulk-read behavior described in [Get section settings](operations/get-section-settings.md) rather than returning ordinary bare-root entries) that every consumer library's own configuration catalog depends on.

## Key components
- **`BaseEnvironmentClient`** — the default `IEnvironmentClient` implementation. Resolves host/track at construction, loads and caches non-secure settings, and always denies secure-setting retrieval (`RetrieveSecureSetting[Async]` unconditionally throws).
- **`SecureEnvironmentClient`** — subclasses `BaseEnvironmentClient` and is the only type able to return secure (crypto) settings, gated by `COREAPIENABLED`/developer-machine status and a system hash validated by the Environment API.
- **`HostResolver`/`IHostResolver`** — resolves which host (and therefore which environment track) the running application belongs to, including the Active Directory `Developer_Machine_Users` override check.
- **`SecureSettingCache`** — a per-`"{section}.{key}"` cache of secure-setting values, re-fetched when the non-secure cache's `LastRefreshed` timestamp advances.
- **`ConfigKey`/`ConfigValue`/`ConfigSetting`/`ConfigurationSettings`/`Track`** — the DTOs used to deserialize Environment API responses for settings and tracks.
- **`EnvironmentClientException`/`MissingEnvironmentUrlVariableException`** — the exceptions this library raises for configuration, retrieval, and bootstrap failures.
- **`ConfigSettingExtensions`** — typed-value conversion helpers (`GetValue<T>`) used when returning generic setting values.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Security and authorization](security-authorization.md)
- [API reference](api/index.md)

## Sources
- `src/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/BaseEnvironmentClient.cs`
- `src/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SecureEnvironmentClient.cs`
- `src/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/HostResolver.cs`
- `src/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient/SAIF.NetCore.EnvironmentClient.csproj`