---
title: Read a preference value
summary: Retrieves a stored preference value from the in-memory cache by key and scope.
status: draft
owner: SAIF Documentation Team
last_reviewed: 2026-08-17
library: SAIF.Presentation
reference_type: package
operation_id: OP-PREF-002
trigger: Consumer code accesses the Item indexer
---

# Read a preference value

This operation returns a cached preference value entirely from memory, without any database round-trip, using one of three `Item` indexer overloads to select the application/page/scope combination to search.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-PREF-002 |
| **Trigger** | Consumer code accesses `instance(key)`, `instance(key, scope)`, or `instance(app, page, key)` |
| **Inputs** | Key (any object), optional `PrefScope`, optional explicit application/page |
| **Outputs** | The stored preference value (`Object`) or `Nothing` if not found |
| **Primary components** | `clsPreferences.Item` (three overloads) |
| **Entry point** | SAIF.Presentation\clsPreferences.vb |

## Steps

1. Normalize the key to a lower-case string ([BR-PREF-002](../business-rules.md#br-pref-002-preference-key-case-normalization)); if `inKey` is `Nothing`, return `Nothing` immediately.
   - If `inKey` is `Nothing`: return `Nothing` without further processing.
2. Look up the matching `Preference` group by `ApplicationName` (case-sensitive for the 2-argument overloads*, case-insensitive for the 3-argument overload) and `Pagename` (derived via `PageKey(scope)`, which returns `Page.ToLower()` only for `PageLevel` scope, else empty string) ([BR-PREF-001](../business-rules.md#br-pref-001-preference-scoping-by-application-and-page)).
3. If the group is found and contains the (lower-cased) key in `PreferenceItems`, return the value; otherwise return `Nothing`.
   - If the group is not found: return `Nothing`.
   - If the key is not present in `PreferenceItems`: return `Nothing`.

No business-rule validation or error branching occurs beyond the above.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Item indexer accessed]) --> S1{Key is Nothing?}
	S1 -->|Yes| EndNothing([Return Nothing])
	S1 -->|No| S2[Normalize key to lower-case]
	S2 --> S3[Find matching Preference group by app/page]
	S3 --> S4{Group found and key present?}
	S4 -->|Yes| EndValue([Return stored value])
	S4 -->|No| EndNothing2([Return Nothing])
```

## Failure and edge-case behavior

- A missing group or missing key both silently return `Nothing`; no exception or error signal distinguishes "not found" from other conditions.
- The 2-argument `Item` overloads compare `ApplicationName` case-sensitively, while the 3-argument overload lowercases both `ApplicationName` and `Pagename` before comparing — an inconsistency in case-handling between overloads*.

> **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