---
title: clsPreferences
summary: API reference for clsPreferences.
status: draft
owner: SAIF Documentation Team
last_reviewed: 2026-08-17
library: SAIF.Presentation
reference_type: package
---

# clsPreferences

`clsPreferences` is the sole public service in this library: a serializable, in-memory, per-user preference cache that eagerly loads all `Preference` groups for the authenticated portal user on construction and mediates scoped reads and writes against that cache, deferring all durable persistence to `SAIF.Framework.Preferences.PreferenceData` until an explicit `Save()` call. It is consumed as a same-repo project reference by `SAIF.Presentation.Web.Core.Infragistics103`, `SAIF.Presentation.Web.MVC` (`clsModelBase.Preferences`), `SAIF.Presentation.Web.Controls.V2.Menu` (`SAIFMenu`), and `SAIF.Presentation.Web.Controls.AJAX.Infragistics103` (`InfragisticsGridCustomizer`).

## Purpose
- Cache all preference groups for the current data-portal user in memory on construction, avoiding a database round-trip on every subsequent read.
- Provide scoped read/write access to preference key-value pairs via `PrefScope`, so consumers can store settings at application, page, or web granularity ([BR-PREF-001](../../business-rules.md#br-pref-001-preference-scoping-by-application-and-page)).
- Serve as the persistence boundary for preference changes, batching in-memory mutations until an explicit `Save()` call writes them to the Oracle-backed store.

## Context
- Namespace: `SAIF.Presentation`
- Assembly/package: `SAIF.BOF.Presentation.Web.Infragistics103` (NuGet package; this project's `.vb` source is bundled and recompiled by consumers rather than shipped as a compiled binary)*

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `Item` (default indexer) | `Item(inKey As Object) As Object` | Returns a preference value at `PrefScope.PageLevel` for the current application/page — the shorthand read path most consumers use. |
| `Item` (default indexer, overload) | `Item(inKey As Object, inScope As PrefScope) As Object` | Returns a preference value for the current application at an explicitly chosen scope, enabling application- or web-level lookups. |
| `Item` (default indexer, overload) | `Item(inApplication As String, inPage As String, inKey As String) As Object` | Returns a preference value for an explicitly named application/page/key combination, case-insensitively — used when reading another application's or page's preferences rather than the current context's. |
| `Count` | `Count As Integer` (ReadOnly) | Reports the number of loaded `Preference` groups (not individual keys) for the current user, useful for diagnostics or conditional logic on whether any preferences exist. |
| `OverridePage` | `OverridePage As String = ""` | Lets non-web callers (e.g., Windows Forms) explicitly set the "page" identity instead of relying on fragile stack-trace inference; must be set immediately after construction and before any scoped call. |
| `Add` | `Add(inKey As Object, inValue As Object)` | Adds or replaces a page-level preference key-value pair in memory ([BR-PREF-002](../../business-rules.md#br-pref-002-preference-key-case-normalization)); does not persist until `Save()` is called. |
| `Add` (overload) | `Add(inKey As Object, inValue As Object, inScope As PrefScope)` | Adds or replaces a preference key-value pair at the specified scope in memory; does not persist until `Save()` is called. |
| `Delete` | `Delete()` | Clears preference items across **all** loaded application/page groups for the user, not just the current application — a broader operation than `Clear()`*. |
| `Clear` | `Clear(inScope As PrefScope)` | Clears all preference items for the current application at the given scope, leaving the group itself in place. |
| `Remove` | `Remove(inKey As Object)` | Removes a single page-level preference key if present; wrapped in `clsLogTrace` method tracing. |
| `Remove` (overload) | `Remove(inKey As Object, inScope As PrefScope)` | Removes a single preference key at the specified scope if present; wrapped in `clsLogTrace` method tracing. |
| `Save` | `Save() As Boolean` | Persists all in-memory preference groups matching the current application to the Oracle-backed store via `PreferenceData.SavePreferences`; the return value is always `False` regardless of outcome, so success can only be inferred from the absence of a thrown `ApplicationException` ([BR-PREF-003](../../business-rules.md#br-pref-003-save-scoped-to-current-application), [BR-PREF-004](../../business-rules.md#br-pref-004-save-return-value-is-unreliable)). |
| `New` (constructor) | `New(inUserID As String, inApplication As String)` | Initializes the instance and eagerly loads all preference groups for the data-portal-authenticated user (not necessarily `inUserID`) and the given application ([BR-PREF-005](../../business-rules.md#br-pref-005-fixed-oracle-database-user)). |
| `New` (constructor, overload) | `New(inUserID As String, inApplication As String, preferencesRootDirectory As String)` | Accepts a `preferencesRootDirectory` parameter documented as enabling file-based preference storage, but the parameter is ignored — the implementation always loads from the Oracle-backed `PreferenceData`, so the XML doc comment and actual behavior diverge*. |

## Behavioral notes
- Construction always resolves the effective user context from `IDataPortalInfo.UserID` (obtained from the Oracle data layer), not from the `inUserID` constructor argument — callers should not assume the instance is scoped to the literal string they passed in*.
- `Page` identity resolution differs by execution context: web requests parse `HttpContext.Current.Request.Path`; non-web contexts use `OverridePage` if set, otherwise infer the calling Windows Form's type name via `System.Diagnostics.StackTrace` reflection — a mechanism sensitive to call-stack depth and fragile if the class hierarchy changes*.
- All persistence is hard-wired to the Oracle DB user `"CLM"`, regardless of the consuming application ([BR-PREF-005](../../business-rules.md#br-pref-005-fixed-oracle-database-user)).
- The private `FormatKey` method exists but has no discoverable caller in this file, suggesting it may be vestigial from an earlier key-formatting scheme**.

## Constraints and usage notes
- Because `Save()`'s boolean return value is always `False`, consumers must catch `ApplicationException` to detect save failures rather than checking the return value ([BR-PREF-004](../../business-rules.md#br-pref-004-save-return-value-is-unreliable)).
- The 3-argument constructor's `preferencesRootDirectory` parameter should not be relied upon for file-based storage behavior — it has no effect on the current implementation*.
- `OverridePage` must be set immediately after construction (before any `Item`/`Add`/`Remove`/`Save` call) to take effect, per its own XML documentation remark.

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

## Sources
- SAIF.Presentation\clsPreferences.vb