init

docs/ai/Common/DTS.Common.SerializationPlus/XLSX.md

@@ -0,0 +1,109 @@
+---
+source_files:
+  - Common/DTS.Common.SerializationPlus/XLSX/Excel.File.cs
+  - Common/DTS.Common.SerializationPlus/XLSX/Excel.File.Writer.cs
+generated_at: "2026-04-17T15:42:01.836098+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "6e876d1fde5a5ee5"
+---
+
+# 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 data—including channel information, sensor metadata, and sampled data—to Excel spreadsheets. The module supports exporting data in Engineering Units (EU), millivolts (mV), or raw ADC values, with optional software filtering applied during export.
+
+---
+
+## 2. Public Interface
+
+### `File` Class (partial)
+**Namespace:** `DTS.Serialization.XLSX`  
+**Inheritance:** `Serialization.File`, `IWritable<Test>`
+
+| Member | Signature | Description |
+|--------|-----------|-------------|
+| `File()` | `public File()` | Constructor that initializes the file type as "XLSX". |
+| `Exporter` | `IWriter<Test> Exporter { get; }` | Lazily initializes and returns the writer instance for XLSX export. Creates a new `Writer` on first access. |
+| `ExportADC` | `bool ExportADC { set; }` | Write-only property that controls whether ADC values are exported. Delegates to `Writer.ExportADC`. |
+| `ExportEU` | `bool ExportEU { set; }` | Write-only property that controls whether Engineering Units are exported. Delegates to `Writer.ExportEU`. |
+| `ExportMV` | `bool ExportMV { set; }` | Write-only property that controls whether millivolt values are exported. Delegates to `Writer.ExportMv`. |
+
+### `File.Writer` Class (nested)
+**Namespace:** `DTS.Serialization.XLSX`  
+**Inheritance:** `Writer<File>`, `IWriter<Test>`
+
+| Member | Signature | Description |
+|--------|-----------|-------------|
+| `ExportADC` | `bool ExportADC { get; set; }` | Controls whether ADC values are included in export. Default: `false`. |
+| `ExportEU` | `bool ExportEU { get; set; }` | Controls whether Engineering Units are included in export. Default: `true`. |
+| `ExportMv` | `bool ExportMv { get; set; }` | Controls whether millivolt values are included in export. Default: `false`. |
+| `Start` | `double Start { get; set; }` | Starting time bound for data export. |
+| `Stop` | `double Stop { get; set; }` | Ending time bound for data export. |
+| `Filtered` | `bool Filtered { get; set; }` | Indicates whether software filtering should be applied to exported data. |
+| `ExportHeaders` | `List<IExportHeader> ExportHeaders { get; set; }` | List of user-selected headers to export (FB 6410). |
+| `WriterParent` | `File WriterParent { get; }` | Internal property referencing the owning `File` instance. |
+| `Write` | `void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` | **Empty implementation** — no code body. |
+| `Write` | `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)` | Main export method. Writes test data to XLSX file at specified path. Handles channel metadata, filtering, and sample data export. |
+| `Initialize` | `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** — no code body. |
+| `GetDataScaler` | `static Common.DAS.Concepts.DataScaler GetDataScaler(Test.Module.AnalogInputChannel currentAnalogChannel)` | Static factory method that constructs a `DataScaler` from an `AnalogInputChannel`, configuring inversion, IEPE, unit conversion, linearization, offsets, excitation voltages, and digital properties. |
+
+---
+
+## 3. Invariants
+
+1. **Template File Requirement:** The file `XLSXExportTemplate.xlsx` must exist at `{AppDomain.CurrentDomain.BaseDirectory}/ReportTemplates/` or the export will fail.
+
+2. **Channel Processing Order:** Channels are sorted by `AbsoluteDisplayOrder` then by `Number` before processing, not by display order (per FB 14659).
+
+3. **Default Export Mode:** The `Writer` defaults to `ExportEU = true`, `ExportADC = false`, `ExportMv = false`.
+
+4. **AnalogInputChannel Only:** Only channels of type `Test.Module.AnalogInputChannel` are processed; all other channel types are skipped during export.
+
+5. **Progress Update Interval:** Progress updates occur every `UPDATE_INTERVAL` (1000) samples.
+
+6. **Column Indexing:** Excel columns start at "B" (index 0 maps to column B) due to column A being reserved for header labels.
+
+7. **ISO Code Mode:** When `WriterParent.ISOViewMode` is `ChannelNameOnly`, the ISO code field is written as empty string.
+
+---
+
+## 4. Dependencies
+
+### This Module Depends On:
+- **DocumentFormat.OpenXml** — OpenXML SDK for Excel file manipulation
+- **DocumentFormat.OpenXml.Packaging** — Spreadsheet document handling
+- **DocumentFormat.OpenXml.Spreadsheet** — Spreadsheet-specific OpenXML types
+- **DTS.Common.Enums** — Enumerations including `IsoViewMode`
+- **DTS.Common.Enums.Sensors** — `SensorConstants.BridgeType.IEPE`
+- **DTS.Common.Interface.ExportData** — `IExportHeader` interface
+- **DTS.Common.SerializationPlus** — Base serialization framework (`Serialization.File`, `Writer<T>`)
+- **DTS.Common.Utilities.Logging** — `APILogger` for error logging
+- **DTS.Slice.Control** — `SaeJ211Filter`, `FilteredData`, event handler delegates
+- **Common.DAS.Concepts.DataScaler** — Data scaling and unit conversion
+
+### What Depends On This Module:
+- Unclear from source alone — no direct consumers visible in these files.
+
+---
+
+## 5. Gotchas
+
+1. **Empty Method Implementations:** Both the 6-parameter `Write` overload and the `Initialize` method have empty bodies. This may indicate incomplete implementation or dead code.
+
+2. **Cast in Property Setters:** The `ExportADC`, `ExportEU`, and `ExportMV` setters on `File` cast `_exporter` from `IWriter<Test>` to `Writer`. This will throw an `InvalidCastException` if a different `IWriter<Test>` implementation is substituted.
+
+3. **Dual Excel Writing Approaches:** The export uses DOM-based writing (via `GetCell`, `InsertCellInWorksheet`) for headers/metadata, then switches to SAX-based writing (via `OpenXmlReader`/`OpenXmlWriter`) for sample data. This is a performance optimization but creates complexity.
+
+4. **Removed GC Calls:** Commented-out garbage collection code exists in the `Write` method with a note that it caused significant performance hit. It was likely added when the application was 32-bit only.
+
+5. **Static Row Cache:** `_rowIndexToRow` is a `static readonly Dictionary<uint, Row>` that is cleared at the start of each `Write` call. This could cause issues if multiple exports run concurrently.
+
+6. **String Lookup Not Thread-Safe:** `_stringLookup` is an instance field initialized to `null` and built lazily during `InsertSharedStringItem`. The method is not thread-safe.
+
+7. **Filtered Data Behavior:** When `Filtered` is `false`, the software filter column writes "NONE" instead of the actual filter name (FB 18024).
+
+8. **Interpolation Logic:** When sample rates differ between channels, linear interpolation is applied. The interpolation handles edge cases (end of data) by using the previous sample for the increment calculation.
+
+9. **FogBugz References:** Multiple comments reference FogBugz tickets (9920, 6410, 14659, 18024, 14469, 14513) indicating historical bug fixes that may be relevant for understanding edge cases.