---
title: Page handler selection initialization
summary: Prepares the request helper, application name, cookie state, and web context before a page handler runs.
status: draft
owner: SAIF IT Core Services
last_reviewed: 2026-10-12
library: BolMiddleware
reference_type: package
operation_id: OP-03
trigger: Razor Pages handler selection on a BolContextModel page
---

# Page handler selection initialization

Every page that derives from `BolContextModel` runs this operation before its handler. It establishes the per-request context that the menu and policy header layers build on.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-03 |
| **Trigger** | Razor Pages handler selection on a `BolContextModel` page |
| **Inputs** | HTTP request, `BolContext` cookie, session |
| **Outputs** | Populated `WebContext`, `contextCookie`, `RequestHelper`, `MyApplicationName` |
| **Primary components** | `BolContextModel.OnPageHandlerSelected` |
| **Entry point** | `src/BolMiddleware/Models/BolContextModel.cs` |

## Steps

1. Create a `RequestHelper` for the current `HttpRequest`.
2. Read the application name from the root `ApplicationName` configuration value through `GetRequiredValue`; a missing value throws.
3. Read the `BolContext` cookie into `contextCookie` when it exists ([BR-BOLMIDDLEWARE-004](../business-rules.md#br-bolmiddleware-004-context-cookie-lifetime-and-flags)).
4. Later, in `OnPageHandlerExecuting` after model binding, resolve the web context as described in [Resolve web context](resolve-web-context.md) ([BR-BOLMIDDLEWARE-001](../business-rules.md#br-bolmiddleware-001-web-context-resolution-precedence)).
5. Still in `OnPageHandlerExecuting`, for an external user run [Capture external user information](capture-external-user-information.md), which calls `ISecurityClient.GetExternalUser` ([BR-BOLMIDDLEWARE-005](../business-rules.md#br-bolmiddleware-005-external-user-detection), [BR-BOLMIDDLEWARE-006](../business-rules.md#br-bolmiddleware-006-external-user-information-lookup-once)).
   - If the user is internal: skip the lookup.
6. Make the `WebContext` available to the consumer handler.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Handler selected]) --> S1[Create RequestHelper]
	S1 --> S2[Read ApplicationName]
	S2 --> S3[Read BolContext cookie]
	S3 --> S3b([Handler executing])
	S3b --> S4[Resolve web context]
	S4 --> D{External user?}
	D -->|Yes| S5[Capture external user information]
	D -->|No| EndOk([Handler runs])
	S5 --> EndOk
```

## Failure and edge-case behavior

- A missing `ApplicationName` configuration value throws before the handler runs. The consumer sample places the value under `AppSettings`, which may not match the root key read here**.
- `ContextCookie` deserialization trusts the unsigned cookie content; the cookie is not integrity protected.

> **Note:** Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Related documentation
- [Index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Dependencies](../dependencies.md)
- [Configuration](../configuration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Security and authorization](../security-authorization.md)
- [Service registration](../service-registration.md)
- [API reference](../api/index.md)

## Sources
- src/BolMiddleware/Models/BolContextModel.cs
- src/BolMiddleware/Services/Request/RequestHelper.cs