166 lines
8.9 KiB
Markdown
166 lines
8.9 KiB
Markdown
---
|
||
source_files:
|
||
- 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
|
||
generated_at: "2026-04-16T03:31:59.768999+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "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**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
public static TestTemplate[] TestSetups { get; }
|
||
```
|
||
Returns a snapshot of `_actualTestTemplates` (as `TestTemplate[]`), containing *all* loaded test templates (not filtered by completeness).
|
||
|
||
- **`UpdateTestSetupListIfStale()` method**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
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**
|
||
```csharp
|
||
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). |