--- 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` 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` 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 Graphs`** List of multi-channel graphs defined in the test. Default: new empty list. - **`List Sensors`** List of sensors used in the test. Default: new empty list. - **`List ExtraProperties`** List of arbitrary key-value metadata pairs. Default: new empty list. - **`List TestObjects`** List of test objects involved. *(Note: `TestObject` type not defined in provided sources.)* Default: new empty list. - **`List Channels`** Placeholder for all graph channels (XML-ignored). Initialized as empty list. - **`List SingleChannelGraphs`** Placeholder for single-channel graphs (XML-ignored). Initialized as empty list. - **`IDictionary 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` 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.IsValueInitialized` is `false`, otherwise return the stored value. --- ## 4. Dependencies ### Internal Dependencies (from source): - `DTS.Common.Utilities` — Provides base types (`Exceptional`, `Property`). - `DTS.Common.Utilities.DotNetProgrammingConstructs` — Contains `Property` implementation. - `DTS.Common.Enums.Sensors` — Defines `CalibrationBehaviors` enum (used in `TestSetup.CalibrationBehavior`). - `System.Collections.Generic` — For `List` and `IDictionary`. - `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`**: 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()` 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.*