---
source_files:
  - Common/DTS.Common.Core/Settings/SettingsChangedEventArgs.cs
  - Common/DTS.Common.Core/Settings/SettingsCollection.cs
generated_at: "2026-04-16T11:41:07.381293+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "e48bcdd1082dba01"
---

# Documentation: DTS.Common.Core.Settings

## 1. Purpose

This module provides an observable dictionary implementation that notifies subscribers when settings change. It consists of `SettingsCollection<TKey, TItem>`, a generic dictionary wrapper that implements `IDictionary<TKey, TItem>` and fires events on modifications, and `SettingsChangedEventArgs<TKey, TItem>`, the event payload describing what changed. This enables reactive patterns where consumers can respond to configuration or settings changes without polling.

---

## 2. Public Interface

### `SettingsCollection<TKey, TItem>`

A generic dictionary implementation that raises events on mutation.

**Event:**
- `event EventHandler<SettingsChangedEventArgs<TKey, TItem>> CollectionItemPropertyChanged` — Fired after any add, remove, modify, or clear operation.

**Constructors:**
- None explicitly defined; uses default constructor.

**Properties:**
- `ICollection<TKey> Keys { get; }` — Returns all keys in the collection. Delegates to internal dictionary.
- `ICollection<TItem> Values { get; }` — Returns all values in the collection. Delegates to internal dictionary.
- `TItem this[TKey key] { get; set; }` — Indexer. Getter returns value for key; setter assigns value and fires `ChangeSettingType.Add` event.
- `int Count { get; }` — Returns count of items.
- `bool IsReadOnly { get; }` — Always returns `false`.

**Methods:**
- `void Add(TKey key, TItem value)` — Adds key-value pair; fires `ChangeSettingType.Add` event.
- `void Add(KeyValuePair<TKey, TItem> item)` — Adds key-value pair; fires `ChangeSettingType.Add` event.
- `bool ContainsKey(TKey key)` — Returns `true` if key exists.
- `bool Contains(KeyValuePair<TKey, TItem> item)` — Returns `true` if both key and value match an entry.
- `bool Remove(TKey key)` — Removes by key; fires `ChangeSettingType.Remove` event if successful. Returns success boolean.
- `bool Remove(KeyValuePair<TKey, TItem> item)` — Removes by key (ignores value); fires `ChangeSettingType.Remove` event if successful. Returns success boolean.
- `bool TryGetValue(TKey key, out TItem value)` — Attempts to retrieve value for key.
- `void Clear()` — Clears all items; fires `ChangeSettingType.ClearAll` event.
- `void CopyTo(KeyValuePair<TKey, TItem>[] array, int arrayIndex)` — **Throws `NotImplementedException`.**
- `IEnumerator<KeyValuePair<TKey, TItem>> GetEnumerator()` — Returns enumerator.
- `IEnumerator IEnumerable.GetEnumerator()` — Returns non-generic enumerator.

---

### `SettingsChangedEventArgs<TKey, TItem>`

Event arguments describing a settings change.

**Constructors:**
- `SettingsChangedEventArgs(ChangeSettingType changeType)` — Initializes with change type only.
- `SettingsChangedEventArgs(ChangeSettingType changeType, TKey key)` — Initializes with change type and key.
- `SettingsChangedEventArgs(ChangeSettingType changeType, TKey key, TItem item)` — Initializes with change type, key, and item.

**Properties:**
- `ChangeSettingType ChangeType { get; }` — The type of change (read-only).
- `TKey Key { get; }` — The key associated with the change (read-only).
- `TItem Item { get; }` — The value associated with the change (read-only).

---

### `ChangeSettingType` (enum)

Defines the type of settings change.

| Value | Name | Numeric Value |
|-------|------|---------------|
| `Add` | Item added | 0 |
| `Remove` | Item removed | 1 |
| `Modified` | Item modified | 3 |
| `ClearAll` | Collection cleared | 4 |

---

## 3. Invariants

- **Event firing occurs after mutation:** Events are fired only after the underlying dictionary has been successfully modified (e.g., `Remove` fires only if removal succeeded).
- **Key and Item properties may be default/uninitialized:** Depending on which constructor is used, `Key` and `Item` may be `default(TKey)` or `default(TItem)` respectively. Consumers should check `ChangeType` to determine which properties are meaningful.
- `IsReadOnly` always returns `false`.
- The internal `_items` dictionary is never null (initialized at declaration).

---

## 4. Dependencies

**This module depends on:**
- `System` (for `EventArgs`, `EventHandler<T>`)
- `System.Collections` (for `IEnumerable`)
- `System.Collections.Generic` (for `IDictionary<TKey, TItem>`, `Dictionary<TKey, TItem>`, `ICollection<T>`, `KeyValuePair<TKey, TItem>`)

**Consumers (inferred):**
- Any module requiring observable settings/configuration storage.
- Cannot determine specific consumers from source alone.

---

## 5. Gotchas

1. **Indexer setter uses `ChangeSettingType.Add`, not `Modified`:** The indexer `this[TKey key]` setter always fires `ChangeSettingType.Add`, even when overwriting an existing key. The `Modified` enum value (3) is never used in this implementation.

2. **`CopyTo` is not implemented:** Calling `CopyTo(KeyValuePair<TKey, TItem>[] array, int arrayIndex)` throws `NotImplementedException`. This will cause runtime failures if the collection is used with APIs that call `CopyTo`.

3. **`Remove(KeyValuePair<TKey, TItem>)` ignores the value:** The `Remove(KeyValuePair<TKey, TItem> item)` method only checks and removes by key, ignoring `item.Value`. This differs from typical `IDictionary` implementations that verify the value matches before removal.

4. **Enum has a gap:** `ChangeSettingType` has values 0, 1, 3, 4 — value 2 is skipped. This may indicate a removed/renamed value or historical artifact.

5. **No validation on constructor arguments:** `SettingsChangedEventArgs` constructors do not validate that `Key` and `Item` are provided when `ChangeType` would logically require them (e.g., `Add` without a key/item).