DP44/docs/ai/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-17T15:33:44.713375+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "27a98b73bf260db5"
---

# DTS.Common.Classes Module Documentation

## Purpose

This module provides core infrastructure classes for the DTS application, including a thread-safe singleton pattern implementation, a serialized service call queue, region name constants for UI navigation, tag management with database persistence, data transfer objects for import operations, and utility helpers for safe data reader access and error handling. These classes form foundational building blocks used across the application for state management, UI coordination, and data operations.

---

## Public Interface

### StatusAndProgressBarEventArgs
**Namespace:** `DTS.Common.Classes`

A data transfer object for passing status and progress information in event arguments.

| Property | Type | Description |
|----------|------|-------------|
| `StatusColor` | `System.Windows.Media.Color` | The color to display for the status text |
| `StatusText` | `string` | The text to display in the status area |
| `ProgressValue` | `double` | The current progress bar value |
| `ProgressBarVisibility` | `System.Windows.Visibility` | Controls visibility of the progress bar |
| `Requester` | `IBaseViewModel` | Reference to the view model requesting the status update |
| `ErrorText` | `string` | Error message text, if any |

---

### Singleton\<T\>
**Namespace:** `DTS.Common.Classes`

A generic base class implementing the singleton pattern. Derived classes must have a public parameterless constructor.

```csharp
public class Singleton<T> where T : new()
```

| Member | Signature | Description |
|--------|-----------|-------------|
| `Instance` | `public static T Instance { get; }` | Returns the singleton instance of type T. Throws `InvalidOperationException` if creation previously failed or if accessed during failed initialization. |

**Constructor Behavior:** The protected constructor throws `InvalidOperationException` if `Instance` is not null, preventing manual instantiation via `new` when an instance already exists.

---

### ServiceCall
**Namespace:** `DTS.Common.Classes`

Represents a unit of work to be executed by the service framework.

| Member | Signature | Description |
|--------|-----------|-------------|
| `Started` | `public bool Started { get; set; }` | Indicates whether the call has begun execution |
| `WorkAction` | `public Action WorkAction { get; set; }` | The delegate containing work to execute |
| `Name` | `public string Name { get; set; }` | Identifier for the service call |
| `MarkDone` | `public void MarkDone()` | Notifies the queue that this call is complete |
| Constructor | `public ServiceCall(string name)` | Creates a new service call with the given name |

---

### ServiceQueue
**Namespace:** `DTS.Common.Classes`

Manages serialized execution of service calls via an internal queue.

| Member | Signature | Description |
|--------|-----------|-------------|
| `Enqueue` | `public static void Enqueue(ServiceCall call)` | Adds a service call to the queue. Starts execution immediately if queue is empty. |
| `MarkFinished` | `public static void MarkFinished(ServiceCall call)` | Removes a completed call from the queue and starts the next item if available. |

---

### RegionNames
**Namespace:** `DTS.Common.Classes`

Static class containing string constants for UI region identifiers used in navigation.

**Constants:**
- `FrontRegion`, `MainRegion`
- `ViewerEuRegion`, `ViewerMvRegion`, `ViewerEdcRegion`, `ViewerTestsRegion`
- `ViewerGraphRegion`, `ViewerGraphsRegion`, `ViewerGraphMainRegion`, `ViewerGraphListRegion`, `ViewerGraphChannelRegion`
- `ViewerTestModificationRegion`, `ViewerLegendRegion`, `ViewerSearchRegion`, `ViewerSettingsRegion`
- `ViewerDiagRegion`, `ViewerDisplayRegion`, `ViewerChartOptionsRegion`, `ViewerStatsRegion`, `ViewerCursorRegion`
- `ViewerFiterRegion` (note: typo preserved from source)
- `MenuRegion`, `NavigationRegion`, `BottomRegion`, `RightRegion`, `TopRegion`
- `VerticalTabRegion`, `HorizontalTabRegion`, `RibbonRegion`
- `PropertyDisplayRegion`, `PropertyModifyRegion`, `PropertyAddRegion`
- `PSDDataSelectRegion`, `PSDGraphRegion`
- `ReportChartOptionsRegion`, `ReportResultsRegion`

---

### TagAwareBase
**Namespace:** `DTS.Common.Classes`

Abstract base class providing tag management functionality for entities that support tagging.

```csharp
public abstract class TagAwareBase : Base.BasePropertyChanged
```

**Nested Enum:**
```csharp
public enum TagTypes
{
    User,
    Group,
    Template,
    TestSetup,
    Sensors,
    SensorModels
}
```

| Member | Signature | Description |
|--------|-----------|-------------|
| `TagType` | `public abstract TagTypes TagType { get; }` | Must be implemented to specify the entity type |
| `TagsBlobBytes` | `public byte[] TagsBlobBytes { get; set; }` | Gets/sets tags as a byte array (int array serialized) |
| `TagIDs` | `public int[] TagIDs { get; set; }` | Array of tag IDs associated with this entity |
| `SetTagsFromCommaSeparatedString` | `public void SetTagsFromCommaSeparatedString(string tagText, Tags.GetSqlCommandDelegate getSqlCommand)` | Parses comma-separated tags and assigns them |
| `SetTags` | `public virtual void SetTags(string[] tagsText, Tags.GetSqlCommandDelegate getSqlCommand)` | Assigns tags from string array |
| `GetTagsAsCommaSeparatedString` | `public string GetTagsAsCommaSeparatedString(Tags.GetSqlCommandDelegate getSqlCommand)` | Returns tags as comma-separated string |
| `GetTagsArray` | `public virtual string[] GetTagsArray(Tags.GetSqlCommandDelegate getSqlCommand)` | Returns tags as string array |
| `GetTagIDs` | `public virtual int[] GetTagIDs()` | Returns the TagIDs array |
| `RemoveTags` | `public virtual void RemoveTags(string[] tagsText)` | Stub method (no implementation in source) |
| `TagCompatible` | `public bool TagCompatible(string tags, Tags.GetSqlCommandDelegate getSqlCommand)` | Checks if any comma-separated tag matches this entity's tags |
| `TagCompatible` | `public virtual bool TagCompatible(int[] tags)` | Checks if any tag ID in the array intersects with this entity's tags |
| `HasIntersectingTag` | `public virtual bool HasIntersectingTag(int[] tags)` | Returns true if any tag ID intersects |
| `InsertTagsFromCommaSeparatedString` | `public void InsertTagsFromCommaSeparatedString(int id, TagTypes tagType, string tags, Tags.GetSqlCommandDelegate getSqlCommand)` | Sets tags and commits to database |
| `Commit` | `public void Commit(int id, TagTypes tagType, Tags.GetSqlCommandDelegate getSqlCommand)` | Persists tag assignments to database via stored procedures |
| `GetTagIdList` | `public List<int> GetTagIdList(int objectId, TagTypes tagType, Tags.GetSqlCommandDelegate getSqlCommand)` | Retrieves tag IDs for an object from database |

---

### Tags
**Namespace:** `DTS.Common.Classes`

Manages tag entities with in-memory caching and database persistence.

**Nested Class: Tag**
```csharp
public class Tag : ICloneable
{
    public const int INVALID_ID = -1;
    public int ID { get; set; }
    public string Text { get; set; }
    public bool IsObsolete { get; set; }
}
```

| Member | Signature | Description |
|--------|-----------|-------------|
| `GetTagsInstance` | `public static Tags GetTagsInstance(GetSqlCommandDelegate getSqlCommand)` | Returns the singleton instance, creating it if necessary |
| `AddTag` | `public static bool AddTag(string tagText, GetSqlCommandDelegate getSqlCommand)` | Adds a tag if not already cached; returns false if already exists |
| `MigrateTag` | `public static bool MigrateTag(string tagText, GetSqlCommandDelegate getSqlCommand)` | Used during database migration to add/update tags |
| `AddRange` | `public static bool[] AddRange(string[] tagText, GetSqlCommandDelegate getSqlCommand)` | Adds multiple tags; returns array of success flags |
| `GetIDFromTagText` | `public static int GetIDFromTagText(string tagText, GetSqlCommandDelegate getSqlCommand)` | Gets tag ID from database by text |
| `GetIDsFromTagText` | `public static int[] GetIDsFromTagText(string[] tagText, GetSqlCommandDelegate getSqlCommand)` | Converts array of tag texts to IDs |
| `GetTagTextFromID` | `public static string GetTagTextFromID(int tagID, GetSqlCommandDelegate getSqlCommand)` | Gets tag text from cached lookup by ID |
| `GetTagTextFromIDs` | `public static string[] GetTagTextFromIDs(int[] tagId, GetSqlCommandDelegate getSqlCommand)` | Converts array of tag IDs to texts |
| `ContainsTag` | `public bool ContainsTag(string text)` | Checks if tag text exists in cache |
| `UpdateList` | `public void UpdateList(GetSqlCommandDelegate getSqlCommand)` | Refreshes the in-memory tag cache from database |

**Delegate:**
```csharp
public delegate SqlCommand GetSqlCommandDelegate(bool bNewConnection);
```

---

### Utility
**Namespace:** `DTS.Common.Classes`

Static utility class providing helper methods for data access and error handling.

| Member | Signature | Description |
|--------|-----------|-------------|
| `GetBytesFromStringArray` | `public static byte[] GetBytesFromStringArray(string[] array, string separator)` | Converts string array to UTF8 bytes with separator |
| `GetAllErrorMessages` | `public static string GetAllErrorMessages(Exception ex)` | Concatenates exception message with all inner exception messages |
| `PingNetwork` | `public static bool PingNetwork(string hostNameOrAddress)` | Tests network connectivity with 4-second timeout |
| `GetUShort` | `public static ushort GetUInt(IDataReader reader, string column, ushort defaultValue = 0)` | Safe ushort extraction from IDataReader |
| `GetUInt` | `public static uint GetUInt(IDataReader reader, string column, uint defaultValue = 0)` | Safe uint extraction from IDataReader |
| `GetString` | `public static string GetString(IDataReader reader, string column, string defaultValue = "")` | Safe string extraction from IDataReader |
| `GetStringArray` | `public static string[] GetStringArray(IDataReader reader, string column, string[] defaultValue, string separator)` | Extracts string array from byte column |
| `GetInt` | `public static int GetInt(IDataReader reader, string column, int defaultValue = 0)` | Safe int extraction from IDataReader |
| `GetDouble` | `public static double GetDouble(IDataReader reader, string column, double defaultValue = 0D)` | Safe double extraction from IDataReader |
| `GetShort` | `public static short GetShort(IDataReader reader, string column, short defaultValue = 0)` | Safe short extraction from IDataReader |
| `GetNullableDateTime` | `public static DateTime? GetNullableDateTime(IDataReader reader, string column)` | Returns nullable DateTime from IDataReader |
| `GetUlong` | `public static ulong GetUlong(IDataReader reader, string column, ulong defaultValue = 0)` | Safe ulong extraction from IDataReader |
| `GetNullableInt` | `public static int? GetNullableInt(IDataReader reader, string column)` | Returns nullable int from IDataReader |
| `GetByteArray` | `public static byte[] GetByteArray(IDataReader reader, string column)` | Returns byte array or empty array if null/DBNull |
| `GetBool` | `public static bool GetBool(IDataReader reader, string column, bool defaultValue = false)` | Safe bool extraction from IDataReader |
| `GetDateTime` | `public static DateTime GetDateTime(IDataReader reader, string column, DateTime defaultValue)` | Safe DateTime extraction from IDataReader |
| `GetLong` | `public static long GetLong(IDataReader reader, string column, long defaultValue = 0)` | Safe long extraction from IDataReader |

---

### SensorImportData
**Namespace:** `DTS.Common.Classes`

Data transfer object for sensor import operations.

| Property | Type |
|----------|------|
| `GroupNameSensorListLookup` | `Dictionary<string, List<string>>` |
| `SensorGroupNameLookup` | `Dictionary<string, string>` |
| `SensorGroupTypeLookup` | `Dictionary<string, string>` |
| `GroupNameTestObjectLookup` | `Dictionary<string, string>` |
| `Errors` | `List<string>` (initialized to empty list) |
| `SensorISOCode` | `Dictionary<string, string>` |
| `SensorISOChannelName` | `Dictionary<string, string>` |
| `SensorUserCode` | `Dictionary<string, string>` |
| `SensorUserChannelName` | `Dictionary<string, string>` |
| `SensorDASSerialNumber` | `Dictionary<string, string>` |
| `SensorChannelIndex` | `Dictionary<string, int>` |

---

### TestSetupImportData
**Namespace:** `DTS.Common.Classes`

Data transfer object for test setup import operations.

| Property | Type | Default |
|----------|------|---------|
| `Name` | `string` | - |
| `Description` | `string` | - |
| `SamplesPerSecond` | `double` | - |
| `PosttriggerSeconds` | `double` | - |
| `PretriggerSeconds` | `double` | - |
| `RecordingMode` | `RecordingModes` | - |
| `CalibrationBehavior` | `CalibrationBehaviors` | - |
| `Version` | `int` | - |
| `TestChannelOrders` | `List<string>` | - |
| `Tags` | `List<string>` | - |
| `ClockMasterInput` | `InputClockSource` | `InputClockSource.None` |
| `ClockMasterOutput` | `OutputClockSource` | `OutputClockSource.None` |
| `ManageClocksOutsideOfDataPROMaster` | `bool` | `false` |
| `ManageClocksOutsideOfDataPROSlave` | `bool` | `false` |
| `ClockSlaveInput` | `OutputClockSource` | `OutputClockSource.None` |
| `ClockSlaveOutput` | `OutputClockSource` | `OutputClockSource.None` |
| `SampleRateForDAS` | `Dictionary<string, int>` | empty dictionary (readonly) |
| `DomainIdForDAS` | `Dictionary<string, uint>` | empty dictionary (readonly) |
| `IsClockMaster` | `Dictionary<string, bool>` | empty dictionary (readonly) |

---

### ImportPageType
**Namespace:** `DTS.Common.Classes`

Enum defining import page types.

| Value |
|-------|
| `ImportSensor` |
| `ImportTestSetup` |

---

## Invariants

1. **Singleton\<T\>**: Only one instance of type T can exist. The protected constructor enforces this by throwing `InvalidOperationException` if `Instance` is already non-null when the constructor is called.

2. **ServiceQueue**: Service calls execute one at a time in FIFO order. A new call does not start until the previous call invokes `MarkDone()`.

3. **ServiceQueue**: The `Started` flag prevents the same `ServiceCall` from being launched multiple times by concurrent `StartWork()` invocations.

4. **Tags**: The `_tagsLookup` dictionary is cached in memory and only refreshed via `UpdateList()` or when new tags are added via `Commit()`.

5. **TagAwareBase.TagIDs**: Never null; always initialized to an empty array if null is assigned.

6. **Tags.Tag.INVALID_ID**: Constant value of `-1` represents an invalid/unassigned tag ID.

7. **Utility IDataReader methods**: All methods handle `DBNull.Value` and