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

---
source_files:
  - Common/DTS.Common.Serialization/Iso/Iso.File.Test.ExtraProperty.cs
  - Common/DTS.Common.Serialization/Iso/Iso.File.cs
  - Common/DTS.Common.Serialization/Iso/Iso.File.Test.Object.cs
  - Common/DTS.Common.Serialization/Iso/Iso.File.Test.cs
generated_at: "2026-04-17T15:35:58.814665+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "e65ccfacaca06b40"
---

# Documentation: DTS.Serialization.Iso

## 1. Purpose

This module provides ISO-standard file serialization for test data, generating `.mme` (test) and `.chn` (channel) files. It serves as the export layer that transforms internal test data structures into the ISO MME format, handling metadata such as laboratory information, customer details, test objects, and measurement channels. The module bridges the domain model (`Common.ISO.TestPlan`, `Serialization.Test`) with the ISO file format specification.

---

## 2. Public Interface

### `File` (partial class)
**Namespace:** `DTS.Serialization.Iso`  
**Inheritance:** `Serialization.File`, `IWritable<Test>`

| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `File(Common.ISO.TestPlan testplan)` | Initializes an ISO file instance with the given test plan. |
| `GetTestPlan()` | `Common.ISO.TestPlan GetTestPlan()` | Returns the test plan associated with this file. |
| `AddChannel` | `void AddChannel(string dasserial, int moduleNumber, int number, string description, FilteredData data)` | Delegates channel addition to the internal `Writer`. |
| `ApplyTestPlan` | `void ApplyTestPlan(Serialization.Test test)` | Populates `TestInstance` fields from the test plan using `Common.ISO.TestPlan.IsoFields` enum. Falls back to `test.InceptionDate` if date parsing fails. |
| `Exporter` | `IWriter<Serialization.Test>` (property) | Lazy-initialized writer; propagates `UseZeroForUnfiltered`, `UseIsoCodeFilterMapping`, `FilteredExport`, `ExportISOChannelName`, and `ExportSummaryReport` settings. |
| `TestInstance` | `Test` (property) | Returns the `Test` instance associated with this file. |
| `TestFileExtension` | `static string` (property) | File extension for test files; default `".mme"`. |
| `ChannelFileExtension` | `static string` (property) | File extension for channel files; default `".chn"`. |
| `ExportSummaryReport` | `bool` (property) | Whether to export a summary report; default `false`. |
| `UseZeroForUnfiltered` | `bool` (property) | Default `false`. |
| `UseIsoCodeFilterMapping` | `bool` (property) | Forces ISO code filter determination by software filter; default `false`. |
| `FilteredExport` | `bool` (property) | Default `false`. |
| `ExportISOChannelName` | `bool` (property) | Default `false`. |

---

### `File.Test` (partial class)
**Inheritance:** `Exceptional`

| Member | Type | Description |
|--------|------|-------------|
| `DataFormatEditionNumber` | `string` | Default `"1.6"`. |
| `LaboratoryName` | `string` | Laboratory name. |
| `LaboratoryContactName` | `string` | Contact name. |
| `LaboratoryContactPhone` | `string` | Contact phone. |
| `LaboratoryContactFax` | `string` | Contact fax. |
| `LaboratoryContactEmail` | `string` | Contact email. |
| `LaboratoryTestReferenceNumber` | `string` | Test reference number. |
| `LaboratoryProjectReferenceNumber` | `string` | Project reference number (non-standard field; label prefixed with `.`). |
| `CustomerName` | `string` | Customer name. |
| `CustomerTestReferenceNumber` | `string` | Customer test reference. |
| `CustomerProjectReferenceNumber` | `string` | Customer project reference. |
| `CustomerOrderNumber` | `string` | Customer order number. |
| `CustomerCostUnit` | `string` | Customer cost unit. |
| `TestEngineerName` | `string` | Test engineer name. |
| `TestEngineerPhone` | `string` | Test engineer phone. |
| `TestEngineerFax` | `string` | Test engineer fax. |
| `TestEngineerEmail` | `string` | Test engineer email. |
| `Title` | `string` | Test title. |
| `NumberOfMedia` | `string` | Default `"1/1"`. |
| `Timestamp` | `string` | Default `DateTime.Now` formatted as `"yyyy-MM-dd HH:mm:ss"`. |
| `TestComment` | `string` | Test comments. |
| `Type` | `string` | Test type. |
| `Date` | `DateTime` | Test date; defaults to `DateTime.Now`. |
| `Subtype` | `string` | Test subtype. |
| `Regulation` | `string` | Regulation. |
| `ReferenceTemperature` | `string` | Reference temperature. |
| `RelativeAirHumidity` | `string` | Relative air humidity. |
| `NumberOfTestObjects` | `int` (read-only) | Returns `Objects.Count`. |
| `Objects` | `List<Object>` | List of test objects. |
| `Channels` | `List<Channel>` | List of channels. |
| `ExtraProperties` | `List<ExtraProperty>` | Custom properties. |
| `ToString()` | `override string` | Generates ISO-formatted string representation. |

---

### `File.Test.Object` (class)
**Inheritance:** `Exceptional`

| Member | Type | Description |
|--------|------|-------------|
| `Comments` | `string[]` | Array of comments. |
| `Name` | `string` | Test object name. |
| `Type` | `string` | Test object type (e.g., `"B"` for barrier). |
| `Number` | `string` | Reference number. |
| `MmeNumber` | `int` | MME sequence number; default `-1`. |
| `Velocity` | `string` | Velocity; default `"0.0"`. |
| `Mass` | `string` | Mass. |
| `TestObject` | `string` | Test object identifier. |
| `Position` | `string` | Driver position code; default `"?"`. |
| `TestObjectImpactSide` | `string` | Impact side. |
| `Class` | `string` | Object class. |
| `Code` | `string` | Object code. |
| `Offset` | `string` | Offset. |
| `BarrierWidth` | `string` | Barrier width (for type `"B"`). |
| `BarrierHeight` | `string` | Barrier height (for type `"B"`). |
| `YawAngle` | `string` | Yaw angle (for type `"B"`). |
| `ReferenceSystem` | `string` | Reference system (for type `"B"`). |
| `OriginX`, `OriginY`, `OriginZ` | `string` | Origin coordinates (for type `"B"`). |
| `NumberOfLoadcells` | `string` | Load cell count (for type `"B"`). |
| `ExtraProperties` | `List<ExtraProperty>` | Custom properties. |
| `ToString()` | `override string` | Generates ISO-formatted string; includes barrier-specific fields when `Type == "B"`. |

---

### `File.Test.ExtraProperty` (class)
**Inheritance:** `Exceptional`

| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `ExtraProperty(string key, string value)` | Initializes with key and value. |
| `Key` | `string` (property) | Property key; returns `null` if not initialized. |
| `Value` | `string` (property) | Property value; returns `null` if not initialized. |

---

## 3. Invariants

- **File Extensions:** `TestFileExtension` is always `".mme"`; `ChannelFileExtension` is always `".chn"` unless explicitly modified.
- **Format Constants:** `SeparatorOffset` is fixed at `28`; `Separator` is `":"`; `NoValue` constant is `"NOVALUE"`.
- **Default Values:** `DataFormatEditionNumber` defaults to `"1.6"`; `NumberOfMedia` defaults to `"1/1"`.
- **Timestamp Behavior:** `Timestamp` is set to `DateTime.Now` at `Test` construction time in format `"yyyy-MM-dd HH:mm:ss"`.
- **Null Safety:** `ExtraProperty.Key` and `ExtraProperty.Value` return `null` when `_Key.IsValueInitialized` or `_Value.IsValueInitialized` is `false`.
- **Field String Extraction:** `GetFieldString()` always returns either the extracted value or `"NOVALUE"`—never throws for field access failures.
- **Barrier Type Condition:** `Object.ToString()` only emits barrier-specific fields (`BarrierWidth`, `BarrierHeight`, `YawAngle`, `ReferenceSystem`, `OriginX/Y/Z`, `NumberOfLoadcells`) when `Type == "B"`.

---

## 4. Dependencies

### This module depends on:
- `DTS.Common.Utilities` — provides utility functions (specific members unclear from source).
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — provides `Property<T>` and `Exceptional` base class.
- `DTS.Serialization.Iso.Report` — referenced in comments; usage unclear from source.
- `Common.ISO.TestPlan` — provides test plan data and `IsoFields` enum.
- `Serialization.File` — base class for `File`.
- `Serialization.Test` — used in `ApplyTestPlan` parameter.
- `IWriter<Serialization.Test>`, `IWritable<Test>` — writer interfaces.
- `Writer` — internal writer class (not shown in source).
- `FilteredData` — data type for `AddChannel` (not shown in source).
- `Channel` — referenced in `Test.Channels` (not shown in source).

### What depends on this module:
- Cannot be determined from source alone; the module exposes public types that could be consumed by any ISO export functionality.

---

## 5. Gotchas

1. **Empty Case Handlers in `ApplyTestPlan`:** The switch statement has empty cases for `CustName`, `TEName`, `LabName`, and `NumberOfTestObjects`—these fields are read from the test plan but never assigned to `TestInstance`.

2. **Position/ImpactSide Parsing:** `Object.ToString()` parses `Position` and `TestObjectImpactSide` by extracting text before the first hyphen (`IndexOf('-') - 1`). This will throw if the string does not contain a hyphen and is not `"NOVALUE"`.

3. **Title Fallback:** `ApplyTestPlan` sets `Title` to `test.Id` when the test plan value equals `"NOVALUE"`.

4. **Non-Standard Field Labels:** `LaboratoryProjectReferenceNumberLabel` is prefixed with `.` (`.Laboratory project ref. num`), indicating it's an extension to the standard ISO format.

5. **Exporter Exception Wrapping:** The `Exporter` property catches all exceptions and re-throws with a generic message `"encountered problem getting exporter"`, potentially obscuring the root cause.

6. **Date Fallback Logic:** In `ApplyTestPlan`, if `DateTime.TryParse` fails for the date field, it falls back to `test.InceptionDate` without logging or indicating the parse failure.

7. **Property Wrapper Pattern:** All field access uses `Property<T>` wrapper objects with `IsValueInitialized` checks—direct field access via `_Key.Value` without checking initialization state may behave unexpectedly.