---
source_files:
  - Common/DTS.Common.Import/Parsers/ParseVariantBase.cs
  - Common/DTS.Common.Import/Parsers/DefaultParseImport.cs
  - Common/DTS.Common.Import/Parsers/DTSXMLParseImport.cs
generated_at: "2026-04-16T02:06:24.270866+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "6317dc1ace913c30"
---

# Parsers

## Documentation: Import Parsing Module

### 1. Purpose  
This module provides foundational infrastructure and concrete implementations for parsing import files into a structured `ImportObject`. It defines an extensible parsing pipeline via the `IParseImport` interface, with base abstractions (`ParseVariantBase`) for variant-specific parsing logic and two concrete import processors: `DefaultParseImport` (generic, variant-driven parsing) and `DTSXMLParseImport` (XML-specific parsing with UI integration, cancellation support, and post-processing for DAS-linked hardware). The module serves as the core engine for transforming raw file inputs into domain objects used throughout the DTS import workflow.

### 2. Public Interface  

#### `ParseVariantBase` (abstract class)  
- **`string FileName { get; set; }`**  
  Gets or sets the name of the file being parsed by this variant. Set by the caller before `Parse` is invoked.  
- **`abstract void Parse(ref ImportObject importObject)`**  
  Parses the file (identified by `FileName`) and mutates the provided `ImportObject` by adding or updating its contents. Must be implemented by derived classes.

#### `DefaultParseImport` (concrete class)  
- **`DefaultParseImport(ImportObject importObject, IEnumerable<IParseVariant> parseVariants)`**  
  Constructor. Initializes the parser with a target `ImportObject` and a sequence of `IParseVariant` implementations to apply.  
- **`ImportObject Parse(IEnumerable<string> importFiles)`**  
  Processes each file in `importFiles` using the configured `IParseVariant`s via a `ParseProcessor`. Returns the mutated `_importObject`.  
  *Note:* The same `ImportObject` instance passed to the constructor is returned (though mutated internally).

#### `DTSXMLParseImport` (concrete class)  
- **`DTSXMLParseImport(ImportObject importObject, IImportNotification importNotification, Func<bool> isCancelled = null, bool skipNormalizing = false)`**  
  Constructor. Initializes the XML parser with a target `ImportObject`, notification sink, optional cancellation delegate, and flag to skip normalization.  
- **`List<IUIItems> UIItems { get; set; }`**  
  Gets or sets UI-related items (e.g., progress indicators, messages) to be used by the underlying processor.  
- **`ImportObject Parse(IEnumerable<string> importFiles)`**  
  Processes XML files via `XMLParseProcessor`, applies post-processing (`AssignLinkedDASSerials`), and returns the mutated `_importObject`.  
  *Note:* `UIItems` is assigned to the processor before processing.

#### `AssignLinkedDASSerials` (private method in `DTSXMLParseImport`)  
- **`void AssignLinkedDASSerials(ref ImportObject importObject)`**  
  Post-processes `importObject.Hardware()` to populate `LinkedDASSerials` for pseudo-rack hardware: for each pseudo-rack (`IsPseudoRack() == true`), collects all hardware items whose `ParentDAS` matches the rack’s `SerialNumber`, and stores their serials in `LinkedDASSerials`.

### 3. Invariants  
- **`ParseVariantBase.Parse` must mutate `importObject` in-place** (via `ref`), not replace it.  
- **`FileName` must be set on each `IParseVariant` instance before calling `Parse(ref ImportObject)`** (enforced by caller, not by class).  
- **`DTSXMLParseImport.Parse` always calls `AssignLinkedDASSerials` after processing**, ensuring `LinkedDASSerials` is populated for pseudo-rack hardware.  
- **`DefaultParseImport` does not modify the `importFiles` sequence**; it only iterates over it.  
- **`DTSXMLParseImport` supports cancellation** via the `_isCancelled` delegate (behavior depends on `XMLParseProcessor` implementation, not visible here).  

### 4. Dependencies  
- **Depends on:**  
  - `DTS.Common.Import.Interfaces` namespace (`IParseImport`, `IParseVariant`, `IImportNotification`, `IUIItems`).  
  - `DTS.Slice.Users` namespace (for `IImportNotification`, `IUIItems`).  
  - `ImportObject` type (used throughout; definition not provided here).  
  - Internal types: `ParseProcessor`, `XMLParseProcessor` (referenced but not documented here).  
- **Depended on by:**  
  - Unknown from source alone. Likely consumed by higher-level import orchestration (e.g., UI layers, batch import services).  

### 5. Gotchas  
- **`DefaultParseImport` reuses the same `ImportObject` instance** passed to its constructor; callers must be aware that the returned object is the *same reference*, not a copy.  
- **`DTSXMLParseImport.AssignLinkedDASSerials` only processes hardware where `IsPseudoRack()` returns `true`**; non-rack hardware is skipped.  
- **`DTSXMLParseImport` does not validate `importFiles` for XML format**—assumes correctness (handled by `XMLParseProcessor`).  
- **`UIItems` must be set on `DTSXMLParseImport` *before* calling `Parse`** to be effective (assigned to processor inside `Parse`).  
- **`skipNormalizing` flag behavior is not visible in this module**—depends on `XMLParseProcessor` implementation.  
- **`AssignLinkedDASSerials` uses LINQ query materialization (`as string[] ?? matches.ToArray()`) but does not guard against null `Hardware()`**—potential `NullReferenceException` if `importObject.Hardware()` returns `null`.