360 lines
17 KiB
Markdown
360 lines
17 KiB
Markdown
---
|
|
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-16T11:44:54.944851+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "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)
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
// 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)
|
|
|
|
```csharp
|
|
// 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)
|
|
|
|
```csharp
|
|
// 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. |