---
title: clsControllerBase
summary: API reference for clsControllerBase.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-08-17
library: SAIF.Presentation.Web.MVC
reference_type: package
---

# clsControllerBase

`clsControllerBase` is the per-screen controller base class every SAIF screen's concrete controller derives from. It converts a raw ASP.NET request into the framework's fixed pipeline — session-timeout handling, security establishment, menu-based page authorization, model initialization, query-string/context processing, and control-value harvesting — and owns cross-application/in-app navigation (with context hand-off) and centralized error handling. It is the busiest class in the library: nearly every operation documented in [Operations and processes](../../operations-processes.md) is implemented here.

## Purpose
- Runs the fixed request-initialization pipeline (see [Initialize a request](../../operations/initialize-request.md)): session-timeout detection, [Establish the security principal](../../operations/establish-security-principal.md), [Enforce menu-based page authorization](../../operations/enforce-menu-authorization.md), model initialization, and inbound context handling.
- Owns cross-application and in-app navigation, including context persistence for genuine application transitions ([Navigate to a view](../../operations/navigate-to-view.md), [Navigate with a fresh model](../../operations/navigate-with-fresh-model.md)).
- Harvests every posted input control's value into a hashtable for the derived screen's `Retrieve` hook ([Harvest posted control values](../../operations/harvest-posted-control-values.md)).
- Provides the framework's terminal error handler — logging, e-mail notification, and redirect to an environment-appropriate error page ([Central error handling](../../operations/central-error-handling.md)).
- Isolates per-view model and view-data state under a GUID identifier so multiple simultaneous browser windows on the same session do not interfere with each other ([BR-MVC-008](../../business-rules.md#br-mvc-008-multi-model-view-state-is-keyed-by-a-per-view-guid)).

## Context
- Namespace: `SAIF.Presentation.Web.MVC`*
- Assembly/package: `SAIF.Presentation.Web.MVC`

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `MODEL_SUFFIX` | `Public Const MODEL_SUFFIX As String = "-model"` | Session key suffix appended to a view ID to store that view's model |
| `VIEWDATA_SUFFIX` | `Public Const VIEWDATA_SUFFIX As String = "-viewdata"` | Session key suffix appended to a view ID to store that view's loose view data |
| `ApplicationName` | `Public ReadOnly Property ApplicationName() As String` | The application (virtual directory) name this controller instance serves |
| `CurrentView` | `Public ReadOnly Property CurrentView() As String` | File name of the currently executing page, parsed from the request path |
| `IsPostBack` | `Public ReadOnly Property IsPostBack() As Boolean` | Whether the current request is a postback, read from the active `ViewPageBase` handler |
| `IsSessionTimedOut` | `Public ReadOnly Property IsSessionTimedOut() As Boolean` | `True` when a postback arrives on a session ASP.NET considers new (i.e., the original session expired) ([BR-MVC-001](../../business-rules.md#br-mvc-001-session-timeout-treated-as-an-unprocessable-postback)) |
| `IsInsideClient` | `Public ReadOnly Property IsInsideClient() As Boolean` | `True` when the caller's address matches `10.*`, `131.131.*.*`, or `127.0.0.1` — the internal-network heuristic used throughout the pipeline |
| `Model` | `Public ReadOnly Property Model() As clsModelBase` | Returns the session-stored model for the current view (keyed by `ViewID & MODEL_SUFFIX`), constructing a fresh one from the factory on first access |
| `SupportsMultiModel` | `Public Property SupportsMultiModel() As Boolean` (Private setter) | Enables per-view-GUID model isolation for multiple simultaneous windows; set once via the constructor |
| `PostBackControlName` | `Public ReadOnly Property PostBackControlName() As String` | The ID of the control that triggered the current postback, resolved via `GetPostBackControlName()` |
| `ViewData` | `Public ReadOnly Property ViewData() As System.Collections.Specialized.HybridDictionary` | Session-backed loose view data for the current view (keyed by `ViewID & VIEWDATA_SUFFIX`) |
| `New` | `Public Sub New(ByVal ApplicationName As String, ByVal Factory As clsFactoryBase, Optional ByVal inSupportsMultiModel As Boolean = False)` | Constructs the controller for the given application/factory, capturing `HttpContext.Current` and applying trace-configuration `AppSettings` (`TraceLogging`, `PageTraceOn`, `TraceUser`) inside an exception-swallowing block |
| `GetPostBackControlName` | `Public Function GetPostBackControlName() As String` | Walks the posted form collection and control tree to resolve which control (including nested controls and image-button `.x`/`.y` postbacks) caused the current postback |
| `Navigate` | `Public Function Navigate(ByVal TargetApp As String, ByVal TargetView As String, Optional ByVal Popup As Boolean = False, Optional ByVal PopupFeatures As String = "height=505,width=641,left=10,top=10,location=no,menubar=no,resizable=no,scrollbars=no,titlebar=yes,toolbar=no", Optional ByVal FocusOnChild As Boolean = True, Optional ByVal inWindowName As String = "", Optional ByVal inNewModel As String = "") As Boolean` | Navigates to an in-app or cross-app target, recording source/target app and view in the model context and persisting them for genuine cross-app transitions; see [Navigate to a view](../../operations/navigate-to-view.md) |
| `Navigate2` | `Public Function Navigate2(Optional ByVal inPopup As Boolean = True, Optional ByVal inPopupFeatures As String = "", Optional ByVal inFocusOnChild As Boolean = True, Optional ByVal inWindowName As String = "") As Boolean` (and an overload taking `inTargetApplication`/`inTargetView`) | Navigates using a brand-new model and view data under a fresh GUID, requiring `SupportsMultiModel`; see [Navigate with a fresh model](../../operations/navigate-with-fresh-model.md) |
| `SecurityCheck` | `Public Sub SecurityCheck()` | Establishes the `clsSecurityPrincipal` on the model context, sets the `STYPE` cookie, or issues a `401` challenge/hard deny; see [Establish the security principal](../../operations/establish-security-principal.md) |
| `Write` | `Public Overridable Function Write() As Boolean` | Delegates to `Model.Write`, gating persistence behind the model's own validation; see [Validate and write the model](../../operations/validate-and-write-model.md) |
| `HandleErrors` | `Protected Friend Sub HandleErrors()` and `Protected Friend Sub HandleErrors(ByVal inEx As Exception)` | Logs/e-mails the error and redirects to the central error page; see [Central error handling](../../operations/central-error-handling.md) |
| `Initialize` | `Protected Friend Sub Initialize()` | Runs the full request-initialization pipeline; see [Initialize a request](../../operations/initialize-request.md) |
| `UnInitialize` | `Protected Friend Sub UnInitialize()` | Persists the model back into session, but only when the model's `SecurityPrincipal` is set, so an unauthenticated request never seeds session model state |
| `CallRetrieve` | `Friend Sub CallRetrieve()` | Harvests all posted control values into a hashtable and calls the derived `Retrieve`; see [Harvest posted control values](../../operations/harvest-posted-control-values.md) |
| `CheckContextViewID` | `Friend Function CheckContextViewID() As String` | Resolves a returning `__SAIFPID` view ID via `clsContext.GetPID`, used to rejoin a request to the correct multi-model instance |
| `HandleContext` | `Protected Friend MustOverride Sub HandleContext(ByVal inContext As Hashtable)` | Derived-class hook invoked with inbound cross-application context values; see [Receive inbound cross-application context](../../operations/receive-inbound-context.md) |
| `Retrieve` | `Protected Friend MustOverride Sub Retrieve(ByVal inControls As System.Collections.Hashtable, ByVal inTargetView As String)` | Derived-class hook invoked with the harvested posted control values |
| `OnNewModel` | `Protected Friend Overridable Function OnNewModel(ByRef inNewModel As clsModelBase, ByRef inNewViewData As System.Collections.Specialized.HybridDictionary) As Boolean` | Derived-class hook allowing properties to be copied from the old model to a newly created one during `Navigate2`; default implementation returns `True` |
| `HandleQuerystring` | `Protected Friend Overridable Sub HandleQuerystring(ByVal inQueryString As System.Collections.Specialized.NameValueCollection)` | Derived-class hook for processing incoming query-string parameters during initialization; default implementation is a no-op |
| `Load` | `Protected Friend Overridable Sub Load()` | Derived-class hook called at the end of `Initialize` so the concrete controller can prepare screen state; default implementation is a no-op |

## Behavioral notes
- `HandleErrors(ex)` wraps its `Response.Redirect` in a `Try`/`Catch`/`Finally` that swallows `ThreadAbortException` via `ResetAbort` and always calls `Response.End()` in `Finally`, so redirect-induced thread aborts never surface as a second error ([BR-MVC-012](../../business-rules.md#br-mvc-012-redirect-induced-thread-aborts-are-suppressed)).
- `Navigate`'s exception handler in its redirect branch catches `Exception` generally (not only `ThreadAbortException`) and unconditionally calls `Thread.ResetAbort()`, which can suppress errors unrelated to the redirect itself.*
- The constructor's trace-configuration block (`TraceLogging`/`PageTraceOn`/`TraceUser`) is wrapped in a `Try`/`Catch` whose `Catch` deliberately swallows all exceptions, so a malformed trace setting silently disables the rest of trace configuration with no diagnostic.

## Constraints and usage notes
- `clsControllerBase` is `MustInherit` — every screen supplies its own concrete controller subclass and overrides `HandleContext` and `Retrieve` (both `MustOverride`).
- `Navigate2` throws `ApplicationException("Navigate2 only supported with Multiple Model configuration.")` when `SupportsMultiModel` is `False` ([BR-MVC-011](../../business-rules.md#br-mvc-011-context-is-persisted-only-on-genuine-cross-app-transitions)).
- `SupportsMultiModel`'s setter is `Private`, so it can only be configured once, through the constructor's `inSupportsMultiModel` parameter.

> **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.Web.MVC/clsControllerBase.vb