Class SoPreference
Reads user preferences at several levels, returning the preference value that is defined at the lowest level.
A user preference defined at level 5 is more specific than a preference read at level 2.
Inherited Members
Namespace: SuperOffice.Data
Assembly: SoDataBase.dll
Syntax
public static class SoPreferenceRemarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.Properties
CacheLifetime
Cache lifetime in seconds for user preferences; note that the cache used will expire when principal is recycled (roundtrip end if in typical Web context)
Declaration
public static double CacheLifetime { get; set; }Property Value
| Type | Description |
|---|---|
| double | The cache lifetime in seconds (default 60). |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.Methods
GetBool(string, string, bool)
Get boolean value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
public static bool GetBool(string section, string key, bool defaultValue)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
| bool | defaultValue | Default value |
Returns
| Type | Description |
|---|---|
| bool | User preference. If the user preference does not excist, the defualtValue is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetBoolAsync(string, string, bool, CancellationToken)
Get boolean value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
[CreateSyncVersion(OmitNullableDirective = true)]
public static Task<bool> GetBoolAsync(string section, string key, bool defaultValue, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
| bool | defaultValue | Default value |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<bool> | User preference. If the user preference does not excist, the defualtValue is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetDateTimeAsync(string, string, DateTime, CancellationToken)
Get DateTime value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
public static Task<DateTime> GetDateTimeAsync(string section, string key, DateTime defaultValue, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
| DateTime | defaultValue | Default value |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<DateTime> | User preference. If the user preference does not exist, the defualtValue is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetDateTimeAsync(string, string, CancellationToken)
Get DateTime value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
public static Task<DateTime> GetDateTimeAsync(string section, string key, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<DateTime> | User preference. If the user preference does not exist, midnight January 1st, 1970 is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetInt(string, string, int)
Get integer value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
public static int GetInt(string section, string key, int defaultValue)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
| int | defaultValue | Default value |
Returns
| Type | Description |
|---|---|
| int | User preference. If the user preference does not exist, the defualtValue is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetIntAsync(string, string, int, CancellationToken)
Get integer value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
[CreateSyncVersion(OmitNullableDirective = true)]
public static Task<int> GetIntAsync(string section, string key, int defaultValue, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
| int | defaultValue | Default value |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<int> | User preference. If the user preference does not exist, the defualtValue is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetKeysAsync(string, CancellationToken)
Get all available keys within a section from the cache if possible, otherwise from the database.
Declaration
public static Task<string[]> GetKeysAsync(string section, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string[]> | Available keys in the section. |
Remarks
An intended side effect is that the value cache for each key are set.
GetPreference(string, string, int, PreferenceLevel, bool)
Get a preference value directly from the database, specifying a full section/key/level/owner independent of the current user
Declaration
public static string GetPreference(string section, string key, int ownerId, PreferenceLevel level, bool skipPermissionCheck = false)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Preference section |
| string | key | Preference key |
| int | ownerId | The id to set for the ownerId field. This will point to different id type depending on the preference type |
| PreferenceLevel | level | The level to set for this preference |
| bool | skipPermissionCheck | Set this to true to skip the check for setting system wide preferences |
Returns
| Type | Description |
|---|---|
| string |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetPreferenceAsync(string, string, int, PreferenceLevel, bool, CancellationToken)
Get a preference value directly from the database, specifying a full section/key/level/owner independent of the current user
Declaration
[CreateSyncVersion(OmitNullableDirective = true)]
public static Task<string> GetPreferenceAsync(string section, string key, int ownerId, PreferenceLevel level, bool skipPermissionCheck = false, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Preference section |
| string | key | Preference key |
| int | ownerId | The id to set for the ownerId field. This will point to different id type depending on the preference type |
| PreferenceLevel | level | The level to set for this preference |
| bool | skipPermissionCheck | Set this to true to skip the check for setting system wide preferences |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetSectionAndKeyFromId(int)
Reads user preferences at several levels, returning the preference value that is defined at the lowest level.
A user preference defined at level 5 is more specific than a preference read at level 2.
Declaration
[Obsolete("Please do not manipulate preferences by ID, only use section/key", true)]
public static UserPreferenceCacheObject GetSectionAndKeyFromId(int primaryId)Parameters
| Type | Name | Description |
|---|---|---|
| int | primaryId |
Returns
| Type | Description |
|---|---|
| UserPreferenceCacheObject |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetSectionsAsync(CancellationToken)
Get all sections defined for the current associate, from the cache if possible, otherwise from the database.
Declaration
public static Task<string[]> GetSectionsAsync(CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string[]> | Array of sections |
Remarks
An intended side effect is that the key cache for each section plus the value cache for each key are set.
GetString(string, string)
Get string value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
public static string GetString(string section, string key)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
Returns
| Type | Description |
|---|---|
| string | User preference. If the user preference does not exist, String.Empty is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetString(string, string, string)
Get string value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
public static string GetString(string section, string key, string defaultValue)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
| string | defaultValue | Default value |
Returns
| Type | Description |
|---|---|
| string | User preference. If the user preference does not exist, the defualtValue is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetStringAsync(string, string, string, CancellationToken)
Get string value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
[CreateSyncVersion(OmitNullableDirective = true)]
public static Task<string> GetStringAsync(string section, string key, string defaultValue, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
| string | defaultValue | Default value |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> | User preference. If the user preference does not exist, the defualtValue is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.GetStringAsync(string, string, CancellationToken)
Get string value for a user preference, from the cache if possible. If not, read all keys and their values from the database, update the caches, and return the wanted value.
Declaration
[CreateSyncVersion(OmitNullableDirective = true)]
public static Task<string> GetStringAsync(string section, string key, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Name of the section. |
| string | key | Name of the key. |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string> | User preference. If the user preference does not exist, Empty is returned. |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.IndividualCacheKey(string, string)
Get the cache key for one single value
Declaration
public static string IndividualCacheKey(string section, string key)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Section name |
| string | key | Key name |
Returns
| Type | Description |
|---|---|
| string | Cache key for use in SoPrincipal |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.ParseBooleanPreference(string, bool)
Parse a string value into a boolean; if that is not possible then return the default instead
Declaration
public static bool ParseBooleanPreference(string value, bool defaultValue)Parameters
| Type | Name | Description |
|---|---|---|
| string | value | |
| bool | defaultValue |
Returns
| Type | Description |
|---|---|
| bool |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.SectionCacheKey(string)
Get the cache key for the list of keys in one section
Declaration
public static string SectionCacheKey(string section)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Section name |
Returns
| Type | Description |
|---|---|
| string | Cache key for use in SoPrincipal |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.SetCachedValue(int, string, string, string, PreferenceLevel)
Update individual and section caches
Declaration
public static void SetCachedValue(int primaryId, string section, string key, string value, PreferenceLevel level)Parameters
| Type | Name | Description |
|---|---|---|
| int | primaryId | Obsolete, not used |
| string | section | |
| string | key | |
| string | value | |
| PreferenceLevel | level | Obsolete, not used |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.SetCachedValue(string, string, string)
Update the cache with one item. This method is internal since it is also called from UserPreferenceRow/implementation, to keep the cache up to date with saved changes. NOTE that this does NOT take into account farm/cluster situations, where we instead rely on a fairly short cache lifetime... that may or may not be good enough.
Declaration
public static void SetCachedValue(string section, string key, string value)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Preference section |
| string | key | Preference key |
| string | value | Raw value to set |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.SetKeys(string, CancellationToken)
Reads user preferences at several levels, returning the preference value that is defined at the lowest level.
A user preference defined at level 5 is more specific than a preference read at level 2.
Declaration
public static Task<string[]> SetKeys(string section, CancellationToken cancellationToken)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<string[]> |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.SetPreferenceAsync(string, string, bool, CancellationToken)
Set a preference on the Individual (associate) level
Declaration
public static Task SetPreferenceAsync(string section, string key, bool value, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Preference section |
| string | key | Preference key |
| bool | value | New value, will overwrite the old or create a new record if no associate-level preference existed for the current associate |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.SetPreferenceAsync(string, string, DateTime, CancellationToken)
Set a preference on the Individual (associate) level
Declaration
public static Task SetPreferenceAsync(string section, string key, DateTime value, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Preference section |
| string | key | Preference key |
| DateTime | value | New value, will overwrite the old or create a new record if no associate-level preference existed for the current associate |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.SetPreferenceAsync(string, string, int, CancellationToken)
Set a preference on the Individual (associate) level
Declaration
public static Task SetPreferenceAsync(string section, string key, int value, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Preference section |
| string | key | Preference key |
| int | value | New value, will overwrite the old or create a new record if no associate-level preference existed for the current associate |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.SetPreferenceAsync(string, string, string, int, PreferenceLevel, bool, bool, CancellationToken)
Set a preference
Declaration
public static Task<int> SetPreferenceAsync(string section, string key, string value, int ownerId, PreferenceLevel level, bool removeOnLowerLevels = false, bool skipPermissionCheck = false, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Preference section |
| string | key | Preference key |
| string | value | New value, will overwrite the old or create a new record if no associate-level preference existed for the associate |
| int | ownerId | The id to set for the ownerId field. This will point to different id type depending on the preference type |
| PreferenceLevel | level | The level to set for this preference |
| bool | removeOnLowerLevels | Will remove same preference on lower levels if set to true |
| bool | skipPermissionCheck | Set this to true to skip the check for setting system wide preferences |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task<int> |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.SetPreferenceAsync(string, string, string, CancellationToken)
Set a preference on the maximum supported level for the given preference. If the maximum level is "Individual" - .an associate level preference will be created. If the maxiumum level is "Group", a group level preference for the current associate will be created.
Declaration
public static Task SetPreferenceAsync(string section, string key, string value, CancellationToken cancellationToken = default)Parameters
| Type | Name | Description |
|---|---|---|
| string | section | Preference section |
| string | key | Preference key |
| string | value | New value, will overwrite the old or create a new record if no preference existed for the maximum supported level |
| CancellationToken | cancellationToken |
Returns
| Type | Description |
|---|---|
| Task |
Remarks
Caching is done using the SoPrincipal-based cache mechanism. This is emptied on every roundtrip. That is intentional, to avoid stale data. In the interest of performance, we read complete sections, so if you ask for one preference we read-ahead all the preferences in that section and cache them for this roundtrip.
We assume that the SetCachedItem in CurrentPrincipal will accept multiple Set calls on the same item, and that the latest value will be the one that survives.