DP44/enriched-qwen3-coder-next/Common/DTS.Common.DataModel/Common.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.DataModel/Common/StatusHelpers.cs Common/DTS.Common.DataModel/Common/TestObjectHelper.cs Common/DTS.Common.DataModel/Common/ChannelHelper.cs Common/DTS.Common.DataModel/Common/TestSetupCollection.cs	2026-04-16T03:31:59.768999+00:00	Qwen/Qwen3-Coder-Next-FP8	1	2101fc7191561021

Common

Documentation: DTS.Common.DataModel.Common Module

---

Purpose

This module provides utility helpers for managing test setup metadata, channel naming conventions, and status reporting within the DTS data modeling layer. It centralizes logic for caching and refreshing test setup lists (with staleness detection via CRC and time-based invalidation), generating warning channel display names, and exposing legacy TOM channel filter constants. It acts as a coordination layer between data persistence (via SQL queries), UI eventing (via Prism’s IEventAggregator), and domain-specific constants, enabling consistent behavior across UI and background processes.

---

Public Interface

StatusHelpers class

• SetProgressValueDelegate delegate

  public delegate void SetProgressValueDelegate(IDASCommunication idas, double progressValue, TSRAIRGoStatus.StatusTypes? status);
  

  Signature for a callback used to set progress and status on a DAS communication interface.

• SetStatus2 method

  public static void SetStatus2(IDASCommunication das, int progressValue, TSRAIRGoStatus.StatusTypes? status, SetProgressValueDelegate setProgressValue)
  

  Invokes the provided setProgressValue delegate with the given das, progressValue, and status. This is a thin wrapper—no validation or transformation is performed on inputs.

TestObjectHelper class

• TDC_LEGACY_TOM_CUTOFF_SPS constant

  public const double TDC_LEGACY_TOM_CUTOFF_SPS = 8000;
  

  Threshold sampling rate (samples per second) used to determine TOM channel filter selection in legacy TDC systems. Channels ≥ 8000 SPS use TDC_LEGACY_TOM_HIGH_FILTER.

• TDC_LEGACY_TOM_HIGH_FILTER constant

  public const double TDC_LEGACY_TOM_HIGH_FILTER = 1650D;
  

  Default high-pass filter frequency (in Hz) applied to TOM channels recorded at >8000 SPS in legacy TDC (CFC1000 equivalent). Note: Values ≤8000 SPS are not handled in this module.

ChannelHelper class

• GetWarningChannelName method

  public static string GetWarningChannelName(IGroupChannel groupChannel)
  

  Generates a human-readable warning label for a channel, using the following logic:
  • Uses TestSetupOrder if ≥ 0; otherwise uses GroupChannelOrder.
  • If GetChannelName(SerializedSettings.ISOViewMode) returns a non-empty string, uses that quoted (e.g., 'MyChannel').
  • Otherwise, appends empty string '', then optionally appends sensor info (if SensorValid) and hardware info (if HardwareValid), e.g., 1, '', (SensorA) DAS1.

TestSetupCollection class

• TestSetupIds property

  public static List<string> TestSetupIds { get; }
  

  Returns a copy of the internal _testSetupList (as a List<string>), containing names of test setups. Access is thread-safe via TestSetupListLock.

• TestSetupList property

  public static string[] TestSetupList { get; }
  

  Returns an array of test setup names (only complete tests if called directly, but behavior differs based on context—see Gotchas). Triggers full refresh if _testSetupList is null/empty. Uses ProgressBarEvent to report progress during refresh.

• TestSetups property

  public static TestTemplate[] TestSetups { get; }
  

  Returns a snapshot of _actualTestTemplates (as TestTemplate[]), containing all loaded test templates (not filtered by completeness).

• UpdateTestSetupListIfStale() method

  public static void UpdateTestSetupListIfStale()
  

  Conditionally triggers UpdateTestSetupList() if:

  • Last update was >30 minutes ago (MIN_TESTS_UPDATEINTERVAL_MINUTES), or
  • CRC of the underlying TestSetups table in SQL has changed.

• UpdateTestSetupList(TestTemplate test) method

  public static void UpdateTestSetupList(TestTemplate test)
  

  Updates the cached list for a single test:

  • If test.IsDirty and !test.IsComplete, removes test.Name from _testSetupList.
  • If !test.IsDirty and !test.IsComplete, does nothing.
  • Otherwise, adds test.Name to _testSetupList (if not already present).

• UpdateTestSetupList(Action onCompleteAction = null) method

  public static void UpdateTestSetupList(Action onCompleteAction = null)
  

  Performs a full refresh of _testSetupList and _actualTestTemplates:

  • Fetches all templates via TestTemplateList.TestTemplatesList.AllTemplates.
  • Publishes ProgressBarEvent with percentage updates.
  • Adds all templates to _testSetupList (regardless of IsComplete).
  • Computes CRC over TestSetups DB table and stores in _crc.
  • Invokes onCompleteAction if provided.

• TestSetupListLock property

  public static object TestSetupListLock { get; }
  

  Lock object used to synchronize access to _testSetupList, _actualTestTemplates, _crc, and _lastUpdateTime.

---

Invariants

1. Thread Safety: All public static properties/methods accessing _testSetupList, _actualTestTemplates, _crc, or _lastUpdateTime are guarded by TestSetupListLock.
2. Staleness Policy: _testSetupList is considered stale if:
   • Time since _lastUpdateTime > 30 minutes (MIN_TESTS_UPDATEINTERVAL_MINUTES), or
   • CRC of the TestSetups DB table (GetCRC()) differs from stored _crc.
3. CRC Computation: CRC is computed over a byte list derived from TestSetups table columns: [TestSetupName], [Dirty], [Complete], [LastModified] (binary representation).
4. Progress Reporting: Full refresh operations (UpdateTestSetupList() and TestSetupList getter) publish ProgressBarEvent with percentage updates; partial updates (e.g., UpdateTestSetupList(TestTemplate)) do not.

---

Dependencies

Imports/References

• DTS.Common.Interface.DASFactory.IDASCommunication – Used by StatusHelpers.SetStatus2.
• DTS.Common.Enums.TSRAIRGo.TSRAIRGoStatus.StatusTypes – Status enum used in SetStatus2.
• DataPROWin7.Common – Referenced in ChannelHelper (via SerializedSettings.ISOViewMode).
• DTS.Common.Interface.Channels.IGroupChannel – Used in ChannelHelper.GetWarningChannelName.
• DataPROWin7.DataModel – Provides TestTemplate, TestTemplateList.
• Prism.Ioc.IContainerLocator, Prism.Events.IEventAggregator – Used for eventing and service resolution.
• System.Windows.Threading.Dispatcher, System.Windows.Application – Used to check dispatcher access before resolving services.
• DTS.Utilities.Crc32 – Custom CRC32 implementation used in GetCRC().

External Dependencies

• SQL Database: Storage.DbOperations.GetSQLCommand() queries [TestSetups] table.
• Prism Event Aggregator: Relies on ProgressBarEvent being registered and subscribed to.

---

Gotchas

1. TestSetupList behavior is context-dependent:

   • When accessed after a full UpdateTestSetupList() call, it returns all test names (including incomplete ones).
   • When accessed initially (empty cache), it filters to only complete tests (if (!t.IsComplete) { continue; }).
     → This inconsistency may cause unexpected omissions or inclusions depending on call order.

2. UpdateTestSetupList(TestTemplate) silently fails if ContainerLocator.Container or IEventAggregator is unavailable (e.g., during cmdline import), returning early without updating the list.

3. TestSetupIds returns a List<string> but is documented as List<string> in source—however, TestSetupList returns string[]. Ensure callers do not assume mutability or shared references.

4. SetStatus2 is a trivial wrapper: It does not validate idas, progressValue, or status. Misuse (e.g., null delegate) will throw at runtime.

5. TDC_LEGACY_TOM_CUTOFF_SPS is a legacy constant: The comment explicitly states that channels ≤8000 SPS are not handled in this module. Do not assume support for lower sampling rates.

6. TestSetupList getter may block indefinitely if ContainerLocator.Container.Resolve<IEventAggregator>() fails (e.g., in headless/test environments), since it does not guard against null eventAggregator in the fallback path (unlike UpdateTestSetupList() methods).

7. CRC computation is expensive: GetCRC() performs a full table scan and byte marshaling. Avoid calling it frequently outside UpdateTestSetupListIfStale().

8. No validation of progressValue in SetStatus2: The delegate may expect double in [0,100] range, but the method accepts any int (e.g., negative or >100).