--- source_files: - Common/DTS.Common.Import/XML/XMLPre20ParseGroupTemplates.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomDirections.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomTestObjects.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomPositions.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomFineLoc3s.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomFineLoc2s.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomFineLoc1s.cs - Common/DTS.Common.Import/XML/XMLParseSensorModels.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomFilterClasses.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomChannels.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomMainLocations.cs - Common/DTS.Common.Import/XML/XMLParseMMECustomPhysicalDimensions.cs - Common/DTS.Common.Import/XML/XMLPre20ParseSensors.cs - Common/DTS.Common.Import/XML/XMLParseUsers.cs - Common/DTS.Common.Import/XML/XMLParseBase.cs - Common/DTS.Common.Import/XML/XMLParseTestEngineerDetails.cs - Common/DTS.Common.Import/XML/XMLParseLabDetails.cs - Common/DTS.Common.Import/XML/XMLParseGlobalSettings.cs - Common/DTS.Common.Import/XML/XMLPre20ParseDASList.cs - Common/DTS.Common.Import/XML/XMLParseCustomerDetails.cs - Common/DTS.Common.Import/XML/XMLParseSensors.cs - Common/DTS.Common.Import/XML/XMLParseDASList.cs - Common/DTS.Common.Import/XML/XMLParseGroupTemplates.cs - Common/DTS.Common.Import/XML/XMLParseCalibrations.cs - Common/DTS.Common.Import/XML/XMLPre20ParseCalibrations.cs - Common/DTS.Common.Import/XML/XMLParseGroups.cs - Common/DTS.Common.Import/XML/XMLParseTestSetups.cs generated_at: "2026-04-17T15:26:52.176871+00:00" model: "zai-org/GLM-5-FP8" schema_version: 1 sha256: "75086f6da3a24b58" --- # XML Import Parsers Documentation ## 1. Purpose This module provides a collection of XML parsing classes for importing configuration data into the DTS system. Each parser handles a specific domain entity (sensors, calibrations, groups, test setups, hardware, etc.) and follows a strategy pattern via the `XMLParseBase` abstract class. The module supports versioned imports with migration logic for pre-2.0 data formats, ID normalization to avoid collisions with existing database records, and cancellation support for long-running operations. Parsers transform XML elements into domain objects and populate an `ImportObject` container for downstream processing. --- ## 2. Public Interface ### XMLParseBase (Abstract Base Class) ```csharp public abstract class XMLParseBase : IParseVariant { public string FileName { get; set; } public abstract void Parse(ref ImportObject importObject); protected XMLParseBase(XmlElement root, double importedVersion, Func isCancelled = null, bool skipNormalizing = false) } ``` **Behavior:** Base class for all XML parsers. Maintains static ID mapping dictionaries (`_dasIdMapping`, `_groupIdMapping`, `_sensorIdMapping`, `_channelIdMapping`) for cross-parser ID normalization. Provides protected helper methods `GetXmlElement()` and `IsCancelled()`. Initializes an internal `XmlWriter` for generating transformed XML. --- ### XMLParseDASList ```csharp public XMLParseDASList(XmlElement root, double importedVersion, Func isCancelled = null, bool skipNormalizing = false) public IImportNotification ImportNotification { get; set; } public override void Parse(ref ImportObject importObject) public List ParseDASList(XmlElement root) ``` **Behavior:** Parses DAS (Data Acquisition System) hardware from XML. Normalizes DAS IDs starting at -2 (preserving -1 for unassigned channels per FB 13544). Validates hardware types against `DTS.Common.Enums.Hardware.HardwareTypes`. Clears `_dasIdMapping` on construction. --- ### XMLParseSensors ```csharp public XMLParseSensors(XmlElement root, double importedVersion, Func isCancelled = null, bool skipNormalizing = false) public IImportNotification ImportNotification { get; set; } public override void Parse(ref ImportObject importObject) public XmlElement ConvertSensors(IEnumerable sensors) public IEnumerable ParseSensors(XmlElement root) ``` **Behavior:** Parses sensor data. Normalizes sensor `DatabaseId` starting at -2 (preserving -1 for invalid). Populates `_sensorIdMapping` during conversion. Respects `_skipNormalizing` flag. --- ### XMLParseGroups ```csharp public XMLParseGroups(XmlElement root, double importedVersion, Func isCancelled = null) public IImportNotification ImportNotification { get; set; } public override void Parse(ref ImportObject importObject) public List ParseGroups(XmlElement root, ref ImportObject importObject) ``` **Behavior:** Parses static groups. Clears `_groupIdMapping` on construction. Normalizes group IDs starting at -2. Maps group channels' DAS and Sensor IDs using `_dasIdMapping` and `_sensorIdMapping`. Handles deleted sensors gracefully (FB 14308) by setting `SensorId = 0`. Uses string-based group ID mapping for pre-2.1 exports, integer-based for 2.1+. --- ### XMLParseTestSetups ```csharp public XMLParseTestSetups(XmlElement root, double importedVersion, Func isCancelled = null, bool skipNormalizing = false) public IImportNotification ImportNotification { get; set; } public override void Parse(ref ImportObject importObject) public IEnumerable ParseTestTemplate(ImportObject importObject, XmlElement root) ``` **Behavior:** Parses test setups/templates. Clears `_channelIdMapping` on construction. Normalizes channel IDs and group IDs within test templates. Maps hardware references using `_dasIdMapping`. Sets `TestSetupImportFileFormat` on the import object. Catches and records XML read errors as warnings (FB 36879). Handles deleted sensors (FB 14308) and orphaned static group references. --- ### XMLParseCalibrations ```csharp public XMLParseCalibrations(XmlElement root, double importedVersion, Func isCancelled = null) public IImportNotification ImportNotification { get; set; } public override void Parse(ref ImportObject importObject) public XmlElement ConvertCalibrations(IEnumerable calibrations) public IEnumerable ParseCalibrations(XmlElement root) ``` **Behavior:** Parses sensor calibrations. Version-specific handling: for version 1.0, sets `AtCapacity = false` and derives `SensitivityUnits` from `NonLinear`/`IsProportional` flags. Uses `FileUtils.DataPROPre20XmlVersion` threshold. --- ### XMLParseGroupTemplates ```csharp public XMLParseGroupTemplates(XmlElement root, double importedVersion, ISO.ISO13499FileDb iSO13499FileDb, Func isCancelled = null) public override void Parse(ref ImportObject importObject) public IEnumerable ParseGroupTemplates(ref ImportObject importObject, XmlElement root) ``` **Behavior:** Parses group templates (test object templates). Requires `ISO13499FileDb` reference. Builds channel lookup from `importObject.CustomChannels()`. Sets `Embedded = true` for system-built or embedded templates. Throws `NotSupportedException` if referenced ISO test object is not found (FB 8790). --- ### XMLParseUsers ```csharp public XMLParseUsers(XmlElement root, double importedVersion, IEnumerable uiItems, Func isCancelled = null) public IImportNotification ImportNotification { get; set; } public override void Parse(ref ImportObject importObject) ``` **Behavior:** Parses user records. Requires `IEnumerable` for user construction. Sets import status to `ReadingUsers`. --- ### XMLParseGlobalSettings ```csharp public XMLParseGlobalSettings(XmlElement root, double importedVersion, Func isCancelled = null) public IImportNotification ImportNotification { get; set; } public override void Parse(ref ImportObject importObject) ``` **Behavior:** Parses global settings into a `Dictionary`. Extracts `SettingName` and `SettingValue` child elements. --- ### XMLParseSensorModels ```csharp public XMLParseSensorModels(XmlElement root, double importedVersion, Func isCancelled = null) public override void Parse(ref ImportObject importObject) ``` **Behavior:** Parses `SensorModel` objects. Creates new instances and calls `ReadXML` on each child element. --- ### XMLParseCustomerDetails, XMLParseLabDetails, XMLParseTestEngineerDetails ```csharp public XMLParseCustomerDetails(XmlElement root, double importedVersion, Func isCancelled = null) public XMLParseLabDetails(XmlElement root, double importedVersion, Func isCancelled = null) public XMLParseTestEngineerDetails(XmlElement root, double importedVersion, Func isCancelled = null) public IImportNotification ImportNotification { get; set; } // All three public override void Parse(ref ImportObject importObject) // All three ``` **Behavior:** Parse ISO entity details (customer, lab, test engineer). Each reads child elements, converts via internal `XmlWriter`, and re-parses. Sets specific import status (`ReadingCustomerDetails`, `ReadingLabDetails`). --- ### MME Custom Parsers (7 classes) ```csharp // All follow same pattern: public XMLParseMMECustom[Type](XmlElement root, double importedVersion, Func isCancelled = null) public override void Parse(ref ImportObject importObject) // Types: Directions, TestObjects, Positions, FineLoc3s, FineLoc2s, FineLoc1s, FilterClasses, Channels, MainLocations, PhysicalDimensions ``` **Behavior:** Each parses ISO MME reference data types by iterating child nodes and calling `ReadXML` on each `XmlElement`. Most check `IsCancelled()` per iteration; `XMLParseMMECustomChannels` does not. --- ### Pre-20 Migration Parsers ```csharp // XMLPre20ParseGroupTemplates public XMLPre20ParseGroupTemplates(XmlElement root, double importedVersion, XMLParseGroupTemplates xmlParseGroupTemplates, Func isCancelled = null) // XMLPre20ParseSensors public XMLPre20ParseSensors(XmlElement root, double importedVersion, XMLParseSensors xmlParseSensors, Func isCancelled = null) public XmlElement MigrateSensors(IEnumerable sensors) // XMLPre20ParseDASList public XMLPre20ParseDASList(XmlElement root, double importedVersion, XMLParseDASList xmlParseDASList, Func isCancelled = null) public List ParsePre20DASList(XmlElement root) // XMLPre20ParseCalibrations public XMLPre20ParseCalibrations(XmlElement root, double importedVersion, XMLParseCalibrations xmlParseCalibrations, Func isCancelled = null) ``` **Behavior:** Decorator-style parsers that delegate to their non-Pre20 counterparts after performing version-specific migration. `XMLPre20ParseSensors` assigns negative database IDs starting at -1. `XMLPre20ParseDASList` wraps ISO hardware in `DASHardware` instances. --- ## 3. Invariants 1. **ID Normalization Range:** DAS, Sensor, Group, and Channel IDs are normalized to negative integers starting at -2 (or -1 for sensors in pre-20 migration), preserving -1 for "invalid/unassigned" semantics. 2. **Static Mapping Dictionaries:** `_dasIdMapping`, `_groupIdMapping`, `_sensorIdMapping`, and `_channelIdMapping` are `static readonly` and shared across all parser instances. Callers must ensure proper sequencing (DAS before Sensors before Groups before TestSetups). 3. **Group ID Mapping Key Type:** `_groupIdMapping` uses `string` keys to support both legacy name-based references (pre-2.1) and modern ID-based references (2.1+). 4. **Cancellation Contract:** If `isCancelled` parameter is null, `IsCancelled()` returns `false`. Parsers return partially-populated lists when cancelled mid-iteration. 5. **ImportObject Population:** All `Parse` methods modify the passed `ImportObject` via `ref` and call specific `Add*` methods (e.g., `AddSensors`, `AddHardwareList`, `AddStaticGroups`). 6. **Version Thresholds:** - `FileUtils.DataPROPre20XmlVersion` distinguishes pre-2.0 from modern formats - `FileUtils.DataPRO21XmlVersion` (2.1+) changes group ID reference semantics - Version 1.0 has special calibration sensitivity unit handling --- ## 4. Dependencies ### This module depends on: - `DTS.Common.Import.Interfaces` - `ImportObject`, `IParseVariant`, `IImportNotification`, `ImportStatus`, `ImportError`, `ImportSeverityError` - `DTS.Common.Interface` - `IUIItems`, sensor interfaces - `DTS.Common.Interface.Groups.GroupList` - `IGroup`, group interfaces - `DTS.Common.Interface.GroupTemplate` - Group template interfaces - `DTS.Common.SharedResource.Strings` - Localized error messages (`StringResources`) - `DTS.Common.Enums.DBExport` - `TopLevelFields` enum for XML element names - `DTS.Common.Enums` - Various enums - `DTS.Common.Enums.Sensors` - `SensorConstants.SensUnits` - `DTS.Common.Utils` - `FileUtils` with version constants - `DTS.SensorDB` - `SensorData`, `SensorCalibration`, `SensorModel` - `DTS.Slice.Users` - `User` class - `DataPROWin7.DataModel` - `DASHardware`, `TestObjectTemplate`, `TestObject` - `DTS.Common.Classes.TestSetups` - `TestTemplate` - `DTS.Common.ISO` or `ISO` namespace - MME types (`MMEDirections`, `MMETestObjects`, `MMEPositions`, `MMEFineLocations1/2/3`, `MMEFilterClasses`, `MMEPossibleChannels`, `MMETransducerMainLocation`, `MMEPhysicalDimensions`, `CustomerDetails`, `TestEngineerDetails`, `LabratoryDetails`) - `System.Xml` - `XmlElement`, `XmlDocument`, `XmlWriter` ### What depends on this module: - Not explicitly shown in source, but inferred: Import orchestration code that instantiates these parsers based on XML structure and version, then processes the populated `ImportObject`. --- ## 5. Gotchas 1. **Static Dictionary State:** The ID mapping dictionaries are static and shared. `XMLParseDASList`, `XMLParseGroups`, and `XMLParseTestSetups` clear their respective dictionaries in constructors, but if parsers are instantiated out of order or reused, mappings may be incorrect. 2. **Missing Cancellation Check:** `XMLParseMMECustomChannels.ParseCustomChannels` does not check `IsCancelled()` during iteration, unlike all other MME parsers. 3. **Unused ImportNotification Property:** `XMLParseMMECustomChannels` declares `ImportNotification` property but never uses it. 4. **Empty Error Handling:** In `XMLParseDASList.ParseDASList`, invalid DAS entries are collected into `invalidDAS` list but the subsequent `if (invalidDAS.Any()) { //??? }` block is empty—no error is reported. 5. **Pre-20 Sensor ID Collision:** `XMLPre20ParseSensors.MigrateSensors` starts IDs at -1, while `XMLParseSensors.ConvertSensors` starts at -2. This inconsistency could cause issues if both are used in the same import pipeline. 6. **Group Template Embedded Logic:** `XMLParseGroupTemplates` sets `template.Embedded = template.SysBuilt || template.Embedded` after reading XML, which may override the imported value unexpectedly. 7. **Orphaned Static Group Handling:** `XMLParseTestSetups.ConvertTestTemplates` silently sets `group.StaticGroupId = null` if the ID isn't found in `_groupIdMapping`, with only a comment explaining this is for buggy old exports. 8. **Version 1.0 Calibration Assumptions:** The calibration parser makes assumptions about sensitivity units for version 1.0 files based on `NonLinear` and `IsProportional` flags that may not be accurate for all legacy data. 9. **XmlWriter State Management:** `XMLParseBase.GetXmlElement()` calls `_writer.Close()`, which means it can only be called once per instance. Subsequent calls would fail.