---
title: DictionaryExtensions
summary: API reference for DictionaryExtensions.
status: draft
owner: saif-docgen
last_reviewed: 2026-09-15
library: SAIF.Framework.Common
reference_type: package
---

# DictionaryExtensions

Dictionary merge and safe-read/upsert helpers layered on `Enforce` guards. ([BR-082](../../business-rules.md#br-082-merging-dictionaries-overwrites-existing-keys-by-default), [BR-083](../../business-rules.md#br-083-a-dictionary-read-with-a-supplied-default-never-throws-on-a-missing-key), [BR-084](../../business-rules.md#br-084-an-upsert-overwrites-an-existing-key-or-adds-a-new-one-and-always-returns-the-supplied-value))

## Purpose
- Dictionary merge and safe-read/upsert helpers layered on `Enforce` guards. ([BR-082](../../business-rules.md#br-082-merging-dictionaries-overwrites-existing-keys-by-default), [BR-083](../../business-rules.md#br-083-a-dictionary-read-with-a-supplied-default-never-throws-on-a-missing-key), [BR-084](../../business-rules.md#br-084-an-upsert-overwrites-an-existing-key-or-adds-a-new-one-and-always-returns-the-supplied-value))

## Context
- Namespace: `SAIF.Common.Extensions`
- Assembly/package: `SAIF.Framework.Common`

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| Merge<TValue>(this IDictionary instance, IDictionary<string,TValue> source, bool replaceExisting = true) | `public static void Merge<TValue>(this IDictionary instance, IDictionary<string,TValue> source, bool replaceExisting = true)` | Copies every entry from `source` into `instance`, optionally skipping keys that already exist. ([BR-082](../../business-rules.md#br-082-merging-dictionaries-overwrites-existing-keys-by-default)) |
| TryGetValue<TKey,TValue>(this IDictionary<TKey,TValue> instance, TKey key, TValue defaultValue) | `public static TValue TryGetValue<TKey,TValue>(this IDictionary<TKey,TValue> instance, TKey key, TValue defaultValue)` | Returns the stored value for `key`, or `defaultValue` when the key is absent, never throwing `KeyNotFoundException`. ([BR-039](../../business-rules.md#br-039-a-guarded-argument-must-not-be-null), [BR-083](../../business-rules.md#br-083-a-dictionary-read-with-a-supplied-default-never-throws-on-a-missing-key)) |
| UpdateOrAdd<TKey,TValue>(this IDictionary<TKey,TValue> instance, TKey key, TValue value) | `public static TValue UpdateOrAdd<TKey,TValue>(this IDictionary<TKey,TValue> instance, TKey key, TValue value)` | Overwrites an existing key or adds a new one, returning `value` for chaining. ([BR-039](../../business-rules.md#br-039-a-guarded-argument-must-not-be-null), [BR-084](../../business-rules.md#br-084-an-upsert-overwrites-an-existing-key-or-adds-a-new-one-and-always-returns-the-supplied-value)) |


## Sources
- `Common/SAIF.Common/Extensions/DictionaryExtensions.cs`