View source for Documentation:SysSingleton optional properties

You can add optional attributes and a login-change method to [[Documentation:SysSingleton|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 ==
[[Documentation:SysSingleton|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 <code>CurrentUser</code> 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 <code>StreamingApp_API_Base</code>, Turnkey checks SysSingleton for the attributes in the following table. If an attribute is present, Turnkey fills it with the corresponding value.

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

A question mark in <code>String?</code> 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.

Turnkey recognizes the following optional SysSingleton properties during StreamingApp_API_Base Open:
Turnkey now checks for filled SysSingleton properties if found(in StreamingApp_API_Base Open). We strongly suggest you have these as non-persistent to get the desired per-user-session result:
* '''SysSingleton.ClientIp:String?, Transient''' - if found, Turnkey will fill in with ClientIp.
* '''SysSingleton.SystemType:String?, Transient''' - if found, Turnkey will fill in with ''TurnkeyNetFramework'' or ''TurnkeyNetCore.''
* '''SysSingleton.UserAgent:String?, Transient''' - if found, Turnkey will fill in with User-agent from the client.
* From '''2023-10-17''', we call a method '''OnCurrentUserChanged''' if found on SysSingleton whenever the CurrentUser is set or nulled out. This happens when a user logs in our out. For MVC, it happens on postback. 
[[File:2021-09-23 12h32 30.png|none|thumb]]'''See also:''' [[Documentation:SHA512ComputeHash, SHA256ComputeHash and BitConverterToString|SHA512ComputeHash,_SHA256ComputeHash_and_BitConverterToString]]
=== Configure the attributes ===

# Open the SysSingleton class in your model.
# Add the attribute with the exact name shown in the table. Attribute names must match exactly for Turnkey to recognize them.
# Set its type to <code>String?</code>.
# Mark the attribute '''Transient''' (non-persistent).
# Repeat for each context value your application needs.

For example, add <code>ClientIp:String?</code> 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 <code>UserAgent</code> were persisted, the browser identifier from one user session could remain on SysSingleton after that request has ended. A transient <code>UserAgent</code> instead represents the value Turnkey supplies for the current client context.
== Respond when the current user changes ==

From 2023-10-17, Turnkey calls <code>OnCurrentUserChanged</code> when it finds that method on SysSingleton and <code>CurrentUser</code> 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 <code>CurrentUser</code>, 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.

[[Documentation:SysUser|SysUser]] and SysSingleton together implement the user-login pattern. For OCL expressions that access the singleton instance, see [[Documentation:OCLOperators oclSingleton|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 <code>StreamingApp_API_Base</code>.
* Treat <code>ClientIp</code>, <code>SystemType</code>, and <code>UserAgent</code> as session/request context. Do not use persistent storage on SysSingleton to retain them between sessions.
* <code>OnCurrentUserChanged</code> is tied to setting or clearing <code>CurrentUser</code>. 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:

* [[Documentation:SysSingleton GetSystemUrl|GetSystemUrl]] provides the running Turnkey system URL.
* [[Documentation:SysSingleton.MiscSetting|SysSingleton.MiscSetting]] provides access to recognized TurnkeyServer settings through an ExternalLateBound method.
* [[Documentation:SysViewStateCookie|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]]

[[Category:Intermediate-Friendly]]
[[Category:MDriven Turnkey]]
[[Category:Priority 60]]
[[Category:Turnkey Features & Modules]]