15 KiB
source_files, generated_at, model, schema_version, sha256
| source_files | generated_at | model | schema_version | sha256 | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
2026-04-17T15:26:52.176871+00:00 | zai-org/GLM-5-FP8 | 1 | 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)
public abstract class XMLParseBase : IParseVariant
{
public string FileName { get; set; }
public abstract void Parse(ref ImportObject importObject);
protected XMLParseBase(XmlElement root, double importedVersion, Func<bool> 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
public XMLParseDASList(XmlElement root, double importedVersion, Func<bool> isCancelled = null, bool skipNormalizing = false)
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public List<DASHardware> 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
public XMLParseSensors(XmlElement root, double importedVersion, Func<bool> isCancelled = null, bool skipNormalizing = false)
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public XmlElement ConvertSensors(IEnumerable<SensorData> sensors)
public IEnumerable<SensorData> 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
public XMLParseGroups(XmlElement root, double importedVersion, Func<bool> isCancelled = null)
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public List<IGroup> 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
public XMLParseTestSetups(XmlElement root, double importedVersion, Func<bool> isCancelled = null, bool skipNormalizing = false)
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public IEnumerable<TestTemplate> 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
public XMLParseCalibrations(XmlElement root, double importedVersion, Func<bool> isCancelled = null)
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public XmlElement ConvertCalibrations(IEnumerable<SensorCalibration> calibrations)
public IEnumerable<SensorCalibration> 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
public XMLParseGroupTemplates(XmlElement root, double importedVersion, ISO.ISO13499FileDb iSO13499FileDb, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)
public IEnumerable<DataPROWin7.DataModel.TestObjectTemplate> 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
public XMLParseUsers(XmlElement root, double importedVersion, IEnumerable<IUIItems> uiItems, Func<bool> isCancelled = null)
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
Behavior: Parses user records. Requires IEnumerable<IUIItems> for user construction. Sets import status to ReadingUsers.
XMLParseGlobalSettings
public XMLParseGlobalSettings(XmlElement root, double importedVersion, Func<bool> isCancelled = null)
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
Behavior: Parses global settings into a Dictionary<string, string>. Extracts SettingName and SettingValue child elements.
XMLParseSensorModels
public XMLParseSensorModels(XmlElement root, double importedVersion, Func<bool> 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
public XMLParseCustomerDetails(XmlElement root, double importedVersion, Func<bool> isCancelled = null)
public XMLParseLabDetails(XmlElement root, double importedVersion, Func<bool> isCancelled = null)
public XMLParseTestEngineerDetails(XmlElement root, double importedVersion, Func<bool> 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)
// All follow same pattern:
public XMLParseMMECustom[Type](XmlElement root, double importedVersion, Func<bool> 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
// XMLPre20ParseGroupTemplates
public XMLPre20ParseGroupTemplates(XmlElement root, double importedVersion, XMLParseGroupTemplates xmlParseGroupTemplates, Func<bool> isCancelled = null)
// XMLPre20ParseSensors
public XMLPre20ParseSensors(XmlElement root, double importedVersion, XMLParseSensors xmlParseSensors, Func<bool> isCancelled = null)
public XmlElement MigrateSensors(IEnumerable<SensorData> sensors)
// XMLPre20ParseDASList
public XMLPre20ParseDASList(XmlElement root, double importedVersion, XMLParseDASList xmlParseDASList, Func<bool> isCancelled = null)
public List<DASHardware> ParsePre20DASList(XmlElement root)
// XMLPre20ParseCalibrations
public XMLPre20ParseCalibrations(XmlElement root, double importedVersion, XMLParseCalibrations xmlParseCalibrations, Func<bool> 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
-
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.
-
Static Mapping Dictionaries:
_dasIdMapping,_groupIdMapping,_sensorIdMapping, and_channelIdMappingarestatic readonlyand shared across all parser instances. Callers must ensure proper sequencing (DAS before Sensors before Groups before TestSetups). -
Group ID Mapping Key Type:
_groupIdMappingusesstringkeys to support both legacy name-based references (pre-2.1) and modern ID-based references (2.1+). -
Cancellation Contract: If
isCancelledparameter is null,IsCancelled()returnsfalse. Parsers return partially-populated lists when cancelled mid-iteration. -
ImportObject Population: All
Parsemethods modify the passedImportObjectviarefand call specificAdd*methods (e.g.,AddSensors,AddHardwareList,AddStaticGroups). -
Version Thresholds:
FileUtils.DataPROPre20XmlVersiondistinguishes pre-2.0 from modern formatsFileUtils.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,ImportSeverityErrorDTS.Common.Interface-IUIItems, sensor interfacesDTS.Common.Interface.Groups.GroupList-IGroup, group interfacesDTS.Common.Interface.GroupTemplate- Group template interfacesDTS.Common.SharedResource.Strings- Localized error messages (StringResources)DTS.Common.Enums.DBExport-TopLevelFieldsenum for XML element namesDTS.Common.Enums- Various enumsDTS.Common.Enums.Sensors-SensorConstants.SensUnitsDTS.Common.Utils-FileUtilswith version constantsDTS.SensorDB-SensorData,SensorCalibration,SensorModelDTS.Slice.Users-UserclassDataPROWin7.DataModel-DASHardware,TestObjectTemplate,TestObjectDTS.Common.Classes.TestSetups-TestTemplateDTS.Common.ISOorISOnamespace - 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
-
Static Dictionary State: The ID mapping dictionaries are static and shared.
XMLParseDASList,XMLParseGroups, andXMLParseTestSetupsclear their respective dictionaries in constructors, but if parsers are instantiated out of order or reused, mappings may be incorrect. -
Missing Cancellation Check:
XMLParseMMECustomChannels.ParseCustomChannelsdoes not checkIsCancelled()during iteration, unlike all other MME parsers. -
Unused ImportNotification Property:
XMLParseMMECustomChannelsdeclaresImportNotificationproperty but never uses it. -
Empty Error Handling: In
XMLParseDASList.ParseDASList, invalid DAS entries are collected intoinvalidDASlist but the subsequentif (invalidDAS.Any()) { //??? }block is empty—no error is reported. -
Pre-20 Sensor ID Collision:
XMLPre20ParseSensors.MigrateSensorsstarts IDs at -1, whileXMLParseSensors.ConvertSensorsstarts at -2. This inconsistency could cause issues if both are used in the same import pipeline. -
Group Template Embedded Logic:
XMLParseGroupTemplatessetstemplate.Embedded = template.SysBuilt || template.Embeddedafter reading XML, which may override the imported value unexpectedly. -
Orphaned Static Group Handling:
XMLParseTestSetups.ConvertTestTemplatessilently setsgroup.StaticGroupId = nullif the ID isn't found in_groupIdMapping, with only a comment explaining this is for buggy old exports. -
Version 1.0 Calibration Assumptions: The calibration parser makes assumptions about sensitivity units for version 1.0 files based on
NonLinearandIsProportionalflags that may not be accurate for all legacy data. -
XmlWriter State Management:
XMLParseBase.GetXmlElement()calls_writer.Close(), which means it can only be called once per instance. Subsequent calls would fail.