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

---
source_files:
  - Common/DTS.Common.SettingsDB/UserSetting.cs
  - Common/DTS.Common.SettingsDB/Setting.cs
  - Common/DTS.Common.SettingsDB/GlobalSetting.cs
  - Common/DTS.Common.SettingsDB/SettingsDB.cs
generated_at: "2026-04-17T15:37:14.268695+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "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