Skip to content

Merge or upsert dictionary entries

Merge, upsert, or safely read dictionary entries, triggered when caller combines configuration/lookup dictionaries or reads with a fallback.

Field Value
Operation ID OP-034
Trigger Caller combines configuration/lookup dictionaries or reads with a fallback
Inputs Target dictionary, plus source dictionary / key / value / default
Outputs void / TValue
Primary components DictionaryExtensions.Merge<TValue>`, `TryGetValue<TKey,TValue>`, `UpdateOrAdd<TKey,TValue>
Entry point Common/SAIF.Common/Extensions/DictionaryExtensions.cs

Steps

  1. Merge iterates the source dictionary's pairs.
  2. When replaceExisting is false and the target already contains the key, skip that pair; otherwise assign instance[pair.Key] = pair.Value (add-or-overwrite). The default is replaceExisting = true. (BR-082)
  3. TryGetValue guards the dictionary with Enforce.ArgumentNotNull, then returns the stored value if the key exists or the caller's defaultValue if not — it never throws KeyNotFoundException. (BR-039, BR-083)
  4. UpdateOrAdd guards the dictionary with Enforce.ArgumentNotNull, then overwrites an existing key or adds a new one, and returns the value for chaining. (BR-039, BR-084)

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start(["Caller merges, reads, or<br>upserts a dictionary"]) --> S1["Merge: iterate source<br>dictionary's pairs"]
    S1 --> S2{"replaceExisting is false<br>and key already exists?"}
    S2 -->|Yes| Skip["Skip this pair"]
    S2 -->|No| Assign["Assign instance[key] = value<br>(add or overwrite)"]
    Skip --> S3
    Assign --> S3["TryGetValue: guard dictionary,<br>return stored value or default"]
    S3 --> S4["UpdateOrAdd: guard dictionary,<br>overwrite or add, return value"]
    S4 --> End(["Result returned to caller"])

Sources

  • Common/SAIF.Common/Extensions/DictionaryExtensions.cs