DP44/docs/ai/Common/DTS.Common.SettingsDB.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.SettingsDB/UserSetting.cs Common/DTS.Common.SettingsDB/Setting.cs Common/DTS.Common.SettingsDB/GlobalSetting.cs Common/DTS.Common.SettingsDB/SettingsDB.cs	2026-04-17T15:37:14.268695+00:00	zai-org/GLM-5-FP8	1	c7c6dae1a5ddac05

Documentation: DTS.Common.Settings

1. Purpose

This module provides a persistent settings management system that stores application configuration in a database. It supports both global (application-wide) and user-specific settings through a singleton cache (SettingsDB) with lazy loading. The module abstracts database operations via stored procedures, handles type conversion for common types (string, int, double, bool, arrays), and maintains backward compatibility for legacy setting migrations.

---

2. Public Interface

Class: Setting (Abstract Base)

Properties:

• string PropertyId — The identifier for the setting.
• PropertyTypes PropertyType — Either User (1) or Global (2).
• string PropertyValue — The current value of the setting.
• string UserId — The user identifier for user-specific settings.

Enum: PropertyTypes

• User = 1
• Global = 2

Methods:

• void SetValue(string value) — Sets the property value and persists it to the database via StoreInDB().

---

Class: UserSetting (inherits Setting)

Constructor:

• UserSetting(string id, string defaultValue, string user) — Creates a user-specific setting. Retrieves existing value from DB or stores the default value if not found.

---

Class: GlobalSetting (inherits Setting)

Constructors:

• GlobalSetting(string id, string defaultPropertyValue) — Creates a global setting with the given ID and default value.
• GlobalSetting() (protected) — Parameterless constructor for XML deserialization.

Static Methods:

• GlobalSetting ReadXML(System.Xml.XmlElement root) — Deserializes a GlobalSetting from XML. Expects child elements matching XMLFields.NAME and XMLFields.VALUE.
• GlobalSetting[] GetAllGlobalSettings() — Retrieves all global settings from the database. Returns an empty array on failure.

Enum: XMLFields

• NAME
• VALUE

Inner Class: NullDefaultValueException — Thrown when a global setting doesn't exist in the database and no default value is provided.

---

Class: SettingsDB (Singleton Facade)

All methods are static and thread-safe via internal locking.

Cache Management:

• void RefreshSettings() — Clears the in-memory settings cache.

User Settings:

• string GetUserValue(string id, string defaultValue, string user) — Retrieves a user-specific value, creating it with the default if it doesn't exist.
• void SetUserValue(string id, string value, string user) — Sets a user-specific value in the database and cache.

Global Settings (String):

• string GetGlobalValue(string id, string defaultValue, bool useCache = true) — Retrieves a global value. If useCache is false, bypasses cache.
• void SetGlobalValue(string id, string value) — Sets a global value.
• void GetAllGlobalValues() — Loads all global settings into the cache.

Global Settings (Typed):

• double GetGlobalValueDouble(string id, double defaultValue) — Retrieves a global value as a double.
• int GetGlobalValueInt(string id, int defaultValue) — Retrieves a global value as an int.
• bool GetGlobalValueBool(string id, bool defaultValue, bool useCache = true) — Retrieves a global value as a bool.

Global Settings (Arrays):

• double[] GetGlobalValueDoubleArray(string id, double[] defaultValues) — Retrieves an array of doubles. Uses {id}_x_Count and {id}_x_{i} keys.
• int[] GetGlobalValueIntArray(string id, int[] defaultValues) — Retrieves an array of ints.
• void SetGlobalValueDoubleArray(string id, double[] values) — Stores an array of doubles.
• void SetGlobalValueIntArray(string id, int[] values) — Stores an array of ints.

Global Settings (Typed Setters):

• void SetGlobalValueDouble(string id, double value)
• void SetGlobalValueInt(string id, int value)
• void SetGlobalValueBoolean(string id, bool value)

---

3. Invariants

1. Singleton Pattern: SettingsDB uses a private constructor and lazy initialization with a lock object (LOCK_OBJECT) to ensure thread-safe singleton access.

2. Cache Key Format:

   • User settings: {id}_{user}
   • Global settings: {id}
   • Array elements: {id}_x_{index}, with count stored at {id}_x_Count

3. Global Settings User ID: All GlobalSetting instances use the constant "SYSTEM" as the UserId when interacting with the database.

4. Stored Procedures: All database operations use:

   • sp_SettingsGet for retrieval
   • sp_SettingsUpdateInsert for persistence

5. Culture Invariance: All numeric conversions use CultureInfo.InvariantCulture for consistent serialization