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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T02:12:54.891278+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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:

  • 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 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