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

---
source_files:
  - Common/DTS.Common.Serialization/StringWriterWithEncoding.cs
  - Common/DTS.Common.Serialization/TickEventHandler.cs
  - Common/DTS.Common.Serialization/InvariantStreamWriter.cs
  - Common/DTS.Common.Serialization/BadCRCBypass.cs
  - Common/DTS.Common.Serialization/IProgressAware.cs
  - Common/DTS.Common.Serialization/ToyotaCsv.File.cs
  - Common/DTS.Common.Serialization/EventHandlers.cs
  - Common/DTS.Common.Serialization/Test.IConvertable.cs
  - Common/DTS.Common.Serialization/TestSetup.TestObject.Channel.cs
  - Common/DTS.Common.Serialization/Test.Module.IConvertable.cs
  - Common/DTS.Common.Serialization/Test.Module.Channel.IConvertable.cs
  - Common/DTS.Common.Serialization/TestSetup.TestObject.DASHardware.cs
  - Common/DTS.Common.Serialization/TestSetup.Sensor.cs
  - Common/DTS.Common.Serialization/File.Writer.cs
  - Common/DTS.Common.Serialization/IReadable.cs
  - Common/DTS.Common.Serialization/TestSetup.Graph.cs
  - Common/DTS.Common.Serialization/FilteredData.cs
  - Common/DTS.Common.Serialization/File.Writer.CharacterCountingStreamWriter.cs
  - Common/DTS.Common.Serialization/Diadem.File.cs
  - Common/DTS.Common.Serialization/TestSetup.TestObject.DASHardware.DASChannel.cs
  - Common/DTS.Common.Serialization/File.cs
  - Common/DTS.Common.Serialization/File.Reader.cs
  - Common/DTS.Common.Serialization/TestSetup.Graph.Channel.cs
  - Common/DTS.Common.Serialization/EventInfoAggregate.cs
  - Common/DTS.Common.Serialization/IWriteable.cs
generated_at: "2026-04-16T14:18:31.446837+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "2a2f1c17484ea7d0"
---

# DTS.Serialization Module Documentation

## 1. Purpose

The `DTS.Serialization` module provides a framework for serializing and deserializing test data to various file formats. It defines an abstract file hierarchy (`File`, `Reader<T>`, `Writer<T>`) with format-specific implementations (Toyota CSV, Diadem), a rich domain model for test data (`Test`, `Module`, `Channel`), and progress-aware serialization operations with event-based notification. The module supports extensibility through `IConvertable` interfaces that allow external objects to transform to/from the internal test representation.

---

## 2. Public Interface

### Core File Abstractions

#### `File` (abstract partial class)
- **Signature**: `public abstract partial class File : Exceptional`
- **Constructor**: `File(string formatName)`
- **Properties**:
  - `string FormatName` (read-only, set via constructor)
  - `int DefaultEncoding` (defaults to `Encoding.UTF8.CodePage`)
  - `static string BaseExportDirectory` (static getter/setter)
  - `static bool UseLegacyTDCSoftwareFiltering` (static getter/setter)
  - `Common.Enums.IsoViewMode ISOViewMode` (getter/setter)
- **Methods**:
  - `protected string EnsureTrailingBackslashOnPathString(string path)`
  - `virtual void SetEUData(string channelID, FilteredData fd)`
  - `virtual FilteredData GetEUData(string channelID)`
  - `virtual int GetChannelNumberFromChannelFileName(string channelFileName)` - returns -1 by default

#### `File.Reader<T>` (abstract nested class)
- **Signature**: `public abstract class Reader<T> : Exceptional, IReader where T : File`
- **Constructor**: `protected Reader(T fileType)`
- **Properties**:
  - `protected T FileType` (read-only)
  - `protected ChannelFilenameComparer ChFileCompare` (read-only)
- **Nested Class**: `ChannelFilenameComparer` (implements `IComparer<string>`)

#### `File.Writer<T>` (abstract partial nested class)
- **Signature**: `public abstract partial class Writer<T> : Exceptional, IWriter where T : File`
- **Constructor**: `public Writer(T fileType, int encoding)`
- **Properties**:
  - `protected T FileType` (read-only)
  - `virtual int DefaultEncoding` (getter/setter, defaults to UTF8 codepage)
- **Nested Class**: `CharacterCountingStreamWriter` (extends `StreamWriter`, counts characters via `WriteLine`)

### Interfaces

#### `IReadable` / `IReadable<T>`
- **Signature**: `public interface IReadable` (marker interface)
- **Signature**: `public interface IReadable<T> : IReadable`
- **Property**: `IReader<T> Importer { get; }`

#### `IReader` / `IReader<T>`
- **Signature**: `public interface IReader` (marker interface)
- **Signature**: `public interface IReader<T> : IReader`
- **Method**: `void Read(string pathname, out T target)`

#### `IWritable` / `IWritable<T>`
- **Signature**: `public interface IWritable` (marker interface)
- **Signature**: `public interface IWritable<T> : IWritable`
- **Property**: `IWriter<T> Exporter { get; }`

#### `IWriter` / `IWriter<T>`
- **Signature**: `public interface IWriter` (marker interface)
- **Signature**: `public interface IWriter<T> : IWriter`
- **Methods**:
  - `void Write(string pathname, string id, T target, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)`
  - `void Write(string pathname, string id, string dataFolder, T target, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler onBeginEvent, CancelEventHandler onCancelEvent, EndEventHandler onEndEvent, TickEventHandler onTickEvent, ErrorEventHandler onErrorEvent, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)`
  - `void Initialize(string pathname, string id, string dataFolder, T target, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler onBeginEvent, CancelEventHandler onCancelEvent, EndEventHandler onEndEvent, TickEventHandler onTickEvent, ErrorEventHandler onErrorEvent, CancelRequested cancelRequested)`

#### `IProgressAware`
- **Signature**: `interface IProgressAware`
- **Events**: `OnBegin` (BeginEventHandler), `OnEnd` (EndEventHandler), `OnTick` (TickEventHandler), `OnCancel` (CancelEventHandler), `OnError` (ErrorEventHandler)

### Event Delegates

- `delegate void TickEventHandler(object sender, double percentageComplete)`
- `delegate void BeginEventHandler(object sender, uint numberOfTicks)`
- `delegate void EndEventHandler(object sender)`
- `delegate void CancelEventHandler(object sender)`
- `delegate void ErrorEventHandler(object sender, Exception ex)`
- `delegate bool CancelRequested()`

### Convertable Interfaces

#### `Test.IConvertable` (nested interface)
- **Methods**:
  - `Test ToDtsSerializationTest()`
  - `void FromDtsSerializationTest(Test test, ReportErrors reportErrors)`
- **Delegate**: `delegate void ReportErrors(List<string> errors)`

#### `Test.Module.IConvertable` (nested interface)
- **Methods**:
  - `Test.Module ToDtsSerializationTestModule(DTS.Serialization.Test parentTest)`
  - `void FromDtsSerializationTestModule(Test.Module testModule, DTS.Serialization.Test.ReportErrors reportErrors)`

#### `Test.Module.Channel.IConvertable` (nested interface)
- **Methods**:
  - `Test.Module.Channel ToDtsSerializationTestModuleChannel()`
  - `void FromDtsSerializationTestModuleChannel(Test.Module.Channel channel)`

### Data Classes

#### `FilteredData`
- **Signature**: `public class FilteredData : Exceptional, IComparable<FilteredData>`
- **Constructor**: `FilteredData(string filterDescription, double filterFrequencyHz, double[] data, int absoluteDisplayOrder)`
- **Properties**: `string FilterDescription`, `double FilterFrequencyHz`, `double[] Data`, `int AbsoluteDisplayOrder` (read-only)
- **Method**: `int CompareTo(FilteredData other)`

#### `EventInfoAggregate`
- **Signature**: `public class EventInfoAggregate`
- **Constructor**: `EventInfoAggregate(DownloadReport.EventInfo newEvent)`
- **Properties**: `EventId`, `EventDescription`, `DurationSeconds`, `GUID`, `HasBeenDownloaded`, `WasTriggered`, `NumberOfChannels`, `NumberOfSamples` (UInt64), `NumberOfBytes` (UInt64), `Faulted`, `EventNumber`
- **Methods**: `Slice.Control.Event GetEvent()`, `Slice.Control.Event GetEvent(bool bClear)`, `int GetEventIndex(IDASCommunication idas)`, `List<IDASCommunication> GetDasList()`, `void Add(DownloadReport.EventInfo newEvent)`

### TestSetup Hierarchy

#### `TestSetup` (partial class)
- **Signature**: `public partial class TestSetup : Exceptional`

#### `TestSetup.TestObject` (partial nested class)
- **Signature**: `public partial class TestObject : Exceptional`

#### `TestSetup.TestObject.TOChannel`
- **Constructor**: Default constructor initializes `Version` to "1.0.0.0"
- **Properties**: `Name`, `SensorName`, `Version`

#### `TestSetup.TestObject.DASHardware`
- **Constructor**: Default constructor initializes `Version` to "1.0.0.0", `DASChannels` to empty list
- **Properties**: `List<DASChannel> DASChannels`, `SampleRate`, `SerialNumber`, `Version`

#### `TestSetup.TestObject.DASHardware.DASChannel`
- **Constructor**: Default constructor initializes `Version` to "1.0.0.0"
- **Properties**: `Location`, `MeasurementUnits`, `Name`, `NumberOfSamples`, `SensorName`, `SerialNumber`, `Version`

#### `TestSetup.Sensor`
- **Constructor**: Default constructor initializes `Version` to "1.0.0.0"
- **Properties**: `FilterClass`, `Name`, `Polarity`, `Position`, `Range`, `Version`

#### `TestSetup.Graph`
- **Constructor**: Initializes `Version` to "1.0.0.0", creates new `Guid` for `Identifier`
- **Properties**: `List<Channel> Channels`, `Name`, `HardwareChannelName`, `DisplayName` (computed as `Name_HardwareChannelName`), `Version`, `Guid Identifier` (read-only)
- **XML-ignored Properties**: `IsSingleChannelGraph`, `FirstChannel`, `FirstTestChannel`
- **Method**: `void UnSet()`

#### `TestSetup.Graph.Channel`
- **Constructors**: 
  - `Channel(DTS.Serialization.Test.Module.Channel channel)`
  - `Channel(string channelId)`
  - Private default constructor
- **Properties**: `ChannelId`, `ChannelGroupName`, `Name` (computed), `SensorName` (XML-ignored), `AxisUnit` (XML-ignored), `SerialNumber` (XML-ignored)
- **Fields**: `ParentTestModule` (XML-ignored), `TestChannel` (XML-ignored)

### Format-Specific Implementations

#### `ToyotaCsv.File`
- **Signature**: `public partial class File : Serialization.File, IWritable<Test>`
- **Constructor**: `File()` - passes "Toyota CSV" to base
- **Static Property**: `string Extension => ".csv"`
- **Property**: `IWriter<Test> Exporter` (lazy-initialized)

#### `Diadem.File`
- **Signature**: `public partial class File : Serialization.File, IWritable<Test>`
- **Constructor**: `File(bool bUseEVG20, TestPlan plan)`
- **Static Property**: `string Extension => ".dat"`
- **Properties**: `UseIsoCodeForDiadem200`, `UseZeroForUnfiltered`, `ChannelName200Option`, `UserComment201Option`, `Reserved1_301Option`, `Reserved2_302Option`, `IWriter<Test> Exporter`
- **Enums**: `DiademOptions` (NONE, ISO_CODE, SENSOR_SERIAL_NUMBER, CHANNEL_NAME), `DiademOptionsReserved1` (NONE, AAF_RATE, GROUP_NAME), `DiademOptionsReserved2` (NONE, CHANNEL_SENSITIVITY)

### Utility Classes

#### `StringWriterWithEncoding`
- **Signature**: `public sealed class StringWriterWithEncoding : StringWriter`
- **Constructor**: `StringWriterWithEncoding(Encoding encoding)`
- **Property**: `override Encoding Encoding` (returns encoding passed to constructor)

#### `InvariantStreamWriter`
- **Signature**: `public class InvariantStreamWriter : System.IO.StreamWriter`
- **Constructors**: `InvariantStreamWriter(string path)`, `InvariantStreamWriter(string path, bool bAppend)`
- **Property**: `override IFormatProvider FormatProvider` (returns `CultureInfo.InvariantCulture`)

#### `BadCRCBypass` (Windows Forms)
- **Signature**: `public partial class BadCRCBypass : Form`
- **Constructor**: `BadCRCBypass()`
- **Properties**: `string FileName`, `bool RememberChoice`
- **Event Handlers**: `btnOK_Click`, `btnCancel_Click`

---

## 3. Invariants

1. **Writer Construction**: `File.Writer<T>` instances must be created through factory methods in the hosting `File` object (constructor is public but intended for factory use).

2. **Reader Construction**: `File.Reader<T>` constructor is `protected`, enforcing that readers must be created by the hosting `File` class.

3. **Encoding Defaults**: All writers default to UTF-8 encoding (`Encoding.UTF8.CodePage`) unless explicitly overridden.

4. **Version Defaults**: All `TestSetup` nested classes initialize `Version` property to "1.0.0.0" by default.

5. **Graph Identifier**: `TestSetup.Graph.Identifier` is assigned a new `Guid` on construction and has a private setter (immutable after creation).

6. **ChannelFilenameComparer**: Requires the file type to be castable to `File` base class; otherwise comparison falls back to string comparison.

7. **EventInfoAggregate Consistency**: When aggregating events via `Add()`, if properties don't match (TestID, Description, Duration, GUID), warnings are logged and minimum values are used for numeric fields.

8. **FilteredData Display Order**: `AbsoluteDisplayOrder` is read-only after construction and defaults to -1.

---

## 4. Dependencies

### External Dependencies (from imports)
- `System.Text` / `System.Text.Encoding` - String encoding
- `System.IO` - Stream/StreamWriter/StringWriter base classes
- `System` - Basic types, Exception, IFormatProvider
- `System.Globalization.CultureInfo` - Invariant culture for formatting
- `System.Windows.Forms` - UI components (BadCRCBypass)
- `System.Xml.Serialization.XmlIgnoreAttribute` - XML serialization control
- `System.Collections.Generic` - List, Dictionary, IComparer