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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-17T15:38:58.339536+00:00	zai-org/GLM-5-FP8	1	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

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.