306 lines
16 KiB
Markdown
306 lines
16 KiB
Markdown
---
|
|
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-16T11:58:55.221476+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "ab2980ca84007830"
|
|
---
|
|
|
|
# DTS.CommonCore/Classes Module Documentation
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
This module provides foundational infrastructure classes for the DTS application, including a thread-safe singleton pattern implementation, a sequential service call queue, UI region name constants, tag management with database persistence, data transfer objects for import operations, and utility helpers for database reader type conversion. These classes serve as core building blocks used throughout the system for common patterns like status reporting, service coordination, and data import workflows.
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### StatusAndProgressBarEventArgs
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
A POCO event argument class for status and progress bar updates.
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| `StatusColor` | `Color` | The color to display for status text |
|
|
| `StatusText` | `string` | The status message text |
|
|
| `ProgressValue` | `double` | The progress bar value |
|
|
| `ProgressBarVisibility` | `Visibility` | Controls progress bar visibility |
|
|
| `Requester` | `IBaseViewModel` | Reference to the requesting view model |
|
|
| `ErrorText` | `string` | Error message text |
|
|
|
|
---
|
|
|
|
### Singleton\<T>
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
Generic singleton base class. Derive via `class MyClass : Singleton<MyClass>`.
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `Instance` | `public static T Instance { get; }` | Returns the singleton instance, lazily created |
|
|
| Constructor | `protected Singleton()` | Protected constructor that throws `InvalidOperationException` if instance already exists |
|
|
|
|
---
|
|
|
|
### ServiceCall
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
Represents a unit of work for the service queue.
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `Started` | `public bool Started { get; set; }` | Indicates if the call has started execution |
|
|
| `WorkAction` | `public Action WorkAction { get; set; }` | The action to execute |
|
|
| `Name` | `public string Name { get; set; }` | Identifier for the service call |
|
|
| `MarkDone` | `public void MarkDone()` | Marks the call as finished, triggering next item in queue |
|
|
| Constructor | `public ServiceCall(string name)` | Creates a named service call |
|
|
|
|
---
|
|
|
|
### ServiceQueue
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
Manages sequential execution of service calls.
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `Enqueue` | `public static void Enqueue(ServiceCall call)` | Adds a service call to the queue; starts immediately if queue is empty |
|
|
| `MarkFinished` | `public static void MarkFinished(ServiceCall call)` | Removes completed call and starts next if available |
|
|
|
|
---
|
|
|
|
### RegionNames
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
Static class containing region name constants for UI composition (likely Prism regions).
|
|
|
|
**Constants include:**
|
|
- `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`
|
|
|
|
---
|
|
|
|
### ImportPageType
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
Enum defining import types.
|
|
|
|
| Value | Description |
|
|
|-------|-------------|
|
|
| `ImportSensor` | Sensor import operation |
|
|
| `ImportTestSetup` | Test setup import operation |
|
|
|
|
---
|
|
|
|
### SensorImportData
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
DTO 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`
|
|
|
|
DTO 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) |
|
|
|
|
---
|
|
|
|
### TagAwareBase
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
Abstract base class for objects that support tagging.
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `TagType` | `public abstract TagTypes TagType { get; }` | Abstract property defining tag type |
|
|
| `TagsBlobBytes` | `public byte[] TagsBlobBytes { get; set; }` | Serializes/deserializes TagIDs as byte array |
|
|
| `TagIDs` | `public int[] TagIDs { get; set; }` | Array of tag IDs; defaults to empty array |
|
|
| `SetTagsFromCommaSeparatedString` | `public void SetTagsFromCommaSeparatedString(string tagText, Tags.GetSqlCommandDelegate getSqlCommand)` | Parses comma-separated tags and sets them |
|
|
| `SetTags` | `public virtual void SetTags(string[] tagsText, Tags.GetSqlCommandDelegate getSqlCommand)` | Sets 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 tag text array from IDs |
|
|
| `GetTagIDs` | `public virtual int[] GetTagIDs()` | Returns TagIDs array |
|
|
| `RemoveTags` | `public virtual void RemoveTags(string[] tagsText)` | Removes tags (implementation incomplete in source) |
|
|
| `TagCompatible(string, delegate)` | `public bool TagCompatible(string tags, Tags.GetSqlCommandDelegate getSqlCommand)` | Checks if any tag in comma-separated string matches |
|
|
| `TagCompatible(int[])` | `public virtual bool TagCompatible(int[] tags)` | Checks for intersecting tag IDs |
|
|
| `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 and commits tags in one operation |
|
|
| `Commit` | `public void Commit(int id, TagTypes tagType, Tags.GetSqlCommandDelegate getSqlCommand)` | Persists tag assignments to database |
|
|
| `GetTagIdList` | `public List<int> GetTagIdList(int objectId, TagTypes tagType, Tags.GetSqlCommandDelegate getSqlCommand)` | Retrieves tag IDs for an object from database |
|
|
|
|
**Nested Enum: TagTypes**
|
|
| Value | Description |
|
|
|-------|-------------|
|
|
| `User` | User tag type |
|
|
| `Group` | Group tag type |
|
|
| `Template` | Template tag type |
|
|
| `TestSetup` | Test setup tag type |
|
|
| `Sensors` | Sensor tag type |
|
|
| `SensorModels` | Sensor model tag type |
|
|
|
|
---
|
|
|
|
### Tags
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
Manages tag persistence and caching.
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `GetSqlCommandDelegate` | `public delegate SqlCommand GetSqlCommandDelegate(bool bNewConnection)` | Delegate for database command creation |
|
|
| `GetTagsInstance` | `public static Tags GetTagsInstance(GetSqlCommandDelegate getSqlCommand)` | Returns singleton instance |
|
|
| `AddTag` | `public static bool AddTag(string tagText, GetSqlCommandDelegate getSqlCommand)` | Adds tag if not present; returns true if added |
|
|
| `MigrateTag` | `public static bool MigrateTag(string tagText, GetSqlCommandDelegate getSqlCommand)` | Adds/updates tag during migration |
|
|
| `AddRange` | `public static bool[] AddRange(string[] tagText, GetSqlCommandDelegate getSqlCommand)` | Adds multiple tags; trims start whitespace |
|
|
| `GetIDFromTagText` | `public static int GetIDFromTagText(string tagText, GetSqlCommandDelegate getSqlCommand)` | Gets ID from database for tag text |
|
|
| `GetIDsFromTagText` | `public static int[] GetIDsFromTagText(string[] tagText, GetSqlCommandDelegate getSqlCommand)` | Converts tag text array to ID array |
|
|
| `GetTagTextFromID` | `public static string GetTagTextFromID(int tagID, GetSqlCommandDelegate getSqlCommand)` | Gets tag text from cached lookup |
|
|
| `GetTagTextFromIDs` | `public static string[] GetTagTextFromIDs(int[] tagId, GetSqlCommandDelegate getSqlCommand)` | Converts ID array to tag text array |
|
|
| `ContainsTag` | `public bool ContainsTag(string text)` | Checks if tag exists in cache |
|
|
| `UpdateList` | `public void UpdateList(GetSqlCommandDelegate getSqlCommand)` | Refreshes tag cache from database |
|
|
|
|
**Nested Class: Tags.Tag**
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `INVALID_ID` | `public const int INVALID_ID = -1` | Constant for invalid tag ID |
|
|
| `ID` | `public int ID { get; set; }` | Tag identifier |
|
|
| `Text` | `public string Text { get; set; }` | Tag text |
|
|
| `IsObsolete` | `public bool IsObsolete { get; set; }` | Obsolescence flag |
|
|
| Constructor | `public Tag(string tagText, int tagId)` | Creates tag with text and ID |
|
|
| Constructor | `public Tag(Tag copy)` | Copy constructor |
|
|
| Constructor | `public Tag(IDataRecord reader)` | Creates tag from data reader |
|
|
| Constructor | `public Tag(DataRow dr)` | Creates tag from data row |
|
|
| `Clone` | `public object Clone()` | ICloneable implementation |
|
|
|
|
---
|
|
|
|
### Utility
|
|
**Namespace:** `DTS.Common.Classes`
|
|
|
|
Static utility class with helper methods.
|
|
|
|
| Method | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `GetBytesFromStringArray` | `public static byte[] GetBytesFromStringArray(string[] array, string separator)` | Joins array with separator and converts to UTF8 bytes |
|
|
| `GetAllErrorMessages` | `public static string GetAllErrorMessages(Exception ex)` | Returns all exception messages including inner exceptions |
|
|
| `PingNetwork` | `public static bool PingNetwork(string hostNameOrAddress)` | Pings host with 4-second timeout; returns success status |
|
|
| `GetUShort` | `public static ushort GetUShort(IDataReader reader, string column, ushort defaultValue = 0)` | Safely reads ushort from reader |
|
|
| `GetUInt` | `public static uint GetUInt(IDataReader reader, string column, uint defaultValue = 0)` | Safely reads uint from reader |
|
|
| `GetString` | `public static string GetString(IDataReader reader, string column, string defaultValue = "")` | Safely reads string from reader |
|
|
| `GetStringArray` | `public static string[] GetStringArray(IDataReader reader, string column, string[] defaultValue, string separator)` | Reads byte array from reader, decodes to UTF8, splits by separator |
|
|
| `GetInt` | `public static int GetInt(IDataReader reader, string column, int defaultValue = 0)` | Safely reads int from reader |
|
|
| `GetDouble` | `public static double GetDouble(IDataReader reader, string column, double defaultValue = 0D)` | Safely reads double from reader |
|
|
| `GetShort` | `public static short GetShort(IDataReader reader, string column, short defaultValue = 0)` | Safely reads short from reader |
|
|
| `GetNullableDateTime` | `public static DateTime? GetNullableDateTime(IDataReader reader, string column)` | Reads nullable DateTime from reader |
|
|
| `GetUlong` | `public static ulong GetUlong(IDataReader reader, string column, ulong defaultValue = 0)` | Safely reads ulong from reader |
|
|
| `GetNullableInt` | `public static int? GetNullableInt(IDataReader reader, string column)` | Reads nullable int from reader |
|
|
| `GetByteArray` | `public static byte[] GetByteArray(IDataReader reader, string column)` | Reads byte array; returns empty array for null/DBNull |
|
|
| `GetBool` | `public static bool GetBool(IDataReader reader, string column, bool defaultValue = false)` | Safely reads bool from reader |
|
|
| `GetDateTime` | `public static DateTime GetDateTime(IDataReader reader, string column, DateTime defaultValue)` | Safely reads DateTime from reader |
|
|
| `GetLong` | `public static long GetLong(IDataReader reader, string column, long defaultValue = 0)` | Safely reads long from reader |
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
### Singleton\<T>
|
|
- The generic type `T` must have a public parameterless constructor (`where T : new()`).
|
|
- `Instance` will always return the same object reference after first creation.
|
|
- Calling `new T()` directly after `Instance` has been accessed will throw `InvalidOperationException`.
|
|
- If the singleton constructor throws, the exception is captured and re-thrown on subsequent `Instance` access.
|
|
|
|
### ServiceQueue
|
|
- Work items execute sequentially, never concurrently.
|
|
- Only the first item in the queue is ever marked as `Started = true`.
|
|
- `MarkFinished` must be called by the `WorkAction` to advance the queue.
|
|
- Queue operations are thread-safe via `QueueLock`.
|
|
|
|
### Tags
|
|
- `Tag.INVALID_ID` is `-1`.
|
|
- Tag IDs of `0` are skipped during cache population.
|
|
- Tag text is trimmed of leading whitespace before database operations in `AddRange`.
|
|
- The `_tagsLookup` dictionary is keyed by tag text, not ID.
|
|
|
|
### TagAwareBase
|
|
- `TagIDs` is never null; it defaults to an empty array.
|
|
- `TagsBlobBytes` format: 4 bytes per int (sizeof(int)), using `Buffer.BlockCopy`.
|
|
|
|
### Utility
|
|
- All `IDataReader` helper methods handle `DBNull.Value` and return default values.
|
|
- `GetByteArray` returns an empty array (not null) for null/DBNull columns.
|
|
- `PingNetwork` timeout is fixed at 4444ms.
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### External Dependencies (Imports)
|
|
| Module | Dependencies |
|
|
|--------|--------------|
|
|
| StatusAndProgressBarEventArgs | `System.Windows`, `System.Windows.Media`, `DTS.Common.Base` (IBaseViewModel) |
|
|
| Singleton\<T> | `System` |
|
|
| ImportData | `DTS.Common.Enums`, `DTS.Common.Enums.Sensors`, `DTS.Common.Interface.Sensors`, `System`, `System.Collections.Generic` |
|
|
| RegionNames | None |
|
|
| ServiceCall | `DTS.Common.Utilities.Logging`, `System`, `System.Collections.Generic`, `System.Linq`, `System.Threading.Tasks` |
|
|
| TagAwareBase | `System`, `System.Collections.Generic`, `System.Data`, `System.Data.SqlClient`, `System.Linq`, `System.Text`, `DTS.Common.Utilities.Logging` |
|
|
| Tags | `System`, `System.Collections.Generic`, `System.Data`, `System.Data.SqlClient`, `System.Linq`, `DTS.Common.Utilities.Logging` |
|
|
| Utility | `System`, `System.Text`, `System.Net.NetworkInformation`, `System.Data`, `DTS.Common.Utilities.Logging`, `System |