DP44/enriched-qwen3-coder-next/Common/DTS.Common/Classes/Groups/ChannelSettings.md

---
source_files:
  - Common/DTS.Common/Classes/Groups/ChannelSettings/ChannelSettingRecord.cs
  - Common/DTS.Common/Classes/Groups/ChannelSettings/GroupChannelSettingRecord.cs
  - Common/DTS.Common/Classes/Groups/ChannelSettings/ChannelSettingBase.cs
generated_at: "2026-04-16T03:18:55.361650+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "48681046c7a61e91"
---

# ChannelSettingRecord, GroupChannelSettingRecord, and ChannelSettingBase Documentation

## 1. Purpose

This module defines core data structures for representing channel configuration settings within the DTS system. It provides three interrelated classes: `ChannelSettingRecord` (a lightweight record of a *type* of channel setting, including its ID, name, and default value), `GroupChannelSettingRecord` (a *specific instance* of a setting applied to a particular channel), and `ChannelSettingBase` (a richer, type-aware implementation of `IChannelSetting` that supports parsing and type conversion of setting values). Together, they enable storage, retrieval, and manipulation of channel-specific configuration parameters across different channel types (analog, digital, squib, UART, CAN, etc.), forming the data layer for channel configuration management.

## 2. Public Interface

### `ChannelSettingRecord`
- **`ChannelSettingRecord()`**  
  Default constructor; initializes an empty record.
- **`ChannelSettingRecord(IDataReader reader)`**  
  Populates the record from an `IDataReader` by reading columns `"Id"`, `"SettingName"`, and `"DefaultValue"` using `Utility.GetInt` and `Utility.GetString`.

- **`int Id { get; set; }`**  
  Unique identifier for this setting *type* (e.g., `"Range"` or `"SquibCurrent"`).
- **`string SettingName { get; set; }`**  
  Human-readable name of the setting (e.g., `"Range"`).
- **`string DefaultValue { get; set; }`**  
  Default value string for this setting type (e.g., `"10"` for a range setting).

> *Note:* Inherits from `Common.Base.BasePropertyChanged`, implying `INotifyPropertyChanged` support for UI binding.

---

### `GroupChannelSettingRecord`
- **`GroupChannelSettingRecord()`**  
  Default constructor; initializes an empty record.
- **`GroupChannelSettingRecord(IDataReader reader, int storedProcedureVersionUsed)`**  
  Populates the record from an `IDataReader`. If `storedProcedureVersionUsed >= Constants.BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`, it reads `"ChannelId"` using `Utility.GetLong`; otherwise, `ChannelId` is left uninitialized (default `0`). Always reads `"SettingId"` (`Utility.GetInt`) and `"SettingValue"` (`Utility.GetString`).
- **`GroupChannelSettingRecord(long channelId, int settingId, string settingValue)`**  
  Constructor for direct initialization with explicit values.

- **`long ChannelId { get; set; }`**  
  Identifier of the channel to which this setting instance applies.
- **`int SettingId { get; set; }`**  
  Identifier of the setting *type* (corresponds to `ChannelSettingRecord.Id`).
- **`string SettingValue { get; set; }`**  
  Actual value string assigned to this setting for the channel.

> *Note:* Inherits from `BasePropertyChanged`, implying `INotifyPropertyChanged` support.

---

### `ChannelSettingBase`
- **`ChannelSettingBase(int settingType, string name, string defaultValue)`**  
  Constructor initializing `SettingTypeId`, `SettingName`, and `DefaultValue`. `Value` is initialized to `null`.
- **`ChannelSettingBase(IChannelSetting setting)`**  
  Copy constructor; initializes all properties from another `IChannelSetting` instance.
- **`IChannelSetting Clone()`**  
  Returns a new `ChannelSettingBase` instance with all properties copied from the current instance.

- **`long ChannelId { get; set; }`**  
  Channel identifier associated with this setting instance.
- **`int SettingTypeId { get; protected set; }`**  
  Type ID of the setting (e.g., used to group settings by channel type).
- **`string SettingName { get; protected set; }`**  
  Name of the setting (e.g., `"Range"`, `"SquibCurrent"`).
- **`string DefaultValue { get; protected set; }`**  
  Default value string for this setting type.
- **`string Value { get; set; }`**  
  Current value string for this setting instance.

- **`double DoubleValue { get; set; }`**  
  Parses `Value` as a `double` (using `InvariantCulture`); if parsing fails, returns `DoubleDefaultValue`. Setting updates `Value`.
- **`double DoubleDefaultValue { get; }`**  
  Parses `DefaultValue` as a `double` (using `InvariantCulture`).
- **`int IntValue { get; set; }`**  
  Parses `Value` as an `int`; if parsing fails, returns `IntDefaultValue`. Setting updates `Value`.
- **`int IntDefaultValue { get; }`**  
  Parses `DefaultValue` as an `int`.
- **`bool BoolValue { get; set; }`**  
  Parses `Value` as a `bool`; if parsing fails, returns `BoolDefaultValue`. Setting updates `Value`.
- **`bool BoolDefaultValue { get; }`**  
  Parses `DefaultValue` as a `bool`. If parsing fails and `DefaultValue` is null/empty, returns `false`; otherwise, returns `!DefaultValue.Equals(0)` (note: this is a string comparison, not numeric).

> *Note:* Implements `IChannelSetting`. Constants defined as `public const string` for known setting names (see *Gotchas* for caveats).

---

## 3. Invariants

- **`ChannelSettingRecord`**  
  - `Id`, `SettingName`, and `DefaultValue` are populated from database columns and must be non-null (except `DefaultValue`, which may be empty or null per `Utility.GetString` behavior).
  - `Id` is expected to be unique per setting type.

- **`GroupChannelSettingRecord`**  
  - `SettingId` must correspond to a valid `ChannelSettingRecord.Id` (enforced externally, not by this class).
  - `ChannelId` may be uninitialized (`0`) if constructed via `IDataReader` constructor with `storedProcedureVersionUsed < Constants.BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`.
  - `SettingValue` may be null or empty.

- **`ChannelSettingBase`**  
  - `SettingName` and `DefaultValue` are set only via constructor and remain immutable after construction (due to `protected set`).
  - `Value` is mutable and may be null/empty.
  - `DoubleValue`, `IntValue`, and `BoolValue` fall back to their respective `*DefaultValue` properties if `Value` is unparsable.
  - `BoolDefaultValue` has non-intuitive behavior: if `DefaultValue` cannot be parsed as `bool`, and is non-empty, it returns `!DefaultValue.Equals("0")` (string comparison), *not* numeric evaluation.

---

## 4. Dependencies

### Dependencies *of* this module:
- **`DTS.Common.Interface.Channels`**  
  Defines interfaces `IChannelSettingRecord`, `IGroupChannelSettingRecord`, and `IChannelSetting` (consumed by these classes).
- **`DTS.Common.Base`**  
  Provides `BasePropertyChanged` (base class for `ChannelSettingRecord` and `GroupChannelSettingRecord`).
- **`System.Data`**  
  Used for `IDataReader` in constructors.
- **`DTS.Common` (internal)**  
  - `Utility` class (for `GetInt`, `GetString`, `GetLong`).
  - `Constants` (for `BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`).

### Dependencies *on* this module:
- Likely consumed by:
  - Data access layers (to populate records from `IDataReader`).
  - Channel configuration services (to manage per-channel settings).
  - UI layers (via `INotifyPropertyChanged` support).

---

## 5. Gotchas

- **`BoolDefaultValue` logic is error-prone**:  
  If `DefaultValue` is `"1"` or `"true"`, `bool.TryParse` succeeds. But if `DefaultValue` is `"0"`, `bool.TryParse` fails (since `"0"` is not a valid `bool` string), and `BoolDefaultValue` returns `!DefaultValue.Equals("0")` → `false`. This is inconsistent with typical `bool` parsing and may cause misinterpretation of `"0"` as `false` only when `bool.TryParse` fails. Prefer explicit `"true"`/`"false"` defaults.

- **`ChannelSettingBase` constants are *not* exhaustive**:  
  The `public const string` fields list known setting names (e.g., `"Range"`, `"SquibCurrent"`), but are not validated against actual usage. New settings may be added without updating these constants, leading to string literals scattered elsewhere in the codebase.

- **`GroupChannelSettingRecord` constructor behavior depends on `storedProcedureVersionUsed`**:  
  If `storedProcedureVersionUsed < Constants.BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`, `ChannelId` is *not* read from the `IDataReader`, leaving it at `0`. This introduces version-dependent data loading logic that may cause silent bugs if versioning is mismanaged.

- **`ChannelSettingBase` does not enforce `Value` format**:  
  While `DoubleValue`, `IntValue`, and `BoolValue` provide type-safe access, `Value` itself is a raw `string`. No validation ensures `Value` matches the expected format for `SettingName`.

- **`Clone()` returns `IChannelSetting`, not `ChannelSettingBase`**:  
  The copy constructor is `private`, and `Clone()` returns the interface type, limiting extensibility or deep-copy behavior in subclasses.

- **No null-safety for `DefaultValue` in numeric/bool conversions**:  
  `DoubleDefaultValue`, `IntDefaultValue`, and `BoolDefaultValue` call `double.Parse`, `int.Parse`, or `bool.TryParse` on `DefaultValue` without null checks. If `DefaultValue` is `null`, this will throw `ArgumentNullException` or `FormatException`.

- **`SettingName` is `protected set`**:  
  Cannot be modified after construction, but `ChannelSettingBase` is not sealed—subclasses could theoretically override behavior, though no subclasses are visible in the provided source.

- **`ChannelSettingRecord` and `GroupChannelSettingRecord` share naming but serve distinct roles**:  
  `ChannelSettingRecord` defines a *type* of setting (e.g., `"Range"`), while `GroupChannelSettingRecord` defines an *instance* (e.g., channel 123’s `"Range"` = `"10"`). Confusing these roles is a common source of bugs.

None identified beyond the above.