85 lines
6.3 KiB
Markdown
85 lines
6.3 KiB
Markdown
---
|
||
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. |