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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Serialization/XLSX/Excel.File.cs Common/DTS.Common.Serialization/XLSX/Excel.File.Writer.cs	2026-04-17T15:42:08.979045+00:00	zai-org/GLM-5-FP8	1	ab2a2a0d3558d3b8

Documentation: DTS.Serialization.XLSX

1. Purpose

This module provides XLSX (Excel) export functionality for test data within the DTS serialization framework. It implements the Serialization.File abstract base class and IWriter<Test> interface to export Test objects—specifically analog input channel data—to Excel spreadsheets. The module supports exporting data in multiple representations (ADC, EU, mV) and can apply SAE J211 filtering to channel data during export.

2. Public Interface

File Class (partial)

Namespace: DTS.Serialization.XLSX
Inheritance: Serialization.File, IWritable<Test>

Constructor

public File()

Constructs a new XLSX file instance, passing "XLSX" to the base class.

Properties

public IWriter<Test> Exporter { get; }

Returns the writer instance for this file type. Lazily instantiates a Writer on first access. Throws Exception with message "encountered problem getting exporter" on failure.

public bool ExportADC { set; }
public bool ExportEU { set; }
public bool ExportMV { set; }

Set-only properties that control which data representation to export. Each delegates to the corresponding property on the underlying Writer instance (accessed via Exporter).

---

File.Writer Class (nested)

Inheritance: Writer<File>, IWriter<Test>

Properties

internal File WriterParent { get; private set; }

The owning File instance that created this writer.

public bool ExportADC { get; set; }
public bool ExportEU { get; set; }
public bool ExportMv { get; set; }

Control which data representation to include in the export. Default values: ExportADC = false, ExportEU = true, ExportMv = false.

public double Start { get; set; }
public double Stop { get; set; }

Time bounds for the export (in seconds).

public bool Filtered { get; set; }

Controls whether channel data should be filtered using SAE J211 filtering during export.

Methods

public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)

Empty implementation - does nothing.

public void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)

Primary export method. Writes test data to an XLSX file at pathname. Uses a template file XLSXExportTemplate.xlsx from ReportTemplates directory. Writes metadata (inception date, test ID, description), channel configuration, and sample data. Supports progress reporting via tickEventHandler and error handling via errorEventHandler.

public void Initialize(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested)

Empty implementation - does nothing.

Protected/Internal Methods

protected Cell GetCell(Worksheet worksheet, string xColumn, UInt32 rowIndex, bool bLookForCell = true)

Retrieves or creates a cell at the specified column and row.

protected WorksheetPart GetWorksheetPartByName(SpreadsheetDocument document, string sheetName)

Retrieves a worksheet part by name. Returns null if not found.

protected int InsertSharedStringItem(string text, SharedStringTablePart shareStringPart)

Inserts text into the shared string table and returns its index. Handles null text by converting to empty string.

3. Invariants

• The Exporter property always returns the same Writer instance after first access (lazy singleton pattern).
• The Writer constructor sets default export flags: ExportEU = true, ExportADC = false, ExportMv = false.
• The template file XLSXExportTemplate.xlsx must exist in ReportTemplates subdirectory of the application base directory.
• The Data worksheet must exist in the template file.
• Row indices for sample data start at row 24 (hardcoded as 24 + sampleIndex).
• Column indexing starts at column B (index 0 maps to column B via GetColumn).
• Progress updates occur every UPDATE_INTERVAL (1000) samples.

4. Dependencies

External Dependencies (from imports)

• DocumentFormat.OpenXml - Open XML SDK for Excel file manipulation
• DocumentFormat.OpenXml.Packaging - Spreadsheet document handling
• DocumentFormat.OpenXml.Spreadsheet - Spreadsheet-specific elements
• DTS.Common.Utilities.Logging - APILogger for error logging
• DTS.Slice.Control - Event delegates (BeginEventHandler, CancelEventHandler, EndEventHandler, TickEventHandler, ErrorEventHandler, CancelRequested)

Internal Dependencies (inferred)

• DTS.Serialization - Base class Serialization.File and Writer<T> base class
• Common.DAS.Concepts - Test, Test.Module.AnalogInputChannel, Test.Module.Channel, DataScaler, FilteredData
• Event.Module.Channel.SaeJ211Filter - Filter parsing and application

Depended On By

• Unknown from source alone (consumers would use File class for XLSX exports)

5. Gotchas

1. Empty Method Implementations: The Write overload with fewer parameters and the Initialize method are both empty implementations. This may indicate incomplete refactoring or dead code.

2. Type Casting in Property Setters: ExportADC, ExportEU, and ExportMV properties on File cast Exporter to Writer. This will fail if _exporter is mocked or substituted with a different IWriter<Test> implementation.

3. Template File Dependency: The export will fail at runtime if XLSXExportTemplate.xlsx does not exist in the expected location. This is not validated at construction.

4. Hardcoded Worksheet Name: The code expects a worksheet named "Data" - this is not configurable.

5. GC Manipulation: The Write method explicitly forces garbage collection with GC.Collect() and modifies GCLatencyMode and LargeObjectHeapCompactionMode. This is unusual and may have performance implications for the calling application.

6. UseLegacyTDCSoftwareFiltering: Referenced in the filtering logic but not defined in the visible source - unclear where this value comes from.

7. Commented-Out Code: The FilteredChannelData property is commented out, suggesting this functionality was removed or never completed.

8. Exception Swallowing: The GetDataScaler method catches and logs exceptions internally but continues execution, potentially returning a partially-configured DataScaler.