---
title: Write or clear a preference value in memory
summary: Adds, removes, or clears preference key-value pairs in the in-memory cache without persisting to the database.
status: draft
owner: SAIF Documentation Team
last_reviewed: 2026-08-17
library: SAIF.Presentation
reference_type: package
operation_id: OP-PREF-003
trigger: Consumer code calls Add, Remove, Clear, or Delete
---

# Write or clear a preference value in memory

This operation mutates the in-memory `_Preferences` collection only; no database write occurs until the consumer separately calls [Persist preferences](save-preferences.md).

| Field | Value |
| --- | --- |
| **Operation ID** | OP-PREF-003 |
| **Trigger** | Consumer code calls `Add`, `Remove`, `Clear`, or `Delete` |
| **Inputs** | Key/value pairs and optional scope |
| **Outputs** | Mutated in-memory `_Preferences` collection; no persistence occurs until `Save()` |
| **Primary components** | `clsPreferences.Add`, `clsPreferences.Remove`, `clsPreferences.Clear`, `clsPreferences.Delete` |
| **Entry point** | SAIF.Presentation\clsPreferences.vb |

## Steps

**`Add(inKey, inValue, inScope)`:**
1. If `inKey` is `Nothing`, no-op ([BR-PREF-002](../business-rules.md#br-pref-002-preference-key-case-normalization)).
2. Find or create (if not found) a `Preference` group keyed by `(m_Application, PageKey(scope))` ([BR-PREF-001](../business-rules.md#br-pref-001-preference-scoping-by-application-and-page)).
3. If the key already exists in `PreferenceItems`, remove it first (to avoid duplicate-key exceptions), then add the new (lower-cased key, string-cast value) pair.

**`Remove(inKey, inScope)`:**
1. Wraps the operation in `clsLogTrace.MethodBegin()`/`MethodEnd()` trace calls.
2. Finds the matching group by application/scope and removes the key if present.
   - If no matching group or key is found: no-op.

**`Clear(inScope)`:**
1. Finds the matching group for the given scope and clears all its `PreferenceItems`, leaving the group itself in `_Preferences`.

**`Delete()`:**
1. Iterates **all** groups in `_Preferences` (not scoped to `m_Application`) and clears each group's `PreferenceItems` — broader in effect than `Clear()`, and not filtered to the current application*.

## Process flow

The following diagram visualizes this operation's control flow for `Add`.

```mermaid
flowchart TD
	Start([Add key/value/scope]) --> S1{Key is Nothing?}
	S1 -->|Yes| EndNoop([No-op])
	S1 -->|No| S2[Find or create Preference group by app/scope]
	S2 --> S3{Key already exists?}
	S3 -->|Yes| S4[Remove existing key]
	S3 -->|No| S5[Add new key/value pair]
	S4 --> S5
	S5 --> EndOk([In-memory group updated])
```

## Failure and edge-case behavior

- `Delete()` clears preference items across **all** loaded application groups for the user, not just the current application — a broader and less targeted operation than `Clear()`, which is scoped to the current application*.
- None of `Add`, `Remove`, `Clear`, or `Delete` write to the database; a subsequent explicit `Save()` call is required for changes to persist ([Persist preferences](save-preferences.md)).

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

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

## Sources
- SAIF.Presentation\clsPreferences.vb