init

enriched-qwen3-coder-next/Common/DTS.Common.DataModel/Classes/TestObject.md

@@ -0,0 +1,179 @@
+---
+source_files:
+  - Common/DTS.Common.DataModel/Classes/TestObject/TemplateChannelUI.cs
+  - Common/DTS.Common.DataModel/Classes/TestObject/TestObjectTemplateCollection.cs
+  - Common/DTS.Common.DataModel/Classes/TestObject/TestObjectList.cs
+  - Common/DTS.Common.DataModel/Classes/TestObject/TestTestObject.cs
+  - Common/DTS.Common.DataModel/Classes/TestObject/TestObjectTemplate.cs
+generated_at: "2026-04-16T03:34:52.105415+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "600a818df3b392d9"
+---
+
+# Documentation: DataModel.TestObject Module
+
+## 1. Purpose
+
+This module provides data model abstractions for ISO 13499-compliant test objects, templates, and related UI wrappers within the DataPROWin7 application. It serves as the bridge between low-level ISO database entities (`DTS.Common.ISO.*`) and high-level WPF UI components, enabling template management, test object instantiation, and channel configuration. The module supports both system-built and user-defined templates, embedded vs. external template references, and test-specific overrides (e.g., excitation settings, position assignments). It is central to test setup definition, serialization, and runtime configuration.
+
+## 2. Public Interface
+
+### `TemplateChannelUI`
+- **`TemplateChannelUI(DTS.Common.ISO.TestObjectTemplateChannel channel)`**  
+  Constructor that wraps an ISO `TestObjectTemplateChannel` instance. Stores the channel in the `Channel` property.
+- **`Channel` (property)**  
+  Gets/sets the underlying `DTS.Common.ISO.TestObjectTemplateChannel`. Implements `INotifyPropertyChanged` via `BasePropertyChanged`.
+
+### `TestObjectTemplateCollection`
+- **`TemplateCollection` (static property)**  
+  Singleton accessor. Returns the single instance of `TestObjectTemplateCollection`, lazily initialized.
+- **`SysBuiltTestObjectTemplate` (property)**  
+  Returns the read-only system-built template (note: `_sysBuiltTestObjectTemplate` is declared but *never initialized* in the source — likely incomplete).
+- **`GetTemplate(string templateId)` (method)**  
+  Retrieves a `TestObjectTemplate` by `templateId` from the ISO database (`ApplicationProperties.IsoDb`). Returns `null` if not found.
+
+### `TestObjectList`
+- **`TestObjectsList` (static property)**  
+  Singleton accessor. Thread-safe (uses `lock(MyLock)`). Returns the single instance of `TestObjectList`.
+- **`Add(TestObject to, bool bNotify)` (method)**  
+  Adds a `TestObject` to the list. Sets `LastModifiedBy` and `LastModified` on the object, calls `Commit()`, and optionally raises `OnPropertyChanged("TestObjects")` if `bNotify` is `true`.
+- **`UpdateAll()` (method)**  
+  Raises `OnPropertyChanged("TestObjects")` to notify UI of changes (e.g., after bulk operations).
+
+### `TestTestObject`
+- **Constructors**  
+  - `TestTestObject(TestObject obj)`  
+    Base constructor wrapping a `TestObject`.
+  - `TestTestObject(TestTestObject obj, bool convertToEmbedded)`  
+    Copy constructor with support for converting to embedded mode (generates new GUIDs for template and serial number).
+  - `TestTestObject(TestObject obj, bool convertToEmbedded)`  
+    Constructor for non-`TestTestObject` inputs with embedded conversion support.
+  - `TestTestObject(TestTestObject to)`  
+    Copy constructor for metadata (calls `MetaCommonConstructor`).
+- **Properties**  
+  - `Position` (`DTS.Common.ISO.MMEPositions`)  
+    Gets/sets the group position. When set to `UserSetKey` (`"@"`), UI shows a button instead of a combo box. When set to a standard position, propagates the position to all required channels’ sensors.
+  - `TestObject` (`DTS.Common.ISO.MMETestObjects`)  
+    Gets/sets the test object type. When set, propagates the test object to all required channels’ sensors.
+  - `GroupPositionComboBoxVisible`, `GroupPositionButtonVisible` (`Visibility`)  
+    Controls UI visibility based on `Position` value. *Note: Non-ISO mode support is commented out.*
+  - `AvailableGroupPositions` (`MMEPositions[]`)  
+    Returns an array containing `_channelDefaultsGUID` (`#`) and all positions from `ApplicationProperties.IsoDb.GetPositions()`.
+  - `AvailablePositions` (`MMEPositions[]`)  
+    Returns positions from `ApplicationProperties.IsoDb.GetPositions()`.
+  - `ChannelTypes` (`string[]`)  
+    Returns `["(no channels)"]` + unique channel types from `ApplicationProperties.IsoDb`.
+  - `AddedGroups` (`TestObject[]`)  
+    Gets/sets a list of added system-built test objects; raises `OnPropertyChanged("AddedSysBuiltTestObjects")` and `OnPropertyChanged("AddedSysBuiltTestObjectsMME")`.
+  - `DisplayOrder`, `IsAdd`, `SysBuilt`, `SerialNumberConverted`  
+    Metadata properties (no explicit backing fields beyond `DisplayOrder` and `IsAdd`).
+  - `ExcitationWarmupTimeMS`, `TargetSampleRate`, `PreTriggerSeconds`, `PostTriggerSeconds`  
+    Test-specific configuration properties.
+- **Methods**  
+  - `Rename(string oldName, string newName)`  
+    Updates `SerialNumber`, `OriginalSerialNumber`, `OriginalTemplate`, `TestSetupName`, and generates new GUIDs for `TemplateName` and `OriginalTemplateName`.
+  - `SetTestObject(string s)`, `SetPosition(string s)`  
+    Low-level setters that bypass property change notifications for `Position`/`TestObject` UI visibility logic.
+  - `CompareTo(TestTestObject other)`  
+    Compares by `DisplayOrder`, then falls back to base comparison.
+
+### `TestObjectTemplate`
+- **Constructors**  
+  - `TestObjectTemplate()`  
+    Default constructor; initializes with empty strings and first available test object.
+  - `TestObjectTemplate(TestObjectTemplate copy, ref ISO13499FileDb db)`  
+    Deep copy constructor.
+  - `TestObjectTemplate(DTS.Common.ISO.TestObjectTemplate template, ref ISO13499FileDb db)`  
+    Wraps an ISO template.
+  - `TestObjectTemplate(DTS.Common.ISO.TestObjectTemplate template, ref ISO13499FileDb db, List<MMETestObjects> testObjects)`  
+    Wraps an ISO template, preferring a provided list of `MMETestObjects`.
+- **Properties**  
+  - `TemplateName`, `TemplateDescription`, `LastModified`, `LastModifiedBy`, `TemplateParent`, `SysBuilt`, `IsLocalOnly`, `Embedded`, `OriginalTemplateName`  
+    Standard metadata properties. `Embedded` and `OriginalTemplateName` synchronize with the underlying `_template` object.
+  - `TestObject` (`MMETestObjects`), `TestObjectType` (`string`)  
+    Gets/sets test object and type. Setting `TestObjectType` triggers channel list regeneration and order assignment.
+  - `RequiredChannels` (`List<TestObjectTemplateChannel>`)  
+    List of required channels (not auto-populated; must be set explicitly).
+  - `TemplateAllChannels` (`TestObjectTemplateChannel[]`), `TemplateAllUIChannels` (`TemplateChannelUI[]`)  
+    Arrays of all channels. `TemplateAllChannels` stores the raw ISO channels; `TemplateAllUIChannels` wraps them in `TemplateChannelUI` for UI binding.
+  - `AvailableTestObjectTypes` (`string[]`)  
+    Derived from `TestObject` via `ApplicationProperties.IsoDb.GetTestObjectTypeForTestObject(...)`.
+  - `TestObjectTypeIndex` (`int`)  
+    Index into `AvailableTestObjectTypes`; setting it updates `TestObjectType`.
+- **Methods**  
+  - `AssignOrders()`  
+    Sorts `TemplateAllChannels` and assigns `DisplayOrder` to channels with `-1`.
+  - `ToISOTestObjectTemplate()`  
+    Converts to a standalone `DTS.Common.ISO.TestObjectTemplate` (for persistence/export).
+  - `MarkChanged(string tag)`  
+    Raises `OnPropertyChanged(tag)`.
+  - `CompareTo(TestObjectTemplate rhs)`  
+    Compares by `TemplateName` (ordinal).
+  - `ReadXML(XmlElement root, Dictionary<long, MMEPossibleChannels> importChannels)` (static)  
+    Deserializes an ISO template from XML. Delegates to `ProcessXMLElement` and `ProcessChannelXMLNode`.
+  - `ProcessXMLElement`, `ProcessChannelXMLNode` (private static)  
+    XML parsing helpers. `ProcessChannelXMLNode` handles channel-specific fields (e.g., `Required`, `DisplayOrder`, `LocalOnly`, `NameOfTheChannel`).
+
+## 3. Invariants
+
+- **Singleton Consistency**:  
+  `TestObjectTemplateCollection.TemplateCollection` and `TestObjectList.TestObjectsList` are singletons. `TestObjectsList` uses explicit locking for thread safety; `TemplateCollection` does not (potential race condition on first access).
+- **Template Identity**:  
+  `TestObjectTemplate.TemplateName` and `OriginalTemplateName` must be non-null. `Embedded` templates use `OriginalTemplateName` for display (`ToString()` override).
+- **Channel Ordering**:  
+  `TestObjectTemplate.AssignOrders()` ensures `DisplayOrder` is non-decreasing and ≥ 0 for all channels after assignment.
+- **Position Propagation**:  
+  Setting `TestTestObject.Position` to a non-`UserSetKey` value propagates the position to all required channels’ sensors via `SetSensor(...)`.
+- **Test Object Propagation**:  
+  Setting `TestTestObject.TestObject` propagates the test object to all required channels’ sensors.
+- **XML Field Validation**:  
+  `ProcessChannelXMLNode` requires `MMEChannelId` and `MMEChannelType` to be present and parseable; otherwise, the channel is skipped.
+- **Metadata Copying**:  
+  `TestTestObject` copy constructors call `MetaCommonConstructor` to ensure test-specific metadata (e.g., `ExcitationWarmupTimeMS`, `Position`) is preserved.
+
+## 4. Dependencies
+
+### Internal Dependencies
+- **Base Classes**:  
+  `BasePropertyChanged` (for `INotifyPropertyChanged` implementation).
+- **ISO Layer**:  
+  `DTS.Common.ISO.TestObjectTemplate`, `TestObjectTemplateChannel`, `MMEPositions`, `MMETestObjects`, `MMEPossibleChannels`, `ISO13499FileDb`.
+- **Application Context**:  
+  `ApplicationProperties.IsoDb` (central database access), `ApplicationProperties.CurrentUser` (for `LastModifiedBy`).
+- **WPF**:  
+  `System.Windows.Visibility` (for UI state).
+
+### External Dependencies
+- **Logging**: `DTS.Common.Utilities.Logging` (imported but no usage observed in source).
+- **DataModel**: `DTS.Common.DataModel` (namespace for shared types).
+- **Utilities**: `System`, `System.Collections.Generic`, `System.Linq`, `System.Xml`.
+
+### Usage by Other Modules
+- `TestObjectTemplateCollection` is used to retrieve templates by ID (e.g., during test setup loading).
+- `TestObjectList` is used to manage test objects in a list (e.g., during test execution).
+- `TestTestObject` is used for test-specific test objects with override capabilities.
+- `TemplateChannelUI` is used in UI bindings for template channel properties.
+
+## 5. Gotchas
+
+- **Uninitialized `SysBuiltTestObjectTemplate`**:  
+  `_sysBuiltTestObjectTemplate` is declared but never assigned in `TestObjectTemplateCollection`. Accessing `SysBuiltTestObjectTemplate` will return `null`.
+- **Thread Safety Gap**:  
+  `TestObjectTemplateCollection.TemplateCollection` is not thread-safe on first access (no locking), while `TestObjectList.TestObjectsList` is.
+- **Non-ISO Mode Code Commented Out**:  
+  `GroupPositionComboBoxVisible` and `GroupPositionButtonVisible` getters contain commented-out logic for `NO_ISO` mode. This may cause unexpected UI behavior if non-ISO mode is active.
+- **Channel Display Order Logic**:  
+  `AssignOrders()` and `ProcessChannelXMLNode` both assign `DisplayOrder` to `-1` channels, but `AssignOrders()` uses the *current* max + 1, while `ProcessChannelXMLNode` uses the *newly added* channel’s max + 1. This can lead to inconsistent ordering if channels are added incrementally.
+- **Template Name Overwrite in `Rename`**:  
+  `Rename` replaces `TemplateName` and `OriginalTemplateName` with new GUIDs, but does not update `TemplateParent`. This may break template hierarchy references.
+- **`TestObjectTemplateChannel` Duplication**:  
+  `TemplateAllChannels` and `TemplateAllUIChannels` store overlapping data. `TemplateAllChannels` is derived from `_allUIChannels`, but setting one does not automatically sync the other (e.g., `TemplateAllChannels` setter calls `TemplateAllUIChannels = ...`, but not vice versa).
+- **`TestTestObject` Constructor Overload Ambiguity**:  
+  Two constructors accept `(TestObject obj, bool convertToEmbedded)`. One is for `TestTestObject`, the other for `TestObject`. This may cause confusion or unintended behavior if misused.
+- **`_userSetGUID` and `_channelDefaultsGUID`**:  
+  These static `MMEPositions` instances are created with `Guid.NewGuid()` at type initialization. If multiple app domains or test runs occur, GUIDs may collide or behave unexpectedly (though unlikely in practice).
+- **`ToISOTestObjectTemplate` Omits Fields**:  
+  The method does not copy `Version`, `CRC32`, or `Icon` to the resulting ISO template, even though these are part of `GroupTemplateFields`.
+- **`ProcessChannelXMLNode` Ignores Many Fields**:  
+  Several `GroupTemplateChannelFields` (e.g., `BitResolution`, `ChannelAmplitudeClass`, `Comments`) are parsed but not applied to the channel. This may lead to data loss during XML import.