Skip to content

Retrieve a configuration setting

This is the library's primary configuration-read path, and every consuming application funnels its setting lookups through it. It keeps the shared Environment API cache current, honors a developer-only override file when one applies, falls back to loading a missing section on demand, and throws rather than returning a silent default when a key cannot be resolved anywhere.

Field Value
Operation ID OP-ENV-001
Trigger Caller request to read a configuration value
Inputs configKey
Outputs string, converted T, or ApplicationException
Primary components EnvironmentServiceBase.GetConfigSetting, EnvironmentServiceBase.GetConfigSetting<T>, EnvironmentServiceBase.GetConfigSettingInfo
Entry point SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs

Steps

  1. Validate that configKey is not null or empty before any lookup begins.
  2. Refresh or initialize the shared settings cache so the lookup runs against the newest known payload (BR-002, BR-003).
  3. Check the server refresh timestamp, but only as often as the configured throttle interval allows.
  4. Download the full settings payload when the cache is missing or the server reports newer data.

Origin: Step 2 is expanded in Refresh configuration cache and always runs before this lookup continues. 3. Normalize the requested key to lowercase and determine its logical section. A key without a dot belongs to the global section; a key with a dot uses the text before the first dot as its section (BR-009). 4. Check for a developer override before consulting central configuration. If DeveloperSettingsFile resolves to an existing JSON file, read and deserialize the override list and return the first entry whose formatted key or global key matches the caller's input (BR-004). - If the override file is malformed or unreadable, swallow that exception and fall through to central configuration lookup rather than failing the caller. 5. Check Configurations.Settings for the normalized key and return the cached ConfigSetting immediately when it is present — this is the common-case, no-network path. 6. If the key belongs to a non-global section and was not already cached, fetch that section from the Environment API and re-check the returned payload for the key (BR-002, BR-009). - Download /v2/settings/{ApplicationId}/{ApplicationHost}/{section}/section. - Merge the returned section entries into the shared cache so later lookups for the same section are served from memory.

Origin: Step 6 is expanded in Load a configuration section and runs only when a non-global key is missing from the cache. 7. If none of the preceding sources returned the key, throw ApplicationException identifying the missing key, track, and section, so a caller never mistakes an absent setting for a valid empty value (BR-001). 8. Return the resolved value to the caller. - GetConfigSetting returns ConfigValue.Value ?? string.Empty. - GetConfigSetting<T> converts the resolved value through ConfigSetting.GetValue<T>().

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Caller requests config key]) --> Refresh[Refresh configuration cache]
    Refresh --> SectionKey[Normalize key and section]
    SectionKey --> Override{Developer override match?}
    Override -->|Yes| ReturnOverride([Return override value])
    Override -->|No| Cached{Shared cache has key?}
    Cached -->|Yes| ReturnCache([Return cached value])
    Cached -->|No| NonGlobal{Non-global section?}
    NonGlobal -->|Yes| Load[Load configuration section]
    NonGlobal -->|No| Missing([Throw ApplicationException])
    Load --> Found{Section contains key?}
    Found -->|Yes| ReturnSection([Return section value])
    Found -->|No| Missing

Failure and edge-case behavior

  • A null or empty configKey fails argument validation before any network call is attempted.
  • Malformed developer override JSON is ignored rather than surfaced to the caller, so a broken local override file degrades to central lookup instead of blocking it.
  • Keys in the global section never trigger LoadSection; only non-global keys can cause an on-demand section fetch.
  • A key that is missing from overrides, the cache, and the freshly loaded section throws ApplicationException only after every lookup path has been exhausted.

Sources

  • SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs
  • SAIF.Framework.Security.EnvironmentApi\Core\Contracts\Core\Configurations\ConfigurationSettings.cs