---
title: Add or update a preference value
summary: Upserts a preference item into the in-memory Preference set.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-08-17
library: SAIF.Presentation
reference_type: package
operation_id: OP-PRES-003
trigger: Consuming code stores a preference (for example, a saved grid layout)
---

# Add or update a preference value

This operation upserts a single preference key/value pair into the in-memory `Preference` set. The change is not persisted until [Persist preferences](persist-preferences.md) runs.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-PRES-003 |
| **Trigger** | Consuming code calls `Add(inKey, inValue)` or `Add(inKey, inValue, inScope)` |
| **Inputs** | Key, value, optional `PrefScope` (defaults to `PageLevel`) |
| **Outputs** | Mutated in-memory `Preference` record |
| **Primary components** | `clsPreferences.Add` (two overloads) |
| **Entry point** | `SAIF.Presentation/clsPreferences.vb` |

## Steps

1. Return silently if the key is `Nothing` ([BR-PRES-006](../business-rules.md#br-pres-006-a-nothing-key-is-a-no-op)).
2. Lower-case the key ([BR-PRES-007](../business-rules.md#br-pres-007-preference-keys-are-case-insensitive)).
3. Locate the `Preference` record for the current application + resolved page key.
   - If none exists: create a new `Preference`, set its `ApplicationName` and `Pagename`, and append it to the list ([BR-PRES-013](../business-rules.md#br-pres-013-adding-a-preference-creates-a-missing-record)).
4. If the key already exists in `PreferenceItems`, remove it first, then add the new value as `inValue.ToString()` ([BR-PRES-014](../business-rules.md#br-pres-014-adding-an-existing-key-replaces-its-value), [BR-PRES-015](../business-rules.md#br-pres-015-preference-values-stored-as-strings)).

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Add key, value, scope]) --> D1{Key is Nothing?}
	D1 -->|Yes| EndNoop([Return, no-op])
	D1 -->|No| S1[Lower-case key]
	S1 --> S2[Locate matching Preference record]
	S2 --> D2{Record exists?}
	D2 -->|No| S3[Create new Preference record and append]
	D2 -->|Yes| S4[Use existing record]
	S3 --> S5
	S4 --> S5[Key already present?]
	S5 -->|Yes| S6[Remove existing item]
	S5 -->|No| S7[Add new item]
	S6 --> S7
	S7 --> EndOk([In-memory record updated])
```

## Failure and edge-case behavior
- A `Nothing` key is a silent no-op rather than an error ([BR-PRES-006](../business-rules.md#br-pres-006-a-nothing-key-is-a-no-op)).
- The change is in-memory only — nothing is persisted until [Persist preferences](persist-preferences.md) runs ([BR-PRES-019](../business-rules.md#br-pres-019-mutations-are-in-memory-until-save)).

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

## Sources
- `SAIF.Presentation/clsPreferences.vb`