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

---
source_files:
  - Common/DTS.Common.Serialization/XLSX/Excel.File.cs
  - Common/DTS.Common.Serialization/XLSX/Excel.File.Writer.cs
generated_at: "2026-04-17T15:42:08.979045+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "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
```csharp
public File()
```
Constructs a new XLSX file instance, passing `"XLSX"` to the base class.

#### Properties

```csharp
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.

```csharp
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

```csharp
internal File WriterParent { get; private set; }
```
The owning `File` instance that created this writer.

```csharp
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`.

```csharp
public double Start { get; set; }
public double Stop { get; set; }
```
Time bounds for the export (in seconds).

```csharp
public bool Filtered { get; set; }
```
Controls whether channel data should be filtered using SAE J211 filtering during export.

#### Methods

```csharp
public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)
```
**Empty implementation** - does nothing.

```csharp
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`.

```csharp
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

```csharp
protected Cell GetCell(Worksheet worksheet, string xColumn, UInt32 rowIndex, bool bLookForCell = true)
```
Retrieves or creates a cell at the specified column and row.

```csharp
protected WorksheetPart GetWorksheetPartByName(SpreadsheetDocument document, string sheetName)
```
Retrieves a worksheet part by name. Returns `null` if not found.

```csharp
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`.