---
source_files:
  - Common/DTS.CommonCore/XMLUtils/DTSXMLFile.cs
  - Common/DTS.CommonCore/XMLUtils/TestMetadataXml.cs
generated_at: "2026-04-16T12:04:29.540782+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "8848a0560473ca7f"
---

# Documentation: DTS.Common.XMLUtils

## 1. Purpose

This module provides XML parsing and metadata extraction utilities for DTS application files. It contains two static classes: `DTSXMLFile` for extracting item count information from XML files, and `TestMetadataXml` for aggregating and parsing multiple DTS test metadata XML files into a unified `XDocument` structure. The module serves as a bridge between raw XML file storage and the application's test management system.

---

## 2. Public Interface

### Class: `DTSXMLFile` (static)

#### `public static double GetItemsToCompleteCount(string fileName)`
- **Returns**: The value of the `TotalItems` attribute from an XML node as a `double`.
- **Behavior**: Retrieves an import XML node via `FileUtils.GetImportXmlNode()`, then extracts and converts the `TotalItems` attribute using `CultureInfo.InvariantCulture`. The `importVersion` parameter is passed as an `out` parameter to the internal call but is not returned to the caller.

---

### Class: `TestMetadataXml` (static)

#### `public static XDocument GetTestMetadataXml(string path, string file = "", string pattern = "")`
- **Returns**: An `XDocument` with a root element named `"Tests"` containing aggregated test metadata.
- **Parameters**:
  - `path` - Directory path to search for files.
  - `file` - Optional specific file path. If provided, only this file is processed.
  - `pattern` - File pattern for search. Defaults to `".dts"` if null or empty.
- **Behavior**: 
  - Clears and populates the static `FileUtils.FileList` property.
  - If `file` is provided, adds it directly to the file list.
  - Otherwise, calls `FileUtils.FindFiles(path, pattern)` to discover files.
  - Delegates to `SetTestMetadataType()` for XML processing.

---

## 3. Invariants

- **FileUtils.FileList state**: The static property `FileUtils.FileList` is cleared (`new List<string>()`) at the start of every `GetTestMetadataXml()` call. Concurrent calls could result in race conditions.
- **Return value for `GetItemsToCompleteCount`**: Always returns a `double`. The initial `importVersion` is set to `-1` before calling `FileUtils.GetImportXmlNode()`.
- **XML structure assumption**: `SetTestMetadataType()` expects XML fragments to contain either a `"Test"` root element or a `"TestSetup"` root element. Other structures are silently ignored (the element is not added).
- **Error handling**: `SetTestMetadataType()` catches exceptions at both the file level (logs and continues) and the overall level (returns an empty `XDocument`).

---

## 4. Dependencies

### This module depends on:
- **`DTS.Common.Utils`** (`FileUtils` class)
  - `FileUtils.GetImportXmlNode()` - used in `DTSXMLFile`
  - `FileUtils.FileList` - static list property used in `TestMetadataXml`
  - `FileUtils.FindFiles()` - file discovery method used in `TestMetadataXml`
- **`DTS.Common.Utilities.Logging`** (`APILogger` class)
  - `APILogger.Log()` - used for error logging in `TestMetadataXml`
- **`System.Xml.Linq`** - `XDocument`, `XElement` for XML manipulation
- **`System.IO`** - `StreamReader`, `StringReader`, `File` for file I/O

### What depends on this module:
- **Unknown from source alone** - No consumers are shown in the provided files.

---

## 5. Gotchas

1. **Multiple XML documents in a single file**: `SetTestMetadataType()` splits file contents by the string `"<?xml version="`, meaning a single file can contain multiple concatenated XML documents. This is a specific format requirement that is not validated—malformed files will cause silent failures.

2. **Static state mutation**: `FileUtils.FileList` is a static property that is cleared and repopulated on every call to `GetTestMetadataXml()`. This is not thread-safe and could cause issues in concurrent scenarios.

3. **Unused variable warning suppression**: The file includes `// ReSharper disable UnusedVariable`, suggesting there may be dead code or the developer wanted to suppress warnings about variables like `xmlCounter` and `fullstring` that could potentially be unused in certain code paths.

4. **DataType attribute logic**: The `DataType` attribute is set to `"ALL"` if the file path contains the substring `"ALL"` (case-sensitive), otherwise `"ROI"`. This simple string check could produce unexpected results if `"ALL"` appears elsewhere in the path.

5. **Empty XDocument on total failure**: If an exception occurs at the outer `try-catch` in `SetTestMetadataType()`, an empty `XDocument` is returned (no root element), which may cause null reference exceptions in consumers expecting a `"Tests"` root.

6. **importVersion not exposed**: In `GetItemsToCompleteCount()`, the `importVersion` value is retrieved via `out` parameter but never returned or used by the caller. Its purpose is unclear from the source.