You can add optional attributes and a login-change method to SysSingleton so Turnkey exposes request and session context to your model; this page is for MDriven modelers who need the client IP address, client user agent, runtime type, or a hook when the current user changes.

Overview

SysSingleton is the application root used by the Turnkey login pattern. When Turnkey finds specific optional members on SysSingleton, it can populate them from the current client request or call a method when CurrentUser changes.

These members are optional. Turnkey uses them only when they are present in the model.

Optional request-context attributes

When an application is open through StreamingApp_API_Base, Turnkey checks SysSingleton for the attributes in the following table. If an attribute is present, Turnkey fills it with the corresponding value.

Add this attribute to SysSingleton	Type and persistence	Value supplied by Turnkey	Example use
ClientIp	String?; mark as Transient	The client IP address	Record the IP address associated with an operation while handling the current session.
SystemType	String?; mark as Transient	TurnkeyNetFramework or TurnkeyNetCore	Adapt model behavior that depends on which Turnkey runtime is serving the application.
UserAgent	String?; mark as Transient	The User-Agent value sent by the client	Inspect the client identifier when diagnosing a browser-specific issue.

A question mark in String? means the attribute is optional (nullable). Do not assume that a value is always available; account for an empty or null value in expressions and actions that use these attributes.

Configure the attributes

1. Open the SysSingleton class in your model.
2. Add the attribute with the exact name shown in the table. Attribute names must match exactly for Turnkey to recognize them.
3. Set its type to String?.
4. Mark the attribute Transient (non-persistent).
5. Repeat for each context value your application needs.

For example, add ClientIp:String? as a transient attribute when an action needs to examine the IP address of the client currently using the application.

Why these attributes must be transient

Request context belongs to the active user session, not to the permanent application data. Marking these attributes as transient prevents a value from being persisted and later treated as application state for another session.

For example, if UserAgent were persisted, the browser identifier from one user session could remain on SysSingleton after that request has ended. A transient UserAgent instead represents the value Turnkey supplies for the current client context.

Respond when the current user changes

From 2023-10-17, Turnkey calls OnCurrentUserChanged when it finds that method on SysSingleton and CurrentUser is set or cleared. This occurs when a user logs in or logs out.

Use this method as a model-level hook for work that must occur when the logged-in user changes. For example, use it to initialize or clear state that depends on CurrentUser, rather than leaving that state associated with the previous user.

In an MVC application, Turnkey also performs this call on postback. Make the method safe to run repeatedly: code in the method must tolerate being called again for the same current user during a postback.

SysUser and SysSingleton together implement the user-login pattern. For OCL expressions that access the singleton instance, see oclSingleton.

Scope and limitations

• These attributes and the callback are recognized only when they are defined on SysSingleton.
• The request-context attributes are supplied when Turnkey finds them while the application is open through StreamingApp_API_Base.
• Treat ClientIp, SystemType, and UserAgent as session/request context. Do not use persistent storage on SysSingleton to retain them between sessions.
• OnCurrentUserChanged is tied to setting or clearing CurrentUser. It is not a general notification for every change to a SysUser object.

Related SysSingleton extensions

This page covers optional session and request-context members. Other SysSingleton extensions have separate purposes:

• GetSystemUrl provides the running Turnkey system URL.
• SysSingleton.MiscSetting provides access to recognized TurnkeyServer settings through an ExternalLateBound method.
• SysViewStateCookie is an optional model pattern for shareable links that contain view state.

See also

• Documentation:SysSingleton
• Documentation:SysUser
• Documentation:OCLOperators oclSingleton
• Documentation:SysSingleton GetSystemUrl
• Documentation:SysSingleton.MiscSetting