250 lines
13 KiB
Markdown
250 lines
13 KiB
Markdown
---
|
|
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
|