Skip to content

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 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.

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