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

---
source_files:
  - Common/DTS.Common.Serialization/TestSetup/ExtraProperty.cs
  - Common/DTS.Common.Serialization/TestSetup/Sensor.cs
  - Common/DTS.Common.Serialization/TestSetup/TestSetup.cs
generated_at: "2026-04-16T03:38:27.625300+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "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.*