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

# clsControllerBase

`clsControllerBase` is the abstract Controller-layer base class every SAIF WebForms application derives from to get a standardized page lifecycle. It orchestrates session-timeout handling, the two authorization gates ([BR-MVC-001](../../business-rules.md#br-mvc-001-session-timeout-redirect), [BR-MVC-002](../../business-rules.md#br-mvc-002-menu-based-page-authorization), [BR-MVC-003](../../business-rules.md#br-mvc-003-authenticated-principal-required)), cross-application navigation and context hand-off, multi-model session storage, and centralized error handling — see [Operations and processes](../../operations-processes.md) for full step-by-step behavior of each area.

## Purpose
- Centralizes the request-lifecycle orchestration (`Initialize`, `CallRetrieve`, `UnInitialize`) so every consuming controller gets identical timeout, security, and navigation-context handling without reimplementing it.
- Owns cross-application navigation (`Navigate`/`Navigate2`), including persisting context to the SQL Server `Context` table when crossing application boundaries ([BR-MVC-005](../../business-rules.md#br-mvc-005-cross-application-context-transfer-only-across-distinct-applications)).
- Provides the multi-model session-storage mechanism (`SupportsMultiModel`, `ViewData`, `MODEL_SUFFIX`/`VIEWDATA_SUFFIX`) allowing multiple concurrent model instances of the same application to coexist in one session.
- Centralizes error logging/e-mail/redirect (`HandleErrors`) invoked from `ViewPageBase.ProcessError` — see [Error handling](../../operations/error-handling.md).

## Context
- Namespace: `SAIF.Presentation.Web.MVC`
- Assembly/package: `SAIF.BOF.Presentation.Web.Infragistics103` (source-bundled)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `ApplicationName` | `Public ReadOnly Property ApplicationName() As String` | The application name this controller instance is scoped to, set at construction time. |
| `CurrentView` | `Public ReadOnly Property CurrentView() As String` | The current request's page file name (e.g., `Default.aspx`), parsed from `Request.Path`. |
| `IsPostBack` | `Public ReadOnly Property IsPostBack() As Boolean` | Delegates to the hosting `ViewPageBase.IsPostBack()`. |
| `IsSessionTimedOut` | `Public ReadOnly Property IsSessionTimedOut() As Boolean` | `True` when the request `IsPostBack` and `Session.IsNewSession` — the trigger condition for [BR-MVC-001](../../business-rules.md#br-mvc-001-session-timeout-redirect). |
| `IsInsideClient` | `Public ReadOnly Property IsInsideClient() As Boolean` | `True` if the caller's host address matches `10.*`, `131.131.*.*`, or `127.0.0.1` — the classification behind [BR-MVC-008](../../business-rules.md#br-mvc-008-internal-address-classification). |
| `Model` | `Public ReadOnly Property Model() As clsModelBase` | Lazily resolves the current model: reuses the session-cached model keyed by `ViewID & MODEL_SUFFIX` if present, otherwise calls `m_factory.GetModel()` and sets its `Context.ApplicationName`. |
| `SupportsMultiModel` | `Public Property SupportsMultiModel() As Boolean` (setter is `Private`) | Whether this controller was configured to support multiple concurrent model instances; gates `Navigate2` per [BR-MVC-004](../../business-rules.md#br-mvc-004-multi-model-requires-configuration). |
| `PostBackControlName` | `Public ReadOnly Property PostBackControlName() As String` | The name of the control that triggered the current postback, resolved via `GetPostBackControlName()`. |
| `ViewData` | `Public ReadOnly Property ViewData() As System.Collections.Specialized.HybridDictionary` | Lazily resolves the current view's session-stored data dictionary, keyed by `ViewID & VIEWDATA_SUFFIX`. |
| `HandleContext` | `Protected Friend MustOverride Sub HandleContext(ByVal inContext As Hashtable)` | Abstract hook the concrete controller implements to consume context values retrieved during [Cross-application context hand-off](../../operations/cross-application-context-hand-off.md). |
| `OnNewModel` | `Protected Friend Overridable Function OnNewModel(ByRef inNewModel As clsModelBase, ByRef inNewViewData As HybridDictionary) As Boolean` | Overridable hook letting the concrete controller copy state from the old model to a newly created one during `Navigate2`; returns `True` by default. |
| `HandleQuerystring` | `Protected Friend Overridable Sub HandleQuerystring(ByVal inQueryString As NameValueCollection)` | Overridable hook for query-string processing during `Initialize()`; no-op by default. |
| `Load` | `Protected Friend Overridable Sub Load()` | Overridable hook invoked during `Initialize()`; no-op by default. |
| `Retrieve` | `Protected Friend MustOverride Sub Retrieve(ByVal inControls As Hashtable, ByVal inTargetView As String)` | Abstract hook the concrete controller implements to populate page controls from model data; invoked by `CallRetrieve()`. |
| `GetPostBackControlName` | `Public Function GetPostBackControlName() As String` | Inspects the posted form collection and current page's control tree to determine which control initiated the postback (button click, image button, or `__EVENTTARGET`). |
| `HandleErrors()` | `Protected Friend Sub HandleErrors()` | Overload that forwards `m_HttpContext.Error` to `HandleErrors(ex)`. |
| `HandleErrors(inEx)` | `Protected Friend Sub HandleErrors(ByVal inEx As Exception)` | Logs and e-mails the exception via `clsLogError.CreateErrorWithEmail` (recipient from the `policymanagement.supportemaillist` config key), resolves an error page (`AppSettings["ErrorPageName"]` or a hardcoded internal/external URL), then redirects with `MSG=`/`Return=` query parameters — see [Error handling](../../operations/error-handling.md). |
| `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 a target application/view, persisting context to the `Context` table when crossing application boundaries ([BR-MVC-005](../../business-rules.md#br-mvc-005-cross-application-context-transfer-only-across-distinct-applications)); see [Cross-application navigation](../../operations/cross-application-navigation.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` | Overload that calls the full `Navigate2` with the current `ApplicationName`/`CurrentView` as target. |
| `Navigate2 (target application and view overload)` | `Public Function Navigate2(ByVal inTargetApplication As String, ByVal inTargetView As String, Optional ByVal inPopup As Boolean = True, Optional ByVal inPopupFeatures As String = "", Optional ByVal inFocusOnChild As Boolean = True, Optional ByVal inWindowName As String = "") As Boolean` | Creates a brand-new model/view-data pair in session and navigates to it; requires `SupportsMultiModel` ([BR-MVC-004](../../business-rules.md#br-mvc-004-multi-model-requires-configuration)), otherwise throws `ApplicationException`. |
| `New(ApplicationName, Factory, inSupportsMultiModel)` | `Public Sub New(ByVal ApplicationName As String, ByVal Factory As clsFactoryBase, Optional ByVal inSupportsMultiModel As Boolean = False)` | Stores the factory/application name, captures the current `HttpContext`, and configures `clsLogTrace` tracing from the `TraceLogging`/`PageTraceOn`/`TraceUser` AppSettings keys (errors during trace configuration are silently swallowed). |
| `SecurityCheck` | `Public Sub SecurityCheck()` | Verifies/establishes an authenticated `clsSecurityPrincipal` on `Model.Context`; enforces [BR-MVC-003](../../business-rules.md#br-mvc-003-authenticated-principal-required). |
| `Write` | `Public Overridable Function Write() As Boolean` | Calls `Model.Write()`; see [Model write pipeline](../../operations/model-write-pipeline.md) and [BR-MVC-006](../../business-rules.md#br-mvc-006-write-requires-prior-validation). |
| `CallRetrieve` | `Friend Sub CallRetrieve()` | Reflects over the current page's controls (`GetInControls`) and invokes the abstract `Retrieve(controls, targetView)` hook. |
| `CheckContext` | `Protected Sub CheckContext(ByVal inAppPath As String)` | Derives source/current application names from the referrer and current path and, if they differ, retrieves and consumes hand-off context; see [Cross-application context hand-off](../../operations/cross-application-context-hand-off.md). |
| `CheckContextViewID` | `Friend Function CheckContextViewID() As String` | Resolves the `SAIFPID_NAME` context value for the current session via `clsContext.GetPID` ([SQL-MVC-003](../../sql/SQL-MVC-003-retrieve-single-context-value.md)). |
| `Initialize` | `Protected Friend Sub Initialize()` | Orchestrates the full request-initialization sequence — see [Page/control lifecycle initialization](../../operations/page-control-lifecycle-initialization.md). |
| `UnInitialize` | `Protected Friend Sub UnInitialize()` | Persists the current `Model` and `ViewData` into `Session`, called from `ViewPageBase.Page_Unload`. |

## Behavioral notes
- `Model` and `ViewData` both derive their session keys from `ViewPage.ViewID`, so multiple concurrent view instances (under `SupportsMultiModel`) never collide in session storage as long as each has a distinct `ViewID`.
- `SecurityCheck()`'s `Set` accessor for `SupportsMultiModel` is `Private`, so it can only be toggled via the constructor's `inSupportsMultiModel` parameter — consuming controllers cannot change it after construction.
- All `Response.Redirect`/`Response.End` call sites in this class swallow `ThreadAbortException` via `Thread.ResetAbort()`, a defensive pattern applied consistently across `Initialize`, `Navigate`, and `HandleErrors`.

## Constraints and usage notes
- `HandleContext` and `Retrieve` are `MustOverride` — every concrete controller must implement both; there is no usable default behavior.
- `Navigate2` (either overload) throws `ApplicationException("Navigate2 only supported with Multiple Model configuration.")` if the controller was constructed with `inSupportsMultiModel:=False` ([BR-MVC-004](../../business-rules.md#br-mvc-004-multi-model-requires-configuration)).

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