Skip to content

Read a preference value

This operation serves keyed lookups entirely from the in-memory Preference set loaded by Construct and load a user's preferences; it issues no database calls.

Field Value
Operation ID OP-PRES-002
Trigger Consuming code indexes into the preference store via Item
Inputs Key (and optionally scope, or explicit application + page)
Outputs The stored value, or Nothing when not found
Primary components clsPreferences.Item (three overloads), clsPreferences.PageKey, clsPreferences.Page, clsPreferences.IsWeb
Entry point SAIF.Presentation/clsPreferences.vb

Steps

  1. Return Nothing immediately if the key is Nothing (BR-PRES-006).
  2. Lower-case the key (BR-PRES-007).
  3. Resolve the page key: PrefScope.PageLevel yields the derived page name; every other scope yields an empty string (BR-PRES-008).
  4. Derive the page name via the Page property:
  5. If System.Web.HttpContext.Current is non-null (web context), take the substring of Request.Path after the last / (BR-PRES-009).
  6. Otherwise use OverridePage when it is non-empty, else reflect the declaring type name from stack frame 1 of a StackTrace(4) (BR-PRES-010).
  7. Find the first Preference whose ApplicationName matches the current application and whose Pagename matches the page key (BR-PRES-011).
  8. If no record matches: return Nothing.
  9. Return PreferenceItems(key) when the key exists in that record, otherwise Nothing.
  10. For the three-argument overload (Item(inApplication, inPage, inKey)), scope resolution is skipped entirely: application, page, and key are lower-cased (mapping Nothing to an empty string) and matched directly against the lower-cased record fields (BR-PRES-012).

No SQL is executed by any read — all reads are served from the collection loaded in Construct and load a user's preferences.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Item lookup]) --> D1{Key is Nothing?}
    D1 -->|Yes| EndNull1([Return Nothing])
    D1 -->|No| S1[Lower-case key]
    S1 --> S2[Resolve page key from scope]
    S2 --> S3[Derive page name: web path or OverridePage/call stack]
    S3 --> S4[Find matching Preference record]
    S4 --> D2{Record found?}
    D2 -->|No| EndNull2([Return Nothing])
    D2 -->|Yes| S5[Look up key in PreferenceItems]
    S5 --> D3{Key present?}
    D3 -->|Yes| EndVal([Return value])
    D3 -->|No| EndNull3([Return Nothing])

Failure and edge-case behavior

  • A Nothing key returns Nothing rather than throwing (BR-PRES-006).
  • No matching Preference record for the application/page returns Nothing rather than throwing.
  • Outside a web context with no OverridePage set, the page name is derived by reflecting the call stack, which is brittle to refactors that add or remove stack frames.*

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • SAIF.Presentation/clsPreferences.vb