---
title: Cookie and session helpers
summary: Reads and writes cookies, user settings, and typed session objects.
status: draft
owner: SAIF IT Core Services
last_reviewed: 2026-10-12
library: BolMiddleware
reference_type: package
operation_id: OP-16
trigger: Calls from page models and services
---

# Cookie and session helpers

Three small helpers handle storage details so the page models do not touch cookies and session JSON directly: `CookieService`, `ContextCookieHelperService`, and the session extension methods.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-16 |
| **Trigger** | Calls from page models and services |
| **Inputs** | Keys, values, timeout in seconds, `ContextCookie` |
| **Outputs** | Stored or retrieved values |
| **Primary components** | `CookieService`, `ContextCookieHelperService`, `BolServiceSessionExtensions`, `SessionExtensions` |
| **Entry point** | `src/BolMiddleware/Services/CookieService/CookieService.cs` |

## Steps

1. `SetCookie` appends a cookie with HttpOnly set and an expiry of the supplied number of seconds from the local clock; `SetCookieObject` serializes the object to JSON first ([BR-BOLMIDDLEWARE-004](../business-rules.md#br-bolmiddleware-004-context-cookie-lifetime-and-flags)).
2. `GetCookie`, `GetCookieObject`, and `DoesCookieExist` read from the request cookie collection; `DeleteCookie` removes the cookie.
3. `ContextCookieHelperService` adds, removes, reads, and tests entries in `ContextCookie.userSettings`; a null key or value throws `ArgumentNullException`.
4. `SetObject` and `GetObject<T>` serialize session values with Newtonsoft JSON; `SaveWebContext`, `SaveMenu`, and `SavePolicyHeader` store under the `WebContextKey`, `WebContextId`, `BolMenu`, and `BolPolicyHeader` keys.
   - If the session value is empty or cannot be deserialized to a value: `GetObject<T>` returns the default value.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Helper call]) --> D1{Storage type?}
	D1 -->|Cookie| S1[CookieService]
	D1 -->|User setting| S2[ContextCookieHelperService]
	D1 -->|Session| S3[Session extensions]
	S1 --> EndOk([Value stored or returned])
	S2 --> EndOk
	S3 --> EndOk
```

## Failure and edge-case behavior

- Cookies are written without Secure or SameSite attributes.
- Session objects use JSON text, so type changes between package versions can produce default values for older sessions.

## 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/Services/CookieService/CookieService.cs
- src/BolMiddleware/ContextCookieHelper/ContextCookieHelper.cs
- src/BolMiddleware/Extensions/BolMiddlewareExtensions.cs
- src/BolMiddleware/Contracts/Constants.cs