Skip to content

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)
  2. On failure: a missing or whitespace-only key causes ArgumentNullException (the key/message is used as the parameter name).
  3. GetOptionalValue<T> (L36) returns GetValue<T> if the key exists, otherwise a caller-supplied default.
  4. HasKey (L49) returns !string.IsNullOrWhiteSpace(config.GetValue<string>(key)) — true only when present and non-blank, not merely present.
  5. TryGetValue<T> (L63) attempts Convert.ChangeType on the raw value.
  6. On failure: an unconvertible value may throw from Convert.ChangeType.
  7. KeyMustExist (L83, L97) throws ArgumentNullException if the key is missing or value is whitespace-only (BR-SE-25)
  8. 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.

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.

Sources

  • src/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/SAIF.NetCore.ServiceExtensions/IConfigurationExtensions.cs