noisedestroyers/DP44
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
DP44/enriched-partialglm/Common/DTS.Common.Import/XML.md
noisedestroyers bc3ac1d4c9 init
2026-04-17 14:55:32 -04:00

17 KiB
Raw Permalink Blame History

source_files, generated_at, model, schema_version, sha256
source_files generated_at model schema_version sha256
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
2026-04-16T11:44:54.944851+00:00 zai-org/GLM-5-FP8 1 87dec39982bd8179

Documentation: DTS.Common.Import.XML Parsers

1. Purpose

This module provides a family of XML parsing classes for importing configuration and data entities into the DTS system. Each parser handles a specific domain entity (sensors, hardware, groups, test setups, calibrations, MME custom definitions, etc.) by reading XML elements and populating an ImportObject. The module supports versioned imports (handling pre-2.0, 1.0, and 2.1+ formats) with ID normalization to avoid collisions with existing database records. All parsers inherit from XMLParseBase and implement IParseVariant, enabling a strategy pattern for import operations.

2. Public Interface

XMLParseBase (Abstract Base Class)

public abstract class XMLParseBase : IParseVariant
{
    // Properties
    public string FileName { get; set; }
    
    // Abstract method
    public abstract void Parse(ref ImportObject importObject);
    
    // Constructor
    protected XMLParseBase(XmlElement root, double importedVersion, Func<bool> isCancelled = null, bool skipNormalizing = false)
    
    // Protected methods
    protected XmlElement GetXmlElement()
    protected bool IsCancelled() // via delegate
}

Behavior: Base class providing shared infrastructure for all XML parsers. Maintains static ID mapping dictionaries for DAS, group, sensor, and channel IDs. Provides cancellation support via delegate and XML document building utilities via XmlWriter.

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)
private XmlElement ConvertDASList(List<DASHardware> dasList)

Behavior: Parses DAS (Data Acquisition System) hardware entries. Normalizes DAS IDs starting at -2 (preserving -1 for unassigned channels). 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 entries. Normalizes sensor DatabaseId starting at -2 (preserving -1 for invalid). Populates _sensorIdMapping during conversion. Optionally skips normalization via _skipNormalizing.

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)
private XmlElement ConvertGroups(List<IGroup> staticGroups)

Behavior: Parses static group definitions. Normalizes group IDs starting at -2. Maps group IDs by string (name) for pre-2.1 exports, by integer ID for 2.1+. Remaps DAS and sensor IDs in group channels using _dasIdMapping and _sensorIdMapping. Clears _groupIdMapping on construction.

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)
private XmlElement ConvertTestTemplates(IEnumerable<TestTemplate> testTemplates, ImportObject importObject)

Behavior: Parses test setup templates. Normalizes channel IDs starting at -1. Remaps DAS, sensor, and group IDs using the static mapping dictionaries. Handles embedded groups and deleted sensor references gracefully. Clears _channelIdMapping on construction. Sets importObject.TestSetupImportFileFormat based on template count.

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 calibration data. Handles version-specific logic: for version 1.0, sets AtCapacity = false and derives SensitivityUnits based on NonLinear and 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. Sets Embedded = true for system-built or embedded templates. Throws NotSupportedException if referenced ISO test object is not found in import file.

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)
private IEnumerable<User> ParseUsers(XmlElement root, IEnumerable<IUIItems> iUItems)

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)
private Dictionary<string, string> ParseGlobalSettings(XmlElement root)
private void GetGlobalSetting(XmlElement node, ref Dictionary<string, string> settings)

Behavior: Parses global settings into a Dictionary<string, string>. Reads SettingName and SettingValue child elements.

XMLParseSensorModels

public XMLParseSensorModels(XmlElement root, double importedVersion, Func<bool> isCancelled = null)

public override void Parse(ref ImportObject importObject)
private List<SensorModel> ParseSensorModels(XmlElement root)

Behavior: Parses sensor model definitions. Creates new SensorModel instances and calls ReadXML on each.

MME Custom Parsers (8 classes)

All follow the same pattern:

// XMLParseMMECustomDirections
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEDirections> ParseCustomDirections(XmlElement root)

// XMLParseMMECustomTestObjects
public override void Parse(ref ImportObject importObject)
public IEnumerable<ISO.MMETestObjects> ParseCustomTestObjects(XmlElement root)

// XMLParseMMECustomPositions
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEPositions> ParsePhysicalDimensions(XmlElement root)

// XMLParseMMECustomFineLoc1s/2s/3s
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEFineLocations1/2/3> ParseCustomFineLoc1s/2s/3s(XmlElement root)

// XMLParseMMECustomFilterClasses
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEFilterClasses> ParseMMECustomFilterClasses(XmlElement root)

// XMLParseMMECustomChannels
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
public IEnumerable<ISO.MMEPossibleChannels> ParseCustomChannels(XmlElement root)

// XMLParseMMECustomMainLocations
public override void Parse(ref ImportObject importObject)
public IEnumerable<ISO.MMETransducerMainLocation> ParseCustomMainLocations(XmlElement root)

// XMLParseMMECustomPhysicalDimensions
public override void Parse(ref ImportObject importObject)
private IEnumerable<ISO.MMEPhysicalDimensions> ParsePhysicalDimensions(XmlElement root)

Behavior: Each parses ISO MME (Measurement Module Equipment) custom definitions by iterating child nodes and calling ReadXML on the appropriate ISO type.

Detail Parsers (3 classes)

// XMLParseCustomerDetails
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
private XmlElement ConvertCustomerDetails(IEnumerable<ISO.CustomerDetails> customerDetails)
private List<ISO.CustomerDetails> ParseCustomerDetails(XmlElement root)

// XMLParseTestEngineerDetails
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
private XmlElement ConvertTestEngineerDetails(IEnumerable<ISO.TestEngineerDetails> details)
private List<ISO.TestEngineerDetails> ParseTestEngineerDetails(XmlElement root)

// XMLParseLabDetails
public IImportNotification ImportNotification { get; set; }
public override void Parse(ref ImportObject importObject)
private XmlElement ConvertLabDetails(IEnumerable<ISO.LabratoryDetails> details)
private List<ISO.LabratoryDetails> ParseLabDetails(XmlElement root)

Behavior: Parse and re-serialize detail records. Set import status notifications.

Pre-20 Version Parsers (4 classes)

// XMLPre20ParseDASList
public XMLPre20ParseDASList(XmlElement root, double importedVersion, XMLParseDASList xmlParseDASList, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)
public List<DASHardware> ParsePre20DASList(XmlElement root)
private XmlElement MigratePre20DASList(List<DASHardware> dasList)

// XMLPre20ParseSensors
public XMLPre20ParseSensors(XmlElement root, double importedVersion, XMLParseSensors xmlParseSensors, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)
public XmlElement MigrateSensors(IEnumerable<SensorData> sensors)

// XMLPre20ParseCalibrations
public XMLPre20ParseCalibrations(XmlElement root, double importedVersion, XMLParseCalibrations xmlParseCalibrations, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)
private IEnumerable<SensorCalibration> ParsePre20Calibrations(ref ImportObject importObject)

// XMLPre20ParseGroupTemplates
public XMLPre20ParseGroupTemplates(XmlElement root, double importedVersion, XMLParseGroupTemplates xmlParseGroupTemplates, Func<bool> isCancelled = null)
public override void Parse(ref ImportObject importObject)

Behavior: Handle migration from pre-2.0 XML formats. Delegate to corresponding non-Pre20 parser after initial parsing. Use negative ID assignment starting at -1 for sensors/DAS.

3. Invariants

  1. ID Normalization: All normalized IDs are negative integers. DAS and sensor normalization starts at -2 (preserving -1 for "unassigned/invalid"). Group normalization starts at -2. Channel normalization starts at -1.

  2. Mapping Dictionary Lifecycle:

    • _dasIdMapping is cleared in XMLParseDASList constructor
    • _groupIdMapping is cleared in XMLParseGroups constructor
    • _channelIdMapping is cleared in XMLParseTestSetups constructor
    • _sensorIdMapping is NOT explicitly cleared (relies on static initialization)

  3. Import Order Dependency: Parsers must be invoked in dependency order (DAS → Sensors → Groups → TestSetups) because later parsers use mapping dictionaries populated by earlier parsers.

  4. Cancellation Contract: When IsCancelled() returns true, parsers return their partially-filled collection immediately.

  5. Version Thresholds:

    • 1.0D: Legacy format requiring calibration unit inference
    • FileUtils.DataPROPre20XmlVersion: Pre-2.0 format threshold
    • FileUtils.DataPRO21XmlVersion: 2.1+ format (uses integer group IDs instead of names)

4. Dependencies

This module depends on:

  • DTS.Common.Import.Interfaces - IParseVariant, ImportObject, IImportNotification, ImportStatus, ImportError, ImportSeverityError
  • DTS.Common.Enums.DBExport - TopLevelFields enum
  • DTS.Common.Enums - Various enums
  • 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 - StringResources for error messages
  • DTS.Common.Utils - FileUtils with version constants
  • DTS.SensorDB - SensorData, SensorModel, SensorCalibration, SensorConstants
  • DTS.Slice.Users - User class
  • DataPROWin7.DataModel - DASHardware, TestObjectTemplate, TestObject
  • DTS.Common.Classes.TestSetups - TestTemplate
  • DTS.Common.ISO / 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:

  • Unknown from source alone (no consumers shown in imports)

5. Gotchas

  1. Static Mapping Dictionaries: The ID mapping dictionaries (_dasIdMapping, _groupIdMapping, _sensorIdMapping, _channelIdMapping) are static, meaning they persist across parser instances. If parsers are instantiated out of order or reused, stale mappings could cause incorrect ID translations.

  2. Inconsistent Cancellation Checks: XMLParseMMECustomChannels.ParseCustomChannels does NOT check IsCancelled() during iteration, unlike all other MME parsers. This could lead to non-responsive cancellation for large channel imports.

  3. Pre-20 vs Standard ID Normalization Difference:

    • XMLPre20ParseSensors and XMLPre20ParseDASList start normalization at -1
    • XMLParseSensors and XMLParseDASList start at -2 This inconsistency may be intentional (different handling for pre-2.0 imports) but could cause confusion.

  4. Unused Invalid DAS Collection: In XMLParseDASList.ParseDASList, invalid DAS serial numbers are collected into invalidDAS list but the subsequent if (invalidDAS.Any()) { //??? } block is empty, suggesting incomplete error handling.

  5. Group ID Mapping Key Type: _groupIdMapping uses string keys to handle both old exports (group name) and new exports (integer ID as string). This dual-mode requires careful version checking via _importedVersion >= FileUtils.DataPRO21XmlVersion.

  6. Missing Sensor Handling: In XMLParseGroups and XMLParseTestSetups, if a sensor ID is not found in _sensorIdMapping, it's silently set to 0 rather than failing (per FB 14308). This handles deleted sensors gracefully but may mask data integrity issues.

  7. XMLParseMMECustomChannels Public ImportNotification: The ImportNotification property on XMLParseMMECustomChannels is never used within the class, unlike other parsers that call SetStatus.

  8. Ref Parameter Patterns: Several methods pass ImportObject by ref even when not reassigning the variable, which is unnecessary but harmless.

Reference in New Issue View Git Blame Copy Permalink