--- 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`, `Writer`) 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` (abstract nested class) - **Signature**: `public abstract class Reader : 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`) #### `File.Writer` (abstract partial nested class) - **Signature**: `public abstract partial class Writer : 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` - **Signature**: `public interface IReadable` (marker interface) - **Signature**: `public interface IReadable : IReadable` - **Property**: `IReader Importer { get; }` #### `IReader` / `IReader` - **Signature**: `public interface IReader` (marker interface) - **Signature**: `public interface IReader : IReader` - **Method**: `void Read(string pathname, out T target)` #### `IWritable` / `IWritable` - **Signature**: `public interface IWritable` (marker interface) - **Signature**: `public interface IWritable : IWritable` - **Property**: `IWriter Exporter { get; }` #### `IWriter` / `IWriter` - **Signature**: `public interface IWriter` (marker interface) - **Signature**: `public interface IWriter : 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 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` - **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 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 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 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` - **Constructor**: `File()` - passes "Toyota CSV" to base - **Static Property**: `string Extension => ".csv"` - **Property**: `IWriter Exporter` (lazy-initialized) #### `Diadem.File` - **Signature**: `public partial class File : Serialization.File, IWritable` - **Constructor**: `File(bool bUseEVG20, TestPlan plan)` - **Static Property**: `string Extension => ".dat"` - **Properties**: `UseIsoCodeForDiadem200`, `UseZeroForUnfiltered`, `ChannelName200Option`, `UserComment201Option`, `Reserved1_301Option`, `Reserved2_302Option`, `IWriter 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` 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` 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