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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Classes/TestSetups/SimpleHardware.cs Common/DTS.Common/Classes/TestSetups/TestSetupHelper.cs Common/DTS.Common/Classes/TestSetups/ExtraProperties.cs Common/DTS.Common/Classes/TestSetups/ROIPeriodChannelRecord.cs Common/DTS.Common/Classes/TestSetups/TestSetupHardwareRecord.cs Common/DTS.Common/Classes/TestSetups/TestSetupROIsRecord.cs Common/DTS.Common/Classes/TestSetups/CalculatedChannelRecord.cs Common/DTS.Common/Classes/TestSetups/ISFFile.cs Common/DTS.Common/Classes/TestSetups/GraphRecord.cs Common/DTS.Common/Classes/TestSetups/RegionOfInterest.cs Common/DTS.Common/Classes/TestSetups/ISFSensorRecord.cs	2026-04-16T03:18:08.842826+00:00	Qwen/Qwen3-Coder-Next-FP8	1	9bc5c021742b55c0

TestSetups Module Documentation

1. Purpose

This module provides core data structures and helper utilities for representing and managing test setup configurations within the DTS system. It defines immutable and mutable record types that model database entities (e.g., hardware assignments, ROIs, calculated channels, graphs), along with supporting infrastructure for ISF file I/O and test setup naming. The module serves as the data layer abstraction for test setup management—enabling serialization/deserialization from database queries, file formats (ISF), and interoperation with UI and business logic layers through interfaces and property change notifications.

2. Public Interface

Classes

SimpleHardware

• Signature: public class SimpleHardware : Tuple<string, string, int, int>
• Behavior: A lightweight, immutable tuple-based representation of hardware configuration. Exposes SerialNumber, ParentDAS, DASId, and DASType via named properties derived from tuple items. Used for passing hardware metadata without database persistence.

TestSetupHelper

• Signature: public abstract class TestSetupHelper
• Behavior: A static helper class for managing test setup names by ID. Provides SetTestSetupName, GetTestSetupName, and ClearTestSetupNames methods. Maintains an internal dictionary mapping integer IDs to string names.

ExtraProperty

• Signature: [Serializable] public class ExtraProperty : IExtraProperty
• Behavior: A mutable, INotifyPropertyChanged-enabled class representing a key-value pair for extra properties. Supports two constructors: parameterized (key, value) and copy constructor from IExtraProperty. Includes PasteCommand and ItemStatus properties (ignored during JSON serialization via [ScriptIgnore]).

ROIPeriodChannelRecord

• Signature: public class ROIPeriodChannelRecord : BasePropertyChanged, IROIPeriodChannelRecord
• Behavior: Represents a record from the ROIPeriodChannels database table. Properties: TestSetupROIId, ChannelName, ChannelId. Constructor accepts IDataReader and storedProcedureVersionToUse; ChannelId is set to -1 if the DB version predates its introduction (Constants.ROIPERIODCHANNELS_CHANNELID_DB_VERSION).

TestSetupHardwareRecord

• Signature: public class TestSetupHardwareRecord : Base.BasePropertyChanged, ITestSetupHardwareRecord
• Behavior: Represents a record from the TestSetupHardware table. Properties: DASId, TestSetupId, AddDAS, SamplesPerSecond, IsClockMaster, PTPDomainId, AntiAliasFilterRate. Supports three constructors: default, IDataReader (with version-aware PTPDomainId parsing), and copy constructor from ITestSetupHardwareRecord.

TestSetupROIsRecord

• Signature: public class TestSetupROIsRecord : BasePropertyChanged, ITestSetupROIRecord
• Behavior: Represents a record from the TestSetupROIs table. Properties: TestSetupROIId, TestSetupId, Suffix, ROIStart, ROIEnd, IsEnabled, IsDefault. Constructor accepts IDataReader; note: TestSetupId is incorrectly assigned from "TestSetupROIId" column in constructor (see Gotchas).

CalculatedChannelRecord

• Signature: public class CalculatedChannelRecord : BasePropertyChanged, ICalculatedChannelRecord
• Behavior: Represents a calculated channel record. Properties include Name, TestSetupName, Id, Operation, CalculatedValueCode, InputChannelIds (string array), CFCForInputChannels, ChannelFilterClassForOutput, TestSetupId, ViewInRealtime, ClipLength. Supports default, copy (ICalculatedChannelRecord), and IDataReader constructors. Input channel IDs are parsed from CSV using CultureInfo.InvariantCulture.TextInfo.ListSeparator.

ISFFile

• Signature: public class ISFFile
• Behavior: Handles reading/writing ISF (Instrumentation Sensor Format) files. Contains fixed-length header fields (TestSetupName, NumberOfRecords, TestType, TestDivision, TCFile) and a list of IISFSensorRecord objects. Methods: AddRecord, WriteToFile, AddSensors. Header line parsing uses fixed offsets and padding with spaces.

GraphRecord

• Signature: public class GraphRecord : BasePropertyChanged, IGraphRecord
• Behavior: Represents a graph configuration record. Properties: GraphId, TestSetupId, GraphName, GraphDescription, ChannelsString, axis range flags (UseDomainMin, UseDomainMax, UseRangeMin, UseRangeMax) and their corresponding min/max values, ThresholdsString, LocalOnly (deprecated). Supports default, copy, and IDataReader constructors.

RegionOfInterest

• Signature: [Serializable] public class RegionOfInterest : IRegionOfInterest
• Behavior: A mutable, INotifyPropertyChanged-enabled class modeling a time-based ROI. Properties: Suffix, Start, End, IsEnabled, IsDefault, ChannelNames, ChannelIds. Includes validation to ensure Start < End. Notifies via RegionOfInterestChangedEvent (via Prism EventAggregator) on value changes, unless Deserializing is true. Provides utility methods for channel name formatting (GetAnalogChanName, GetChanName, RemoveParentDASName, RemoveAssignedByIDFromHardwareString) and silent assignment (SetChannelNamesNoNotify, SetChannelIdsNoNotify).

ISFSensorRecord

• Signature: public class ISFSensorRecord : IISFSensorRecord
• Behavior: Represents a single sensor record in an ISF file (comprising 4 fixed-length records of RECORD_LENGTH chars each). Exposes structured properties for sensor metadata (e.g., DataChannelNumber, Tag, SerialNumber, Sensitivity, Capacity, EngineeringUnits, C1, C2, C3, EID, CommentPart1/2/3, SensorType, TOMConfigurationName). Includes methods to set/get values and Write to BinaryWriter. Default constructor initializes TOMConfigurationName to "STANDARD".

Extension Methods (in ISFFile)

• Fill<T>(this T[] sourceArray, T with): Fills entire array with value.
• SubFill<T>(this T[] source, T with, int startIndex, int finalIndex): Fills from startIndex to finalIndex (exclusive), respecting array bounds.
• SetValues<T>(this T[] source, T[] with, int startIndex, int length, T pad): Copies with array into source starting at startIndex, padding remaining space with pad.
• GetValues<T>(this T[] source, int startIndex, int length): Returns a new array of length elements starting at startIndex.

3. Invariants

• SimpleHardware: Immutable after construction; tuple item mapping is fixed (Item1→SerialNumber, Item2→ParentDAS, Item3→DASId, Item4→DASType).
• TestSetupROIsRecord constructor: TestSetupId is incorrectly assigned from "TestSetupROIId" column (see Gotchas); no invariant violation is enforced by code.
• RegionOfInterest.Start and End: Start < End is enforced via setter logic (Start capped at End - 0.01, End capped at Start + 0.01). Infinity values are explicitly excluded from notifications (per comment referencing "FB 43462").
• ISFFile header fields: All fields are fixed-width and space-padded. NumberOfRecords is derived as 4 * number of sensor records.
• ISFSensorRecord: Each record consists of exactly 4 fixed-length char[] arrays (Record1–Record4), each of length ConstantsAndEnums.RECORD_LENGTH.
• CalculatedChannelRecord.InputChannelIds: Stored as a string array; parsed from CSV using ListSeparator (e.g., comma in invariant culture).
• GraphRecord axis flags: UseDomainMin/Max and UseRangeMin/Max flags control whether corresponding min/max values are applied.

4. Dependencies

Internal Dependencies

• DTS.Common.Base: Base classes (BasePropertyChanged) used by ROIPeriodChannelRecord, TestSetupROIsRecord, CalculatedChannelRecord, GraphRecord.
• DTS.Common.Interface.*: Interfaces implemented by record classes:
  • IROIPeriodChannelRecord, ITestSetupHardwareRecord, ITestSetupROIRecord, ICalculatedChannelRecord, IGraphRecord, IISFSensorRecord, IExtraProperty, IRegionOfInterest.
• DTS.Common.Enums: Operations enum used by CalculatedChannelRecord.
• DTS.Common.Interface.Sensors: ISensorData used by ISFSensorRecord.SetSensor.
• DTS.Common.Events.RegionOfInterest: RegionOfInterestChangedEvent used by RegionOfInterest.
• Prism.*: IEventAggregator, IContainerProvider, ContainerLocator used by RegionOfInterest.NotifyChanged.

External Dependencies

• System.Data: IDataReader for database record construction.
• System.ComponentModel: INotifyPropertyChanged via PropertyChangedEventHandler.
• System.Web.Script.Serialization: [ScriptIgnore] attribute.
• System.Linq: Used for array equality checks (SequenceEqual) and LINQ queries.
• System: Core types (string, char[], double, int, long, short, byte, bool, ICommand).

Inferred Usage

• Database: All record classes with IDataReader constructors imply usage with stored procedures (e.g., sp_ROIPeriodChannelsGet, sp_TestSetupROIsGet).
• ISF I/O: ISFFile and ISFSensorRecord are used for writing sensor data to ISF files.
• UI: ExtraProperty, RegionOfInterest, and record classes implement INotifyPropertyChanged, indicating use in data-bound UI layers (e.g., WPF).

5. Gotchas

• TestSetupROIsRecord constructor bug: TestSetupId = Utility.GetInt(reader, "TestSetupROIId"); incorrectly reads from "TestSetupROIId" instead of "TestSetupId". This will cause incorrect TestSetupId values when constructing from database reader.
• ISFSensorRecord.GetCapacity(), GetSensitivity(), etc.: Methods like CapacityCharacters.ToString() return the underlying char[]'s ToString() (i.e., type name), not the string content. Correct usage requires new string(char[]) or string.Concat(char[]). This is likely a bug.
• RegionOfInterest.Suffix validation: Enforces that non-empty suffixes must start with "_" and be otherwise whitespace-free. If input violates this, it is auto-corrected (e.g., "ROI1" → "_ROI1").
• RegionOfInterest.Deserializing flag: A static flag used to suppress change notifications during deserialization (e.g., to avoid triggering UI updates or event publishing during object construction). Requires careful coordination to avoid missed updates.
• ISFFile.NumberOfRecords semantics: SetNumberOfRecords sets NumberOfRecords to 4 * Records.Length, implying each sensor record occupies 4 "records" in the ISF file (consistent with ISFSensorRecord having 4 char[] fields).
• CalculatedChannelRecord.InputChannelIds copy constructor: Uses CopyTo on record.InputChannelIds into _inputChannelIds, but _inputChannelIds is initialized to new string[0] before the copy, causing ArgumentException if record.InputChannelIds.Length > 0. Should initialize _inputChannelIds to new string[record.InputChannelIds.Length] first.
• ISFSensorRecord.TOMConfigurationName: Default value "STANDARD" is hardcoded; other values are not supported per comments.
• RegionOfInterest.GetAnalogChanName logic: Distinguishes "TEST_SPECIFIC_ANALOG_SERIAL" and "VOLTAGE_INPUT" DAS types for special channel name parsing. Relies on SensorConstants values (not shown in source).
• TestSetupHelper.TestSetupNames: Static dictionary is shared across all usages; ClearTestSetupNames() affects all callers. No thread-safety is evident.