---
title: Load a configuration section
summary: Fetch a missing non-global section and merge it into the shared cache.
status: draft
owner: SAIF Framework
last_reviewed: 2026-07-30
library: SAIF.Framework.Security.EnvironmentApi
reference_type: package
operation_id: OP-ENV-003
trigger: Cached lookup misses a non-global key
---

# Load a configuration section

This operation retrieves one named section from the Environment API and merges its settings into the library's shared cache. It exists as the fallback path for the common case where a non-global key was not requested at construction time and therefore is not yet part of the main payload.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-ENV-003 |
| **Trigger** | `GetConfigSettingInfo` misses a non-global key in the shared cache |
| **Inputs** | `section` |
| **Outputs** | Section-scoped `ConfigurationSettings` payload plus merged cached entries |
| **Primary components** | `EnvironmentServiceBase.LoadSection`, `EnvironmentServiceBase.AddSettingToLoadedConfigurations` |
| **Entry point** | `SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs` |

## Steps

1. Read the current `LastRefreshed` value before issuing the section request, so the returned payload can be stamped with the same server refresh timestamp as the rest of the cache ([BR-002](../business-rules.md#br-002-environment-api-base-url-must-be-present)).
2. Build `/v2/settings/{ApplicationId}/{ApplicationHost}/{section}/section` and download the JSON response.
3. Deserialize the response into a fresh `ConfigurationSettings` instance.
4. Stamp the returned payload with the previously captured `LastRefreshed` value and a new local `LastLoaded` timestamp.
5. Merge each returned `ConfigSetting` into the shared cache by calling `AddSettingToLoadedConfigurations`.
   - Lock `_configLock` during the merge so concurrent section loads cannot corrupt the shared dictionary.
   - Skip the merge entirely when `_configurations` is still null.
   - Ignore duplicate-key `ArgumentException`s so a repeated or concurrent section load does not fail the caller.
6. Return the section payload to the caller, which rechecks the specific key against the freshly merged settings.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller misses non-global key]) --> Stamp[Capture LastRefreshed]
	Stamp --> Download[Download section payload]
	Download --> Deserialize[Deserialize ConfigurationSettings]
	Deserialize --> Merge[Merge returned settings into shared cache]
	Merge --> End([Return section payload])
```

## Failure and edge-case behavior

- The method depends on the current `ApplicationHost`; a host-resolution failure surfaces before the section request is even made.
- Duplicate section entries are ignored during the cache merge rather than overwriting the value that was already loaded.
- HTTP and deserialization failures are not caught locally and propagate to the caller.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Configuration](../configuration.md)

## Sources
- SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs