DP44/docs/ai/Common/DTS.Common.Serialization/Test.md

---
source_files:
  - Common/DTS.Common.Serialization/Test/IConvertable.cs
  - Common/DTS.Common.Serialization/Test/IntervalSec.cs
  - Common/DTS.Common.Serialization/Test/DasTimestamp.cs
  - Common/DTS.Common.Serialization/Test/Test.cs
generated_at: "2026-04-17T15:38:58.339536+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "c3111610a62a3486"
---

# DTS.Serialization.Test Module Documentation

## 1. Purpose

This module provides the core serialization framework for test data within the DTS (Diversified Technical Systems) system. The primary `Test` class serves as a serializable container for test metadata, data acquisition modules, channel configurations, and DAS timestamp information. It implements `IXmlSerializable` for custom XML serialization/deserialization and defines nested types for time intervals (`IntervalSec`) and DAS timestamps (`DasTimestamp`), as well as an `IConvertable` interface for bi-directional conversion between domain objects and `Test` instances.

---

## 2. Public Interface

### Test Class
**Namespace:** `DTS.Serialization`

**Constructors:**
- `Test()` — Parameterless constructor; initializes channel order lookup.
- `Test(string dtsfile)` — Constructor accepting a DTS file path (implementation body is empty in source).
- `Test(string id, string description)` — Initializes with ID and description; delegates to `Test(string, string, int)` with eventNumber=0.
- `Test(string id, string description, int eventNumber)` — Full constructor initializing Id, Description, and EventNumber.

**Properties:**
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Software` | `string` | `"DataPRO"` | Software name associated with this test. |
| `SoftwareVersion` | `string` | `""` | Software version string. |
| `Id` | `string` | `""` | Test identifier. |
| `Description` | `string` | `""` | Test description. |
| `EventNumber` | `int` | `0` | Event number for this test. |
| `Guid` | `Guid` | Empty GUID | Globally unique identifier. |
| `FaultFlags` | `ushort` | `0` | Fault flags bitmask. |
| `ExtendedFaultFlags1` | `uint` | `0` | Extended fault flags (bank 1). |
| `ExtendedFaultFlags2` | `uint` | `0` | Extended fault flags (bank 2). |
| `ExtendedFaultFlags3` | `uint` | `0` | Extended fault flags (bank 3). |
| `ExtendedFaultFlags4` | `uint` | `0` | Extended fault flags (bank 4). |
| `InlineSerializedData` | `bool` | `false` | Controls inline serialization; propagates to all modules when set. |
| `Modules` | `List<Module>` | Empty list | Collection of modules in this test. |
| `DasTimestamps` | `List<DasTimestamp>` | Empty list | Collection of DAS timestamps. |
| `Channels` | `List<Module.Channel>` | Computed | Aggregated, sorted list of all channels from all modules. |
| `InceptionDate` | `DateTime` | `DateTime.Now` | Creation timestamp of serialization. |

**Methods:**
- `void ClearExtendedFaultFlags()` — Sets all four extended fault flag properties to 0.
- `void TryGetChannelOrder()` — Reads `ChannelOrder.txt` from current directory to establish custom channel ordering.
- `void WriteXml(XmlWriter writer)` — Serializes this object to XML.
- `void ReadXml(XmlReader reader)` — Deserializes this object from XML.
- `XmlSchema GetSchema()` — Returns `null` (required by `IXmlSerializable`).
- `override bool Equals(object obj)` — Compares Id, Description, and Modules for equality.
- `override int GetHashCode()` — Returns `base.GetHashCode()`.
- `void SaveTest(string directory, string testId, int defaultEncoding, bool includeGroupNameInISOExport)` — Saves test to .dts file with backup handling.

**Nested Types:**
- `ChannelOrderComparor : IComparer<Module.Channel>` — Comparer for channel ordering based on external file.

---

### Test.IConvertable Interface
**Namespace:** `DTS.Serialization`

```csharp
public delegate void ReportErrors(List<string> errors);

public interface IConvertable
{
    Test ToDtsSerializationTest();
    void FromDtsSerializationTest(Test test, ReportErrors reportErrors);
}
```

- `Test ToDtsSerializationTest()` — Converts implementing object to a `Test` instance.
- `void FromDtsSerializationTest(Test test, ReportErrors reportErrors)` — Initializes implementing object from a `Test` instance; errors reported via callback.

---

### Test.IntervalSec Class
**Namespace:** `DTS.Serialization`  
**Base Class:** `Exceptional`

**Constructors:**
- `IntervalSec()` — Parameterless; Begin and End remain at default (0).
- `IntervalSec(double begin, double end)` — Initializes with specified begin and end times.

**Properties:**
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Begin` | `double` | `0` | Interval begin time in seconds. |
| `End` | `double` | `0` | Interval end time in seconds. |
| `DoRoundOffValues` | `bool` | `false` | Controls automatic rounding of Begin/End on get. |
| `NumberRoundingDecimalPlaces` | `int` | `6` | Decimal places for rounding when enabled. |

**Methods:**
- `override bool Equals(object obj)` — Compares Begin and End values.
- `override int GetHashCode()` — Returns `base.GetHashCode()`.

---

### Test.DasTimestamp Class
**Namespace:** `DTS.Serialization`  
**Base Class:** `Exceptional`  
**Attribute:** `[XmlSerializationTag("DasTimestamp")]`

**Constructor:**
- `DasTimestamp(Test parentTest)` — Requires parent `Test` reference.

**Properties:**
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ParentTest` | `Test` | `null` | Reference to containing Test object. |
| `BaseSerialNumber` | `string` | `""` | DAS base serial number. |
| `NumberOfSamples` | `UInt64` | `0` | Sample count. |
| `NumberOfBitsPerSample` | `UInt32` | `0` | Bits per sample timestamp. |
| `FileName` | `string` | `""` | Name of corresponding .bin file. |

**Methods:**
- `void WriteXml(XmlWriter writer)` — Writes XML; only serializes `BaseSerialNumber` and `NumberOfSamples`.
- `void ReadXml(XmlReader reader)` — Reads XML; sets `NumberOfBitsPerSample` to `8 * sizeof(ulong)` (64) if not present.
- `XmlSchema GetSchema()` — Returns `null`.
- `override bool Equals(object obj)` — Compares FileName, NumberOfSamples, NumberOfBitsPerSample, and BaseSerialNumber.
- `override int GetHashCode()` — Returns `base.GetHashCode()`.

---

## 3. Invariants

- **IntervalSec**: When `DoRoundOffValues` is `true`, the getter returns rounded values but the underlying stored value is unrounded.
- **DasTimestamp**: `NumberOfBitsPerSample` defaults to 64 (`8 * sizeof(ulong)`) when not present in XML.
- **Test.Guid**: Always initialized; defaults to `00000000-0000-0000-0000-000000000000` if parsing fails.
- **Test.Channels**: Always returns a sorted list; sorting is by `AbsoluteDisplayOrder`, then `ParentModule.Number`, then `Channel.Number`, with optional external ordering from `ChannelOrder.txt`.
- **Test.InlineSerializedData**: Setting this property propagates the value to all modules in `Modules`.
- **XML Serialization**: All properties marked with `[XmlSerializationTag]` are candidates for serialization, but `DasTimestamp.WriteXml` does not serialize all tagged properties.

---

## 4. Dependencies

**This module depends on:**
- `System`, `System.Collections.Generic`, `System.IO`, `System.Text`
- `System.Xml`, `System.Xml.Schema`, `System.Xml.Serialization`
- `DTS.Common.Utilities` — Provides `Exceptional` base class
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — Provides `Property<T>`
- `DTS.Common.Utilities.Logging` — Provides `APILogger`
- `DTS.Common.Utilities.Xml` — Provides `XmlSerializationTagAttribute`, `AttributeExtractor<T>`

**Consumers of this module:**
- Not determinable from the provided source files alone.

---

## 5. Gotchas

1. **Empty Constructor**: `Test(string dtsfile)` has an empty body — it does not load the file despite the parameter name suggesting it should.

2. **Incomplete XML Serialization in DasTimestamp**: `WriteXml` only writes `BaseSerialNumber` and `NumberOfSamples`, but `ReadXml` attempts to read `NumberOfBitsPerSample` and `FileName` is never serialized. The source contains a TODO-style comment acknowledging this should use reflection for automatic property handling.

3. **GetHashCode Implementations**: Both `IntervalSec` and `DasTimestamp` override `Equals` for value-based comparison but `GetHashCode` returns `base.GetHashCode()`, which violates the .NET guideline that equal objects must have equal hash codes.

4. **ChannelOrder.txt Side Effect**: `Test.Channels` getter and constructors call `TryGetChannelOrder()`, which reads a file named `ChannelOrder.txt` from the current working directory. This creates an implicit dependency on the execution environment.

5. **Backup File Handling in SaveTest**: The backup file (`.dts.bak`) is only deleted if it was created during the current save operation; pre-existing backups are preserved.

6. **Fault Flags Not Serialized**: `FaultFlags` and `ExtendedFaultFlags1-4` are written to XML but not all are read back with the same robustness — `ExtendedFaultFlags` use `GetUintSafe` with defaults, while `FaultFlags` uses a try/catch with silent default to 0.

7. **IntervalSec Parameterless Constructor**: The comment states Begin and End are left "uninitialized", but they are actually initialized to 0 via the `Property<double>` default.