enriched-qwen3-coder-next/Common/DTS.CommonCore/XMLUtils.md

---
source_files:
  - Common/DTS.CommonCore/XMLUtils/DTSXMLFile.cs
  - Common/DTS.CommonCore/XMLUtils/TestMetadataXml.cs
generated_at: "2026-04-16T02:15:46.883506+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "8848a0560473ca7f"
---

# XMLUtils

## Documentation: `DTSXMLFile` and `TestMetadataXml` Modules

---

### 1. **Purpose**

This module provides utilities for parsing and aggregating DTS (Device Test System) XML test metadata files. `DTSXMLFile` offers a lightweight helper to extract the total number of items to complete from a single XML file, while `TestMetadataXml` aggregates multiple DTS XML files into a unified `XDocument` structure for downstream processing (e.g., test execution planning or reporting). These utilities abstract away low-level XML parsing and file discovery logic, enabling consistent consumption of test metadata across the system.

---

### 2. **Public Interface**

#### `DTSXMLFile.GetItemsToCompleteCount(string fileName)`
- **Signature**: `public static double GetItemsToCompleteCount(string fileName)`
- **Behavior**: Reads the XML file at `fileName`, retrieves the root `<Test>` element (via `FileUtils.GetImportXmlNode`), and returns the numeric value of its `TotalItems` attribute as a `double`. Returns `-1` if the import version cannot be determined (due to `importVersion` initialization and lack of error handling on `GetImportXmlNode` failure), though the return value itself is not used to signal failure— callers must validate the result.

#### `TestMetadataXml.GetTestMetadataXml(string path, string file = "", string pattern = "")`
- **Signature**: `public static XDocument GetTestMetadataXml(string path, string file = "", string pattern = "")`
- **Behavior**: Discovers DTS XML files using either:
  - A specific `file` path (if provided), or
  - A recursive search under `path` using `pattern` (default: `".dts"`).
  
  Calls `FileUtils.FileList` (a static field) to populate discovered files, then invokes `SetTestMetadataType` to parse them. Returns a single `XDocument` with root `<Tests>`, containing one `<TestMetadata>` child per input file. Each `<TestMetadata>` has an `Id` attribute (0-based index) and contains all `<Test>` or `<TestSetup>` elements extracted from the file. If parsing fails for a file, it logs via `APILogger.Log` and continues; if the entire process fails, returns an empty `XDocument`.

---

### 3. **Invariants**

- **XML Structure Assumption**: Files must contain at least one top-level `<Test>` or `<TestSetup>` element; otherwise, no child elements are added to the corresponding `<TestMetadata>`.
- **File Discovery**: `FileUtils.FileList` is mutated as a side effect of `GetTestMetadataXml`. Its value is not cleared between calls unless explicitly reset (e.g., by subsequent calls to `GetTestMetadataXml`).
- **Data Type Inference**: A file’s `DataType` is `"ALL"` if its path contains the substring `"ALL"` (case-sensitive), otherwise `"ROI"`.
- **Timestamp Source**: `FileDate` is set to `File.GetCreationTime(file)`, which may be platform-dependent (e.g., UTC vs. local time).
- **Error Handling**: Exceptions during per-file processing are caught and logged; the method does not fail fast. Exceptions in the outer `try` block (e.g., during `XDocument` construction) cause an empty `XDocument` to be returned.

---

### 4. **Dependencies**

#### **Internal Dependencies**
- `DTS.Common.Utils.FileUtils`: Used for file discovery (`FindFiles`) and XML node retrieval (`GetImportXmlNode`). Relies on `FileUtils.FileList` (a static `List<string>` field).
- `DTS.Common.Utilities.Logging.APILogger`: Used for logging errors during file processing.

#### **System Dependencies**
- `System.Xml.Linq` (`XDocument`, `XElement`, `XAttribute`)
- `System.IO` (`StreamReader`, `StringReader`, `File.GetCreationTime`)

#### **Depended Upon**
- Likely consumed by test orchestration or reporting modules (e.g., to load test plans or generate summaries). Not directly referenced in source, but its public methods are entry points for metadata ingestion.

---

### 5. **Gotchas**

- **Substring Matching for `DataType`**: The check `file.Contains("ALL")` is case-sensitive and matches any path containing `"ALL"` (e.g., `"MyALLTests.xml"` → `"ALL"`). This may produce unintended results if `"ALL"` appears in unrelated paths.
- **XML Fragment Parsing**: `SetTestMetadataType` splits file content on `"<?xml version="` to handle multiple XML declarations in one file. This is fragile—malformed XML (e.g., missing `<?xml` or embedded comments) may cause incorrect splitting or parsing errors.
- **`FileUtils.FileList` Mutation**: The static `FileUtils.FileList` is overwritten on each call to `GetTestMetadataXml`. If callers retain a reference to this list, it may become stale after subsequent calls.
- **No Validation of `TotalItems`**: `GetItemsToCompleteCount` assumes the `TotalItems` attribute exists and is numeric. If missing or malformed, `Convert.ToDouble` may throw (though `CultureInfo.InvariantCulture` is used correctly).
- **No Disposal of `StringReader`/`StreamReader` in Outer Loop**: While `StreamReader` is disposed per-file, `StringReader` instances (`sr`) are not explicitly disposed (though `XDocument.Load` consumes them synchronously and they are short-lived).
- **Empty File Handling**: If a file contains no `<Test>` or `<TestSetup>` elements, its corresponding `<TestMetadata>` node is added but remains empty—no error is logged.
- **`GetImportXmlNode` Behavior Unknown**: `DTSXMLFile.GetItemsToCompleteCount` depends on `FileUtils.GetImportXmlNode`, whose implementation is not provided. Its error behavior (e.g., return value on missing file) is unknown, making failure modes of `GetItemsToCompleteCount` ambiguous.

> **Note**: None of the above are explicitly documented in the provided source; they are inferred from implementation patterns and potential edge cases.
-												init

											
										
										
											2026-04-17 14:55:32 -04:00
+								---
 								source_files:
 								  - Common/DTS.CommonCore/XMLUtils/DTSXMLFile.cs
 								  - Common/DTS.CommonCore/XMLUtils/TestMetadataXml.cs
 								generated_at: "2026-04-16T02:15:46.883506+00:00"
 								model: "Qwen/Qwen3-Coder-Next-FP8"
 								schema_version: 1
 								sha256: "8848a0560473ca7f"
 								---
 								# XMLUtils
 								## Documentation: `DTSXMLFile` and `TestMetadataXml` Modules
 								---
 								### 1. **Purpose**
 								This module provides utilities for parsing and aggregating DTS (Device Test System) XML test metadata files. `DTSXMLFile` offers a lightweight helper to extract the total number of items to complete from a single XML file, while `TestMetadataXml` aggregates multiple DTS XML files into a unified `XDocument` structure for downstream processing (e.g., test execution planning or reporting). These utilities abstract away low-level XML parsing and file discovery logic, enabling consistent consumption of test metadata across the system.
 								---
 								### 2. **Public Interface**
 								#### `DTSXMLFile.GetItemsToCompleteCount(string fileName)`
 								- **Signature**: `public static double GetItemsToCompleteCount(string fileName)`
 								- **Behavior**: Reads the XML file at `fileName`, retrieves the root `<Test>` element (via `FileUtils.GetImportXmlNode`), and returns the numeric value of its `TotalItems` attribute as a `double`. Returns `-1` if the import version cannot be determined (due to `importVersion` initialization and lack of error handling on `GetImportXmlNode` failure), though the return value itself is not used to signal failure— callers must validate the result.
 								#### `TestMetadataXml.GetTestMetadataXml(string path, string file = "", string pattern = "")`
 								- **Signature**: `public static XDocument GetTestMetadataXml(string path, string file = "", string pattern = "")`
 								- **Behavior**: Discovers DTS XML files using either:
 								  - A specific `file` path (if provided), or
 								  - A recursive search under `path` using `pattern` (default: `".dts"`).
 								  Calls `FileUtils.FileList` (a static field) to populate discovered files, then invokes `SetTestMetadataType` to parse them. Returns a single `XDocument` with root `<Tests>`, containing one `<TestMetadata>` child per input file. Each `<TestMetadata>` has an `Id` attribute (0-based index) and contains all `<Test>` or `<TestSetup>` elements extracted from the file. If parsing fails for a file, it logs via `APILogger.Log` and continues; if the entire process fails, returns an empty `XDocument`.
 								---
 								### 3. **Invariants**
 								- **XML Structure Assumption**: Files must contain at least one top-level `<Test>` or `<TestSetup>` element; otherwise, no child elements are added to the corresponding `<TestMetadata>`.
 								- **File Discovery**: `FileUtils.FileList` is mutated as a side effect of `GetTestMetadataXml`. Its value is not cleared between calls unless explicitly reset (e.g., by subsequent calls to `GetTestMetadataXml`).
 								- **Data Type Inference**: A file’s `DataType` is `"ALL"` if its path contains the substring `"ALL"` (case-sensitive), otherwise `"ROI"`.
 								- **Timestamp Source**: `FileDate` is set to `File.GetCreationTime(file)`, which may be platform-dependent (e.g., UTC vs. local time).
 								- **Error Handling**: Exceptions during per-file processing are caught and logged; the method does not fail fast. Exceptions in the outer `try` block (e.g., during `XDocument` construction) cause an empty `XDocument` to be returned.
 								---
 								### 4. **Dependencies**
 								#### **Internal Dependencies**
 								- `DTS.Common.Utils.FileUtils`: Used for file discovery (`FindFiles`) and XML node retrieval (`GetImportXmlNode`). Relies on `FileUtils.FileList` (a static `List<string>` field).
 								- `DTS.Common.Utilities.Logging.APILogger`: Used for logging errors during file processing.
 								#### **System Dependencies**
 								- `System.Xml.Linq` (`XDocument`, `XElement`, `XAttribute`)
 								- `System.IO` (`StreamReader`, `StringReader`, `File.GetCreationTime`)
 								#### **Depended Upon**
 								- Likely consumed by test orchestration or reporting modules (e.g., to load test plans or generate summaries). Not directly referenced in source, but its public methods are entry points for metadata ingestion.
 								---
 								### 5. **Gotchas**
 								- **Substring Matching for `DataType`**: The check `file.Contains("ALL")` is case-sensitive and matches any path containing `"ALL"` (e.g., `"MyALLTests.xml"` → `"ALL"`). This may produce unintended results if `"ALL"` appears in unrelated paths.
 								- **XML Fragment Parsing**: `SetTestMetadataType` splits file content on `"<?xml version="` to handle multiple XML declarations in one file. This is fragile—malformed XML (e.g., missing `<?xml` or embedded comments) may cause incorrect splitting or parsing errors.
 								- **`FileUtils.FileList` Mutation**: The static `FileUtils.FileList` is overwritten on each call to `GetTestMetadataXml`. If callers retain a reference to this list, it may become stale after subsequent calls.
 								- **No Validation of `TotalItems`**: `GetItemsToCompleteCount` assumes the `TotalItems` attribute exists and is numeric. If missing or malformed, `Convert.ToDouble` may throw (though `CultureInfo.InvariantCulture` is used correctly).
 								- **No Disposal of `StringReader`/`StreamReader` in Outer Loop**: While `StreamReader` is disposed per-file, `StringReader` instances (`sr`) are not explicitly disposed (though `XDocument.Load` consumes them synchronously and they are short-lived).
 								- **Empty File Handling**: If a file contains no `<Test>` or `<TestSetup>` elements, its corresponding `<TestMetadata>` node is added but remains empty—no error is logged.
 								- **`GetImportXmlNode` Behavior Unknown**: `DTSXMLFile.GetItemsToCompleteCount` depends on `FileUtils.GetImportXmlNode`, whose implementation is not provided. Its error behavior (e.g., return value on missing file) is unknown, making failure modes of `GetItemsToCompleteCount` ambiguous.
 								> **Note**: None of the above are explicitly documented in the provided source; they are inferred from implementation patterns and potential edge cases.