DP44/enriched-qwen3-coder-next/Common/DTS.Common.Serialization/TestSetup.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Serialization/TestSetup/ExtraProperty.cs Common/DTS.Common.Serialization/TestSetup/Sensor.cs Common/DTS.Common.Serialization/TestSetup/TestSetup.cs	2026-04-16T03:38:27.625300+00:00	Qwen/Qwen3-Coder-Next-FP8	1	94471ae1594e14ef

Documentation: DTS.Serialization.TestSetup Module

---

1. Purpose

This module defines core data structures used to serialize and deserialize test setup configurations in the DTS (Dynamic Test System) platform. It provides strongly-typed, property-backed classes (TestSetup, Sensor, ExtraProperty) that model metadata about a test run—including laboratory and customer information, test parameters, associated sensors, graphs, and upload settings. These classes are designed to support XML serialization (evidenced by [Serializable] and [XmlIgnore] attributes) and are part of a larger serialization framework leveraging DTS.Common.Utilities.DotNetProgrammingConstructs.Property<T> for change tracking and metadata management. The module serves as the foundational schema for persisting and restoring test configurations across sessions.

---

2. Public Interface

All classes reside in the DTS.Serialization namespace and inherit from Exceptional.

TestSetup (partial class, [Serializable])

• TestSetup()
  Default constructor. Initializes all backing Property<T> fields to default values (e.g., null for strings, 0 for Int32, CalibrationBehaviors.NonLinearIfAvailable, empty lists, "2.0.0.0" for Version, false for Upload/UploadExportsOnly, "" for UploadFolder).
  Note: Several fields are initialized redundantly (e.g., _dateOfTheTest is assigned null twice), but this is harmless.

• bool Upload
  Indicates whether the test setup was configured to upload when run. Default: false.

• string UploadFolder
  Stores the simple upload folder value set in the UI. May be overridden by an INI file at runtime. Default: "".

• bool UploadExportsOnly
  Indicates whether only exported files should be uploaded. Default: false.

• string ISFFile
  Stores the path or name of the ISF (Instrument Setup File) associated with the test. Default: "".

• string DateOfTheTest
  Date of the test as a string. Default: null.

• string Description
  Free-text description of the test. Default: null.

• CalibrationBehaviors CalibrationBehavior
  Calibration behavior setting. Default: CalibrationBehaviors.NonLinearIfAvailable.

• string ExportFolder
  Folder path for exported data. Default: null.

• int ExportTypes
  Bitmask or enum value indicating export formats. Default: 0.

• List<Graph> Graphs
  List of multi-channel graphs defined in the test. Default: new empty list.

• List<Sensor> Sensors
  List of sensors used in the test. Default: new empty list.

• List<ExtraProperty> ExtraProperties
  List of arbitrary key-value metadata pairs. Default: new empty list.

• List<TestObject> TestObjects
  List of test objects involved. (Note: TestObject type not defined in provided sources.)
  Default: new empty list.

• List<Graph.Channel> Channels
  Placeholder for all graph channels (XML-ignored). Initialized as empty list.

• List<Graph> SingleChannelGraphs
  Placeholder for single-channel graphs (XML-ignored). Initialized as empty list.

• IDictionary<Guid, Graph> SortedGraphs
  Sorted dictionary of graphs (XML-ignored), populated by SortGraphs().

• void SortGraphs()
  Clears SortedGraphs, then populates it with entries from Graphs (multi-channel) in order, followed by entries from SingleChannelGraphs sorted by AbsoluteDisplayOrder of their first channel.

• string LabName, LaboratoryName, LaboratoryContactName, LaboratoryContactPhone, LaboratoryContactFax, LaboratoryContactEmail, LaboratoryTestReferenceNumber, LaboratoryProjectReferenceNumber
  Laboratory-related metadata fields. Most default to null.
  LaboratoryProjectReferenceNumber has a custom getter: returns "" if _laboratoryProjectReferenceNumber.IsValueInitialized is false, otherwise returns the value.

• string CustName, CustomerName, CustomerTestReferenceNumber, CustomerProjectReferenceNumber, CustomerOrderNumber, CustomerCostUnit
  Customer-related metadata fields. All default to null.

• string TEName, TestEngineerName, TestEngineerPhone, TestEngineerFax, TestEngineerEmail
  Test engineer contact fields.
  TEName has a custom getter: returns "" if _teName.IsValueInitialized is false, otherwise returns the value.

• string Name
  Name of the test setup. Default: null.

• string NumberOfTestObjects, NumberOfMedia
  String representations of counts. Default: null.

• string ReferenceTemperature, Regulation, RelativeAirHumidity, Subtype, TestComment, TypeOfTheTest, Timestamp
  Various test parameters. All default to null.

• virtual string Version
  Version of the TestSetup schema. Default: "2.0.0.0" (set in constructor). Overridable in derived classes.

---

TestSetup.Sensor (nested partial class)

• Sensor()
  Default constructor. Initializes all string properties to null, except Version, which is set to "1.0.0.0".

• string FilterClass
  Filter class name. Default: null.

• string Name
  Sensor name. Default: null.

• string Polarity
  Polarity setting (e.g., “Positive”, “Negative”). Default: null.

• string Position
  Physical or logical position of the sensor. Default: null.

• string Range
  Measurement range of the sensor. Default: null.

• string Version
  Schema version for this sensor definition. Default: "1.0.0.0".

---

TestSetup.ExtraProperty (nested partial class)

• ExtraProperty()
  Default constructor. Sets Key and Value to null, Version to "1.0.0.0".

• ExtraProperty(string key, string value)
  Constructor that initializes Key and Value to the provided arguments.

• string Key
  Key/name of the extra property. Default: null.

• string Value
  Value of the extra property. Default: null.

• string Version
  Schema version for this property. Default: "1.0.0.0".

---

3. Invariants

• All Property<T> fields are initialized with a unique metadata key (e.g., typeof(TestSetup).Namespace + ".TestSetup.Upload") and default value.
• The Version property of TestSetup is initialized to "2.0.0.0" in the constructor and is marked virtual, implying extensibility.
• The Version properties of Sensor and ExtraProperty are initialized to "1.0.0.0".
• UploadFolder and ISFFile default to "" (empty string), not null.
• ExportTypes defaults to 0 (i.e., no export formats selected).
• CalibrationBehavior defaults to CalibrationBehaviors.NonLinearIfAvailable.
• Graphs, Sensors, ExtraProperties, and TestObjects default to new empty lists (not null).
• Channels, SingleChannelGraphs, and SortedGraphs are XML-ignored and used only at runtime.
• SortGraphs() enforces ordering: multi-channel Graphs first (in original list order), then SingleChannelGraphs sorted by AbsoluteDisplayOrder of their first channel.
• TEName and LaboratoryProjectReferenceNumber have non-standard getters: they return "" if the underlying Property<T>.IsValueInitialized is false, otherwise return the stored value.

---

4. Dependencies

Internal Dependencies (from source):

• DTS.Common.Utilities — Provides base types (Exceptional, Property<T>).
• DTS.Common.Utilities.DotNetProgrammingConstructs — Contains Property<T> implementation.
• DTS.Common.Enums.Sensors — Defines CalibrationBehaviors enum (used in TestSetup.CalibrationBehavior).
• System.Collections.Generic — For List<T> and IDictionary<TKey, TValue>.
• System.Xml.Serialization — Used for [Serializable] and [XmlIgnore] attributes.

External Dependencies (inferred):

• Graph class — Referenced in TestSetup.Graphs, SingleChannelGraphs, Channels, and SortedGraphs. Not defined in provided sources, but its nested Channel class and Identifier and FirstTestChannel properties are used.
• TestObject class — Referenced in TestSetup.TestObjects. Not defined in provided sources.
• GraphDisplayOrderComparer — A private method in TestSetup that compares Graph instances by AbsoluteDisplayOrder of their first channel.

---

5. Gotchas

• Redundant field initialization: In TestSetup(), _dateOfTheTest.Value = null appears twice. Likely a copy-paste artifact, but harmless.
• Inconsistent null vs. empty string defaults:
  • UploadFolder, ISFFile → ""
  • ExportFolder, DateOfTheTest, Description, etc. → null
    This may cause confusion when checking for presence (e.g., string.IsNullOrEmpty() vs. null checks).
• Non-standard getters for optional fields:
  TEName and LaboratoryProjectReferenceNumber return "" when uninitialized, while other string properties return null. This breaks consistency and may lead to bugs if consumers assume uniform nullability.
• IsValueInitialized usage is undocumented in Property<T>:
  The behavior of IsValueInitialized is not defined in the source; its semantics (e.g., whether it tracks explicit null assignments) are unknown.
• Version is virtual in TestSetup but not in nested classes:
  Sensor.Version and ExtraProperty.Version are not virtual, suggesting they are not intended for override, while TestSetup.Version is. This may indicate a versioning strategy where only top-level objects evolve schema.
• ExtraProperties and Sensors lists are mutable but not defensively copied:
  Setting TestSetup.Sensors = null or TestSetup.Sensors = new List<Sensor>() is allowed, but no validation prevents null or duplicate entries.
• SortGraphs() mutates SortedGraphs but does not validate inputs:
  If Graph.Identifier is not unique, SortedGraphs.Add() will throw an ArgumentException.
• GraphDisplayOrderComparer may throw NullReferenceException:
  If a.FirstTestChannel or b.FirstTestChannel is null, the comparison will fail. No null checks are present.
• [Serializable] on TestSetup but no ISerializable implementation:
  Relies on default .NET serialization; may break across assembly version changes if field names or types change.

---

Documentation generated from provided source files. No external assumptions or behaviors were inferred beyond what is strictly observable.