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

---
source_files:
  - Common/DTS.CommonCore/Classes/StatusAndProgressBarEventArgs.cs
  - Common/DTS.CommonCore/Classes/Singleton.cs
  - Common/DTS.CommonCore/Classes/ImportData.cs
  - Common/DTS.CommonCore/Classes/RegionNames.cs
  - Common/DTS.CommonCore/Classes/ServiceCall.cs
  - Common/DTS.CommonCore/Classes/TagAwareBase.cs
  - Common/DTS.CommonCore/Classes/Utility.cs
  - Common/DTS.CommonCore/Classes/Tags.cs
generated_at: "2026-04-16T02:12:54.891278+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "ab2980ca84007830"
---

# DTS.CommonCore Classes Documentation

## 1. Purpose

This module provides foundational infrastructure and data structures for the DTS (Data Transfer System) application. It establishes core patterns—including singleton management, service call queuing, tag-aware object modeling, and utility data access helpers—while defining shared data models for import operations, UI region naming, and status/progress reporting. The module serves as a shared dependency layer, enabling consistent behavior across UI, service, and data access components by encapsulating cross-cutting concerns like thread-safe resource management, database tag handling, and robust data parsing.

## 2. Public Interface

### `StatusAndProgressBarEventArgs`
- **`Color StatusColor { get; set; }`**: Color used to indicate status (e.g., success, error, warning).
- **`string StatusText { get; set; }`**: Human-readable status message.
- **`double ProgressValue { get; set; }`**: Numeric progress value (typically 0.0–100.0).
- **`Visibility ProgressBarVisibility { get; set; }`**: Controls whether the progress bar is visible (`Visible`, `Hidden`, or `Collapsed`).
- **`IBaseViewModel Requester { get; set; }`**: Reference to the originating view model requesting the status update.
- **`string ErrorText { get; set; }`**: Optional error message associated with the status.

### `Singleton<T>`
- **`protected Singleton()`**: Constructor prevents direct instantiation; throws `InvalidOperationException` if called when `Instance` already exists.
- **`public static T Instance { get; }`**: Returns the singleton instance of `T`. Initialization occurs lazily in a static constructor. If instantiation fails, subsequent access throws the captured exception.

### `ImportData`
#### `ImportPageType`
- **`enum ImportPageType`**: Defines import source types: `ImportSensor`, `ImportTestSetup`.

#### `SensorImportData`
- **`Dictionary<string, List<string>> GroupNameSensorListLookup { get; set; }`**: Maps group names to lists of sensor names.
- **`Dictionary<string, string> SensorGroupNameLookup { get; set; }`**: Maps sensor names to group names.
- **`Dictionary<string, string> SensorGroupTypeLookup { get; set; }`**: Maps group names to group types.
- **`Dictionary<string, string> GroupNameTestObjectLookup { get; set; }`**: Maps group names to test object names.
- **`List<string> Errors { get; set; }`**: Accumulated error messages during import.
- **`Dictionary<string, string> SensorISOCode { get; set; }`**: Maps sensor names to ISO codes.
- **`Dictionary<string, string> SensorISOChannelName { get; set; }`**: Maps sensor names to ISO channel names.
- **`Dictionary<string, string> SensorUserCode { get; set; }`**: Maps sensor names to user-defined codes.
- **`Dictionary<string, string> SensorUserChannelName { get; set; }`**: Maps sensor names to user-defined channel names.
- **`Dictionary<string, string> SensorDASSerialNumber { get; set; }`**: Maps sensor names to DAS serial numbers.
- **`Dictionary<string, int> SensorChannelIndex { get; set; }`**: Maps sensor names to channel indices.

#### `TestSetupImportData`
- **`string Name { get; set; }`**: Test setup name.
- **`string Description { get; set; }`**: Test setup description.
- **`double SamplesPerSecond { get; set; }`**: Sampling rate.
- **`double PosttriggerSeconds { get; set; }`**: Post-trigger duration.
- **`double PretriggerSeconds { get; set; }`**: Pre-trigger duration.
- **`RecordingModes RecordingMode { get; set; }`**: Recording mode (enum defined elsewhere).
- **`CalibrationBehaviors CalibrationBehavior { get; set; }`**: Calibration behavior (enum defined elsewhere).
- **`int Version { get; set; }`**: Test setup version.
- **`List<string> TestChannelOrders { get; set; }`**: Ordered list of test channel names.
- **`List<string> Tags { get; set; }`**: List of tag strings.
- **`InputClockSource ClockMasterInput { get; set; }`**: Input clock source for master (default: `None`).
- **`OutputClockSource ClockMasterOutput { get; set; }`**: Output clock source for master (default: `None`).
- **`bool ManageClocksOutsideOfDataPROMaster { get; set; }`**: Flag for external clock management on master (default: `false`).
- **`bool ManageClocksOutsideOfDataPROSlave { get; set; }`**: Flag for external clock management on slave (default: `false`).
- **`OutputClockSource ClockSlaveInput { get; set; }`**: Input clock source for slave (default: `None`).
- **`OutputClockSource ClockSlaveOutput { get; set; }`**: Output clock source for slave (default: `None`).
- **`Dictionary<string, int> SampleRateForDAS { get; }`**: Maps DAS device names to sample rates.
- **`Dictionary<string, uint> DomainIdForDAS { get; }`**: Maps DAS device names to domain IDs.
- **`Dictionary<string, bool> IsClockMaster { get; }`**: Maps DAS device names to clock master flag.

### `RegionNames`
- **`public const string FrontRegion = "FrontRegion"`**
- **`public const string MainRegion = "MainRegion"`**
- **`public const string ViewerEuRegion = "ViewerEuRegion"`**
- **`public const string ViewerMvRegion = "ViewerMvRegion"`**
- **`public const string ViewerEdcRegion = "ViewerEdcRegion"`**
- **`public const string ViewerTestsRegion = "ViewerTestsRegion"`**
- **`public const string ViewerGraphRegion = "ViewerGraphRegion"`**
- **`public const string ViewerGraphsRegion = "ViewerGraphsRegion"`**
- **`public const string ViewerGraphMainRegion = "ViewerGraphMainRegion"`**
- **`public const string ViewerGraphListRegion = "ViewerGraphListRegion"`**
- **`public const string ViewerGraphChannelRegion = "ViewerGraphChannelRegion"`**
- **`public const string ViewerTestModificationRegion = "ViewerTestModificationRegion"`**
- **`public const string ViewerLegendRegion = "ViewerLegendRegion"`**
- **`public const string ViewerSearchRegion = "ViewerSearchRegion"`**
- **`public const string ViewerSettingsRegion = "ViewerSettingsRegion"`**
- **`public const string ViewerDiagRegion = "ViewerDiagRegion"`**
- **`public const string ViewerDisplayRegion = "ViewerDisplayRegion"`**
- **`public const string ViewerChartOptionsRegion = "ViewerChartOptionsRegion"`**
- **`public const string ViewerStatsRegion = "ViewerStatsRegion"`**
- **`public const string ViewerCursorRegion = "ViewerCursorRegion"`**
- **`public const string ViewerFiterRegion = "ViewerFiterRegion"`** *(Note: Typo in source—likely intended "Filter")*
- **`public const string MenuRegion = "MenuRegion"`**
- **`public const string NavigationRegion = "NavigationRegion"`**
- **`public const string BottomRegion = "BottomRegion"`**
- **`public const string RightRegion = "RightRegion"`**
- **`public const string TopRegion = "TopRegion"`**
- **`public const string VerticalTabRegion = "VerticalTabRegion"`**
- **`public const string HorizontalTabRegion = "HorizontalTabRegion"`**
- **`public const string RibbonRegion = "RibbonRegion"`**
- **`public const string PropertyDisplayRegion = "PropertyDisplayRegion"`**
- **`public const string PropertyModifyRegion = "PropertyModifyRegion"`**
- **`public const string PropertyAddRegion = "PropertyAddRegion"`**
- **`public const string PSDDataSelectRegion = "PSDDataSelectRegion"`**
- **`public const string PSDGraphRegion = "PSDGraphRegion"`**
- **`public const string ReportChartOptionsRegion = "ReportChartOptionsRegion"`**
- **`public const string ReportResultsRegion = "ReportResultsRegion"`**

### `ServiceCall`
- **`bool Started { get; set; }`**: Indicates whether the work has started.
- **`Action WorkAction { get; set; }`**: The delegate representing the work to execute.
- **`void MarkDone()`**: Notifies the `ServiceQueue` that this call has completed.
- **`string Name { get; set; }`**: Human-readable name for debugging/tracing.
- **`ServiceCall(string name)`**: Constructor setting the `Name`.

### `ServiceQueue`
- **`public static void Enqueue(ServiceCall call)`**: Adds a `ServiceCall` to the queue. Starts execution if queue was empty.
- **`public static void MarkFinished(ServiceCall call)`**: Marks a `ServiceCall` as finished. If it was the current item, the next item in the queue is started.

### `TagAwareBase`
- **`enum TagTypes`**: Defines tag categories: `User`, `Group`, `Template`, `TestSetup`, `Sensors`, `SensorModels`.
- **`public abstract TagTypes TagType { get; }`**: Must be implemented by derived classes to specify its tag type.
- **`public byte[] TagsBlobBytes { get; set; }`**: Gets/sets `TagIDs` as a byte array (used for DB storage).
- **`public int[] TagIDs { get; set; }`**: Array of tag IDs associated with this object.
- **`void SetTagsFromCommaSeparatedString(string tagText, Tags.GetSqlCommandDelegate getSqlCommand)`**: Parses comma-separated tags and updates `TagIDs`.
- **`virtual void SetTags(string[] tagsText, Tags.GetSqlCommandDelegate getSqlCommand)`**: Adds/updates tags and sets `TagIDs`.
- **`string GetTagsAsCommaSeparatedString(Tags.GetSqlCommandDelegate getSqlCommand)`**: Returns tags as comma-separated string.
- **`virtual string[] GetTagsArray(Tags.GetSqlCommandDelegate getSqlCommand)`**: Returns array of tag text strings.
- **`virtual int[] GetTagIDs()`**: Returns `TagIDs`.
- **`virtual void RemoveTags(string[] tagsText)`**: Stub—no implementation provided.
- **`bool TagCompatible(string tags, Tags.GetSqlCommandDelegate getSqlCommand)`**: Returns `true` if any tag in `tags` matches this object’s tags.
- **`virtual bool TagCompatible(int[] tags)`**: Returns `true` if `tags` is empty or has intersection with `TagIDs`.
- **`virtual bool HasIntersectingTag(int[] tags)`**: Returns `true` if `tags` and `TagIDs` share at least one ID.
- **`void InsertTagsFromCommaSeparatedString(int id, TagTypes tagType, string tags, Tags.GetSqlCommandDelegate getSqlCommand)`**: Sets tags and commits assignments.
- **`void Commit(int id, TagTypes tagType, Tags.GetSqlCommandDelegate getSqlCommand)`**: Deletes existing tag assignments for this object, then inserts new ones for current `TagIDs`.
- **`List<int> GetTagIdList(int objectId, TagTypes tagType, Tags.GetSqlCommandDelegate getSqlCommand)`**: Retrieves tag IDs for a given object ID and type from the database.

### `Utility`
- **`static byte[] GetBytesFromStringArray(string[] array, string separator)`**: Joins array with `separator`, returns UTF-8 bytes.
- **`static string GetAllErrorMessages(Exception ex)`**: Recursively aggregates exception messages (including inner exceptions).
- **`static bool PingNetwork(string hostNameOrAddress)`**: Pings host with 4s timeout; returns `true` on success.
- **`static ushort GetUShort(IDataReader reader, string column, ushort defaultValue = 0)`**
- **`static uint GetUInt(IDataReader reader, string column, uint defaultValue = 0)`**
- **`static string GetString(IDataReader reader, string column, string defaultValue = "")`**
- **`static string[] GetStringArray(IDataReader reader, string column, string[] defaultValue, string separator)`**: Reads byte array, decodes as UTF-8, splits by `separator`.
- **`static int GetInt(IDataReader reader, string column, int defaultValue = 0)`**
- **`static double GetDouble(IDataReader reader, string column, double defaultValue = 0D)`**
- **`static short GetShort(IDataReader reader, string column, short defaultValue = 0)`**
- **`static DateTime? GetNullableDateTime(IDataReader reader, string column)`**
- **`static ulong GetUlong(IDataReader reader, string column, ulong defaultValue = 0)`**
- **`static int? GetNullableInt(IDataReader reader, string column)`**
- **`static byte[] GetByteArray(IDataReader reader, string column)`**
- **`static bool GetBool(IDataReader reader, string column, bool defaultValue = false)`**
- **`static DateTime GetDateTime(IDataReader reader, string column, DateTime defaultValue)`**
- **`static long GetLong(IDataReader reader, string column, long defaultValue = 0)`**

All `Get*` methods:
- Return `defaultValue` if `column` is null/whitespace or value is `DBNull`.
- Log failures via `APILogger.Log(...)` with column name and value.

### `Tags`
- **`class Tag`**
  - **`public const int INVALID_ID = -1`**
  - **`int ID { get; set; }`**
  - **`string Text { get; set; }`**
  - **`bool IsObsolete { get; set; }`**
  - **Constructors**: From `(string, int)`, `(Tag)`, `(IDataRecord)`, `(DataRow)`.
  - **`object Clone()`**: Returns a copy.

- **`public delegate SqlCommand GetSqlCommandDelegate(bool bNewConnection)`**: Factory delegate for SQL commands.

- **`public static Tags GetTagsInstance(GetSqlCommandDelegate getSqlCommand)`**: Returns singleton instance (lazy-initialized per delegate).

- **`public static bool AddTag(string tagText, GetSqlCommandDelegate getSqlCommand)`**: Adds tag if not already present; returns `true` if added.

- **`public static bool MigrateTag(string tagText, GetSqlCommandDelegate getSqlCommand)`**: Commits tag (used for DB migration); returns `true`.

- **`public static bool[] AddRange(string[] tagText, GetSqlCommandDelegate getSqlCommand)`**: Adds multiple tags; trims leading whitespace.

- **`public static int GetIDFromTagText(string tagText, GetSqlCommandDelegate getSqlCommand)`**: Gets tag ID from text (calls DB); returns `Tag.INVALID_ID` if not found.

- **`public static int[] GetIDsFromTagText(string[] tagText, GetSqlCommandDelegate getSqlCommand)`**: Gets IDs for array of tag texts; filters out `INVALID_ID`.

- **`public static string GetTagTextFromID(int tagID, GetSqlCommandDelegate getSqlCommand)`**: Gets tag text from ID (from in-memory cache); returns `null` if invalid or not found.

- **`public static string[] GetTagTextFromIDs(int[] tagId, GetSqlCommandDelegate getSqlCommand)`**: Gets tag texts from IDs (from cache); filters invalid/empty.

- **`public bool ContainsTag(string text)`**: Checks if tag text exists in cache.

- **`public void UpdateList(GetSqlCommandDelegate getSqlCommand)`**: Refreshes in-memory cache by querying DB via `sp_TagsGet`.

## 3. Invariants

- **Singleton<T>**:
  - Only one instance of `T` exists per AppDomain.
  - `Instance` is lazily initialized in a static constructor.
  - Direct instantiation via `new T()` throws `InvalidOperationException` if `Instance` already exists.
  - If `T`’s constructor throws, subsequent `Instance` access rethrows the captured exception.

- **ServiceQueue**:
  - Work items execute sequentially in FIFO order.
  - Only one `ServiceCall.WorkAction` runs at a time (via `Task.Run`).
  - `MarkDone()` must be called by the executing code to trigger next item.
  - Items not yet started can be removed from queue; only the first item is actively executed.

- **TagAwareBase**:
  - `TagIDs` is never `null` (defaults to empty array).
  - `TagsBlobBytes` and `TagIDs` are kept in sync via property setters.
  - `Commit()` always deletes existing assignments before inserting new ones.
  - `TagCompatible(string)` returns `true` if `tags` is null/empty/whitespace or if any tag matches.

- **Utility**:
  - All `Get*` methods return `defaultValue` on `DBNull` or parse failure.
  - All `Get*` methods log failures via `APILogger`.

- **Tags**:
  - Tag text is trimmed only during `AddRange` (leading whitespace).
  - `GetTagTextFromID` uses in-memory cache; `GetIDFromTagText` queries DB.
  - `UpdateList` clears and repopulates `_tagsLookup`.

## 4. Dependencies

### This module depends on:
- **DTS.Common.Base**: `IBaseViewModel`, `BasePropertyChanged`.
- **DTS.Common.Enums**: `RecordingModes`, `CalibrationBehaviors`, `InputClockSource`, `OutputClockSource`.
- **DTS.Common.Interface.Sensors**: `IBaseViewModel` (used in `StatusAndProgressBarEventArgs.Requester`).
- **System**: `System.Windows`, `System.Data`, `System.Data.SqlClient`, `System.Net.NetworkInformation`, `System.Collections.Generic`, `System.Linq`, `System.Text`, `System.Threading.Tasks`.
- **DTS.Common.Utilities.Logging**: `APILogger`.

### This module is depended upon by:
- Any module requiring singleton behavior (`Singleton<T>`).
- Any module needing tag-aware objects (`TagAwareBase`).
- Any module performing data import (`ImportData`).
- Any module using service call queuing (`ServiceCall`, `ServiceQueue`).
- Any module needing UI region names (`RegionNames`).
- Any module requiring robust data access helpers (`Utility`).
- Any module managing tags (`Tags`).

## 5. Gotchas

- **Typo in RegionNames**: `ViewerFiterRegion` is likely intended to be `ViewerFilterRegion`.
- **Singleton<T> thread-safety**: Initialization is thread-safe (static constructor), but no further synchronization is applied to the singleton instance itself.
- **Tags caching**: `_tagsLookup` is populated only on first access and updated only when adding tags or calling `UpdateList`. It does not automatically refresh.
- **Tag text trimming**: `AddRange` trims leading whitespace, but `SetTagsFromCommaSeparatedString` does *not* trim (only `Split` and `TrimStart` in `AddRange`).
- **`TagCompatible(string)` behavior**: Returns `true` if *any* tag in the input matches *any* of the object’s tags (logical OR), not AND.
- **`Tags.GetTag