---
title: Configuration helpers
summary: IConfigurationExtensions provides required/optional configuration-value reads with key validation.
status: draft
owner: Framework.NCore maintainers
last_reviewed: 2026-10-02
library: SAIF.NetCore.ServiceExtensions
reference_type: package
operation_id: OP-20
trigger: Application or framework code calls a GetRequiredValue/GetOptionalValue/HasKey/TryGetValue/KeyMustExist/GetAllKeys extension method on IConfiguration.
---

# Configuration helpers

This operation is a small set of `IConfiguration` extension methods providing required-value reads (with key-existence validation), optional reads, existence checks, a try-get that returns `false` for a missing/blank value but still propagates a conversion exception for an unconvertible non-blank value, and key enumeration.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-20 |
| **Trigger** | Application or framework code calls one of `GetRequiredValue<T>`, `GetOptionalValue<T>`, `HasKey`, `TryGetValue<T>`, `KeyMustExist`, `GetAllKeys` on an `IConfiguration` instance. |
| **Inputs** | A configuration key; `GetOptionalValue<T>` and `TryGetValue<T>` additionally require a caller-supplied `defaultValue`; `TryGetValue<T>` also takes an `out` value. |
| **Outputs** | The resolved configuration value, or an exception/default per method. |
| **Primary components** | `IConfigurationExtensions` |
| **Entry point** | `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IConfigurationExtensions.cs` |

## Steps

1. `GetRequiredValue<T>` (L22) calls `KeyMustExist` then `GetValue<T>` ([BR-SE-25](../business-rules.md#br-se-25-required-configuration-keys-must-exist))
   - On failure: a missing or whitespace-only key causes `ArgumentNullException` (the key/message is used as the parameter name).
2. `GetOptionalValue<T>` (L36) returns `GetValue<T>` if the key exists, otherwise a caller-supplied default.
3. `HasKey` (L49) returns `!string.IsNullOrWhiteSpace(config.GetValue<string>(key))` — `true` only when present **and** non-blank, not merely present.
4. `TryGetValue<T>` (L63) attempts `Convert.ChangeType` on the raw value.
   - On failure: an unconvertible value may throw from `Convert.ChangeType`.
5. `KeyMustExist` (L83, L97) throws `ArgumentNullException` if the key is missing or value is whitespace-only ([BR-SE-25](../business-rules.md#br-se-25-required-configuration-keys-must-exist))
6. `GetAllKeys` (L113) enumerates all configuration keys.

## Process flow

This diagram shows the synchronous, per-call branching inside each `IConfiguration` extension method invoked by application code; it is not a multi-step process that persists state across calls.

```mermaid
flowchart TD
    Start([Extension method called]) --> S1{Which method?}
    S1 -->|GetRequiredValue| S2[KeyMustExist]
    S2 --> D1{Key exists and non-blank?}
    D1 -->|No| EndErr([ArgumentNullException])
    D1 -->|Yes| S3[GetValue and return]
    S1 -->|GetOptionalValue| S4[Return value or default]
    S1 -->|HasKey| S5[Return existence boolean]
    S1 -->|TryGetValue| S6[Convert.ChangeType attempt]
    S1 -->|GetAllKeys| S7[Enumerate keys]
    S3 --> EndOk([Value returned])
    S4 --> EndOk
    S5 --> EndOk
    S6 --> EndOk
    S7 --> EndOk
```

## Failure and edge-case behavior
- Missing or whitespace-only required keys throw `ArgumentNullException` via `KeyMustExist`.
- `TryGetValue<T>`'s `Convert.ChangeType` call may throw for incompatible type conversions rather than returning `false`.

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

## Sources
- `src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IConfigurationExtensions.cs`