enriched-qwen3-coder-next/Common/DTS.Common.Serialization/Iso/Report.md

---
source_files:
  - Common/DTS.Common.Serialization/Iso/Report/SummaryReport.cs
  - Common/DTS.Common.Serialization/Iso/Report/ChannelData.cs
generated_at: "2026-04-16T03:40:44.805086+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "6a29f80fb642a4d0"
---

# Report

## Documentation: Summary Report Serialization Module

### 1. Purpose  
This module provides functionality to generate and output a standardized text-based summary report for ISO test data. It aggregates channel metadata (e.g., ISO code, name, filter class, EIDs, data flags) from a `Test` object into a structured report format, primarily for use in import workflows (e.g., test setup reconciliation or audit trails). The report is serialized to a file named `TestNo_FilterList.txt` in a specified directory. It is part of the `DTS.Serialization.Iso.Report` namespace and serves as a bridge between internal test data structures and external systems expecting this specific textual format.

---

### 2. Public Interface  

#### `SummaryReport` class  
- **`public static SummaryReport CreateSummaryReport(Test test)`**  
  Factory method that constructs a `SummaryReport` instance by extracting channel data from the provided `test` object. Internally calls `AddChannels` to populate channel data.  
  - *Returns*: A fully populated `SummaryReport` instance.  

- **`public string GetLines()`**  
  Generates the full report content as a single string.  
  - *Returns*: A multi-line string where the first line is `"Number of channels          :XXX /  /  /  /  /"` (with zero-padded channel count), followed by one line per channel (see `ChannelData.GetLine()`).  

- **`public static void OutputToPath(string path, SummaryReport summary)`**  
  Writes the report content (from `summary.GetLines()`) to a file named `TestNo_FilterList.txt` in the directory specified by `path`.  
  - *Throws*: May throw `IOException`, `UnauthorizedAccessException`, or other exceptions from `File.WriteAllText`.  

- **`protected void AddChannels(Test.Module.Channel[] channels)`**  
  Adds channel data to the internal `_channels` list, converting each `Test.Module.Channel` to a `ChannelData` via `ChannelData.CreateChannel`. Channels are sorted by `ChannelNumber` (ascending) after insertion.  
  - *Note*: This method is `protected`, so it is only callable from within `SummaryReport` or derived classes.  

#### `ChannelData` class *(internal)*  
- **`public string GetLine()`**  
  Returns a single formatted line for this channel in the report.  
  - *Format*: `"Name of channel XXX         :<ISOCode> / <ChannelName> / <SAEFilterClass> / <SetupEID> / <DataCollectionEID> / <DataFlagInt>"`, where `XXX = ChannelNumber + 1` (1-indexed, zero-padded to 3 digits).  

- **`public static ChannelData CreateChannel(Test.Module.Channel channel)`**  
  Factory method that constructs a `ChannelData` instance from a `Test.Module.Channel`.  
  - *Behavior*:  
    - For `AnalogInputChannel` instances, extracts `IsoCode`, `IsoChannelName`, and `SoftwareFilter` (spaces removed).  
    - For non-`AnalogInputChannel` types, `ISOCode` and `ChannelName` default to `string.Empty`; `SAEFilterClass` defaults to `string.Empty`.  
    - Maps `channel.AbsoluteDisplayOrder` → `ChannelNumber`, `channel.DataCollectionEID` → `DataCollectionEID`, `channel.SetupEID` → `SetupEID`, `channel.DataFlag` → `DataFlag` (cast to `DataFlag` enum).  

---

### 3. Invariants  
- **Channel ordering**: Channels in the report are sorted by `ChannelNumber` (ascending), as enforced by `_channels.Sort(...)` in `AddChannels`.  
- **Channel numbering**: The channel index in the report header line (`XXX`) is `ChannelNumber + 1`, making it 1-indexed (e.g., `ChannelNumber=0` → `001`).  
- **Fixed header format**: The first line of the report always follows the pattern:  
  `"Number of channels          :{count:000} /  /  /  /  /"`, with exactly 3 digits for the count and 5 trailing ` / ` segments (the last 4 are empty).  
- **Channel line format**: Each channel line uses the literal `"Name of channel"` prefix and exactly 6 ` / `-separated fields: `ISOCode`, `ChannelName`, `SAEFilterClass`, `SetupEID`, `DataCollectionEID`, and `(int)DataFlag`.  
- **Filter class normalization**: `SAEFilterClass` is derived from `analog.SoftwareFilter` with all spaces removed (via `Replace(" ", "")`).  

---

### 4. Dependencies  
- **Internal types used**:  
  - `Test` (namespace `DTS.Test` or similar; imported implicitly via `Test.Module.Channel`)  
  - `Test.Module.Channel` (base type)  
  - `Test.Module.AnalogInputChannel` (derived type; only this subtype is handled specially)  
  - `DataFlag` enum (from `DTS.Common` namespace)  
- **External dependencies**:  
  - `System.Collections.Generic` (`List<T>`)  
  - `System.Text` (`StringBuilder`)  
  - `System.IO` (`File.WriteAllText`, `Path.Combine`)  
- **Depended upon by**:  
  - Likely consumed by UI or workflow components (e.g., import wizard) as inferred from comments referencing internal cases. No explicit callers are visible in the source.  

---

### 5. Gotchas  
- **Non-`AnalogInputChannel` handling**: For non-`AnalogInputChannel` instances (e.g., digital channels), `ISOCode`, `ChannelName`, and `SAEFilterClass` will be empty strings. This may produce lines like `"Name of channel 001         : /  /  / EID1 / EID2 / 0"`.  
- **`DataFlag` enum cast**: `channel.DataFlag` is cast directly to `DataFlag` (e.g., `(DataFlag)channel.DataFlag`). If `channel.DataFlag` is an `int` with values outside the `DataFlag` enum’s defined range, this may yield undefined or unexpected values.  
- **Path handling**: `OutputToPath` uses `Path.Combine(path, "TestNo_FilterList.txt")`, so `path` must be a valid directory path (not a file path). Passing a file path will cause an `ArgumentException` or `IOException`.  
- **No validation on `Test` object**: `CreateSummaryReport` does not validate that `test.Channels` is non-null. If `test.Channels` is `null`, `AddChannels([.. test.Channels])` will throw a `NullReferenceException`.  
- **`protected` method**: `AddChannels` is not public, so external code cannot manually populate channels—only via `CreateSummaryReport`.  
- **Hardcoded filename**: The output filename `"TestNo_FilterList.txt"` is hardcoded in `OutputToPath`, with no configurability.  
- **No encoding specification**: `File.WriteAllText` uses UTF-8 *without BOM* by default in .NET 5+, but this is not explicitly stated in the source.
-												init

											
										
										
											2026-04-17 14:55:32 -04:00
+								---
 								source_files:
 								  - Common/DTS.Common.Serialization/Iso/Report/SummaryReport.cs
 								  - Common/DTS.Common.Serialization/Iso/Report/ChannelData.cs
 								generated_at: "2026-04-16T03:40:44.805086+00:00"
 								model: "Qwen/Qwen3-Coder-Next-FP8"
 								schema_version: 1
 								sha256: "6a29f80fb642a4d0"
 								---
 								# Report
 								## Documentation: Summary Report Serialization Module
 								### 1. Purpose
 								This module provides functionality to generate and output a standardized text-based summary report for ISO test data. It aggregates channel metadata (e.g., ISO code, name, filter class, EIDs, data flags) from a `Test` object into a structured report format, primarily for use in import workflows (e.g., test setup reconciliation or audit trails). The report is serialized to a file named `TestNo_FilterList.txt` in a specified directory. It is part of the `DTS.Serialization.Iso.Report` namespace and serves as a bridge between internal test data structures and external systems expecting this specific textual format.
 								---
 								### 2. Public Interface
 								#### `SummaryReport` class
 								- **`public static SummaryReport CreateSummaryReport(Test test)`**
 								  Factory method that constructs a `SummaryReport` instance by extracting channel data from the provided `test` object. Internally calls `AddChannels` to populate channel data.
 								  - *Returns*: A fully populated `SummaryReport` instance.
 								- **`public string GetLines()`**
 								  Generates the full report content as a single string.
 								  - *Returns*: A multi-line string where the first line is `"Number of channels          :XXX /  /  /  /  /"` (with zero-padded channel count), followed by one line per channel (see `ChannelData.GetLine()`).
 								- **`public static void OutputToPath(string path, SummaryReport summary)`**
 								  Writes the report content (from `summary.GetLines()`) to a file named `TestNo_FilterList.txt` in the directory specified by `path`.
 								  - *Throws*: May throw `IOException`, `UnauthorizedAccessException`, or other exceptions from `File.WriteAllText`.
 								- **`protected void AddChannels(Test.Module.Channel[] channels)`**
 								  Adds channel data to the internal `_channels` list, converting each `Test.Module.Channel` to a `ChannelData` via `ChannelData.CreateChannel`. Channels are sorted by `ChannelNumber` (ascending) after insertion.
 								  - *Note*: This method is `protected`, so it is only callable from within `SummaryReport` or derived classes.
 								#### `ChannelData` class *(internal)*
 								- **`public string GetLine()`**
 								  Returns a single formatted line for this channel in the report.
 								  - *Format*: `"Name of channel XXX         :<ISOCode> / <ChannelName> / <SAEFilterClass> / <SetupEID> / <DataCollectionEID> / <DataFlagInt>"`, where `XXX = ChannelNumber + 1` (1-indexed, zero-padded to 3 digits).
 								- **`public static ChannelData CreateChannel(Test.Module.Channel channel)`**
 								  Factory method that constructs a `ChannelData` instance from a `Test.Module.Channel`.
 								  - *Behavior*:
 								    - For `AnalogInputChannel` instances, extracts `IsoCode`, `IsoChannelName`, and `SoftwareFilter` (spaces removed).
 								    - For non-`AnalogInputChannel` types, `ISOCode` and `ChannelName` default to `string.Empty`; `SAEFilterClass` defaults to `string.Empty`.
 								    - Maps `channel.AbsoluteDisplayOrder` → `ChannelNumber`, `channel.DataCollectionEID` → `DataCollectionEID`, `channel.SetupEID` → `SetupEID`, `channel.DataFlag` → `DataFlag` (cast to `DataFlag` enum).
 								---
 								### 3. Invariants
 								- **Channel ordering**: Channels in the report are sorted by `ChannelNumber` (ascending), as enforced by `_channels.Sort(...)` in `AddChannels`.
 								- **Channel numbering**: The channel index in the report header line (`XXX`) is `ChannelNumber + 1`, making it 1-indexed (e.g., `ChannelNumber=0` → `001`).
 								- **Fixed header format**: The first line of the report always follows the pattern:
 								  `"Number of channels          :{count:000} /  /  /  /  /"`, with exactly 3 digits for the count and 5 trailing ` / ` segments (the last 4 are empty).
 								- **Channel line format**: Each channel line uses the literal `"Name of channel"` prefix and exactly 6 ` / `-separated fields: `ISOCode`, `ChannelName`, `SAEFilterClass`, `SetupEID`, `DataCollectionEID`, and `(int)DataFlag`.
 								- **Filter class normalization**: `SAEFilterClass` is derived from `analog.SoftwareFilter` with all spaces removed (via `Replace(" ", "")`).
 								---
 								### 4. Dependencies
 								- **Internal types used**:
 								  - `Test` (namespace `DTS.Test` or similar; imported implicitly via `Test.Module.Channel`)
 								  - `Test.Module.Channel` (base type)
 								  - `Test.Module.AnalogInputChannel` (derived type; only this subtype is handled specially)
 								  - `DataFlag` enum (from `DTS.Common` namespace)
 								- **External dependencies**:
 								  - `System.Collections.Generic` (`List<T>`)
 								  - `System.Text` (`StringBuilder`)
 								  - `System.IO` (`File.WriteAllText`, `Path.Combine`)
 								- **Depended upon by**:
 								  - Likely consumed by UI or workflow components (e.g., import wizard) as inferred from comments referencing internal cases. No explicit callers are visible in the source.
 								---
 								### 5. Gotchas
 								- **Non-`AnalogInputChannel` handling**: For non-`AnalogInputChannel` instances (e.g., digital channels), `ISOCode`, `ChannelName`, and `SAEFilterClass` will be empty strings. This may produce lines like `"Name of channel 001         : /  /  / EID1 / EID2 / 0"`.
 								- **`DataFlag` enum cast**: `channel.DataFlag` is cast directly to `DataFlag` (e.g., `(DataFlag)channel.DataFlag`). If `channel.DataFlag` is an `int` with values outside the `DataFlag` enum’s defined range, this may yield undefined or unexpected values.
 								- **Path handling**: `OutputToPath` uses `Path.Combine(path, "TestNo_FilterList.txt")`, so `path` must be a valid directory path (not a file path). Passing a file path will cause an `ArgumentException` or `IOException`.
 								- **No validation on `Test` object**: `CreateSummaryReport` does not validate that `test.Channels` is non-null. If `test.Channels` is `null`, `AddChannels([.. test.Channels])` will throw a `NullReferenceException`.
 								- **`protected` method**: `AddChannels` is not public, so external code cannot manually populate channels—only via `CreateSummaryReport`.
 								- **Hardcoded filename**: The output filename `"TestNo_FilterList.txt"` is hardcoded in `OutputToPath`, with no configurability.
 								- **No encoding specification**: `File.WriteAllText` uses UTF-8 *without BOM* by default in .NET 5+, but this is not explicitly stated in the source.