141 lines
9.3 KiB
Markdown
141 lines
9.3 KiB
Markdown
---
|
|
source_files:
|
|
- Common/DTS.Common.Import/ImportError.cs
|
|
- Common/DTS.Common.Import/ParseProcessor.cs
|
|
- Common/DTS.Common.Import/TsetSetupImportSensorInfo.cs
|
|
- Common/DTS.Common.Import/CsvUtil.cs
|
|
- Common/DTS.Common.Import/ImportNotification.cs
|
|
- Common/DTS.Common.Import/XMLParseProcessor.cs
|
|
- Common/DTS.Common.Import/CalibrationImport.cs
|
|
- Common/DTS.Common.Import/GroupHelper.cs
|
|
- Common/DTS.Common.Import/ImportObject.cs
|
|
generated_at: "2026-04-16T14:08:49.625344+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "e94d77a26e8f0798"
|
|
---
|
|
|
|
# Module Documentation: DTS.Common.Import
|
|
|
|
## 1. Purpose
|
|
The `DTS.Common.Import` namespace provides the infrastructure for parsing and importing test configuration data (sensors, calibrations, test setups, hardware) from external files (CSV, XML) into the application's internal object model. It defines a centralized data container (`ImportObject`), processors for handling file parsing workflows (`ParseProcessor`, `XMLParseProcessor`), and various utility classes for data transformation and error reporting during the import process.
|
|
|
|
## 2. Public Interface
|
|
|
|
### Classes
|
|
|
|
#### `ImportObject`
|
|
The central state container for an import operation. It holds all imported entities and lookup mappings.
|
|
* **Properties**:
|
|
* `ImportFormats SourceFormat`: Gets or sets the format of the source file.
|
|
* `ImportFileFormat TestSetupImportFileFormat`: Gets or sets the file format type (Single, Multiple, No Test Setup).
|
|
* **Methods**:
|
|
* `IEnumerable<ImportError> Errors()`: Returns the list of import errors.
|
|
* `void AddError(ImportError d)`, `void AddErrors(IEnumerable<ImportError> d)`: Appends errors to the collection.
|
|
* `void ClearErrors()`: Clears the error list.
|
|
* `void ClearSensors()`: Clears the sensor list.
|
|
* `void ClearTestSetups()`: Clears the test setup list.
|
|
* `ImportFileFormat GetImportFileFormat()`: Determines the file format based on the count of test setups.
|
|
* **Add/Get methods for collections**: `Sensors`, `Calibrations`, `TestSetups`, `Groups`, `GroupTemplates`, `Hardware`, `Users`, `CustomerDetails`, `LabDetails`, `TestEngineerDetails`, `CustomChannels`, `PhysicalDimensions`, `Positions`, `Directions`, `FilterClasses`, `MainLocations`, `FineLoc1s/2s/3s`, `TestObjects`, `SensorModels`, `StaticGroups`.
|
|
* Pattern: `void Add[Entity](T item)`, `void Add[Entity]List(IEnumerable list)`, `IEnumerable Get[Entity]()`.
|
|
* **Lookup Management**:
|
|
* `void AssignSensorLookup(Dictionary<string, SensorData> sensorLookup)`
|
|
* `void AssignCalibrationLookup(Dictionary<string, List<SensorCalibration>> calibrationLookup)`
|
|
* `void AssignSensorGroupNameLookup(Dictionary<string, string> sensorGroupNameLookup)`
|
|
* `void AssignOldSensorDatabaseIdToNew(Dictionary<int, int> oldSensorDatabaseIdToNew)`
|
|
* Corresponding `Add...` and `Get...` methods for these lookups.
|
|
* `IReadOnlyDictionary<int, ISensorData> GetSensorLookup()`: Constructs a lookup dictionary keyed by `DatabaseId` from the current sensors list.
|
|
|
|
#### `ParseProcessor`
|
|
Orchestrates parsing using a list of file names and `IParseVariant` implementations.
|
|
* **Constructor**: `ParseProcessor(ImportObject importObject, IEnumerable<string> fileNames, IEnumerable<IParseVariant> parseVariants)`
|
|
* **Methods**:
|
|
* `ImportObject Process()`: Iterates through `_fileNames` and `_parseVariants`, executing `variant.Parse(ref _importObject)` for each.
|
|
|
|
#### `XMLParseProcessor`
|
|
Orchestrates XML parsing with progress notification and cancellation support.
|
|
* **Constructor**: `XMLParseProcessor(ImportObject importObject, IImportNotification importNotification, IEnumerable<string> fileNames, Func<bool> isCancelled, bool skipNormalizing)`
|
|
* **Properties**:
|
|
* `List<IUIItems> UIItems`: Gets or sets UI items used by the parser factory.
|
|
* **Methods**:
|
|
* `ImportObject Process()`: Iterates files, sets status, creates parsers via `XmlParserFactory`, executes parsing, and notifies progress.
|
|
|
|
#### `ImportNotification` & `IImportNotification`
|
|
Provides callback delegates for reporting import status and progress.
|
|
* **Interface `IImportNotification`**:
|
|
* `Action ImportDone`
|
|
* `Action<List<string>> ReportErrors`
|
|
* `Action<double> SetProgress`
|
|
* `Action<ImportStatus> SetStatus`
|
|
* **Class `ImportNotification`**:
|
|
* **Constructors**: Default (no-op delegates), Parameterized (accepts specific `Action` delegates).
|
|
|
|
#### `CalibrationImport`
|
|
Implements `ICalibrationImport` to manipulate sensor calibration data.
|
|
* **Methods**:
|
|
* `SensorCalibration CheckForExcitationCalibration(SensorCalibration sc, double sensitivity, ExcitationVoltageOptions.ExcitationVoltageOption excitation, string EU)`: Adds a calibration record if the excitation differs from the first record.
|
|
* `SensorCalibration AddLinearCalRecordIfNeeded(SensorCalibration sc, bool savedIsProportional, bool savedRemoveOffset)`: Adds a linear calibration record if only one record exists.
|
|
* `SensorCalibration AddLinearZeroMethodIfNeeded(SensorCalibration sc, ZeroMethodType zeroMethodType, double zeroMethodStart, double zeroMethodEnd)`: Adds a zero method if only one exists.
|
|
|
|
#### `CsvUtil`
|
|
Static utility for CSV file handling.
|
|
* **Methods**:
|
|
* `static CsvReader CreateCsvReader(string filename)`: Creates a `CsvReader` using `CultureInfo.InvariantCulture`.
|
|
* `static List<string> ReadFields(CsvReader csvReader, bool readNextLine = true)`: Reads fields from the current/next line into a trimmed string list.
|
|
|
|
#### `GroupHelper`
|
|
Static utility methods for group and sensor data manipulation during import.
|
|
* **Methods**:
|
|
* `static IGroup CreateEmptyGroup()`: Returns a new `GroupList.Model.Group`.
|
|
* `static void GetTestSensorParameters(...)`: Resolves sensor parameters (ISO code, channel names, etc.) using `ParseParameters` overrides.
|
|
* `static IReadOnlyDictionary<string, int> GetDAS(...)`: Maps DAS serial numbers to DAS IDs.
|
|
* `static List<SensorData> CleanUneededSensorDataPlaceHolder(...)`: Removes sensors with specific prefixes or invalid calibrations.
|
|
* `static List<SensorData> NormalizeSensorIds(List<SensorData> sensorList)`: Assigns temporary negative IDs to new sensors or existing DB IDs.
|
|
|
|
#### `ImportError`
|
|
Represents a single error or warning during import.
|
|
* **Properties**:
|
|
* `string Message`
|
|
* `ImportSeverityError Severity`
|
|
* `bool ContinueImportOnError` (default: `true`)
|
|
|
|
#### `ImportStatus`
|
|
Represents the current status of the import operation.
|
|
* **Properties**: `string Status`, `PossibleStatus PossibleStatus`, `ImportExtraStatus ExtraStatus`.
|
|
|
|
#### `TsetSetupImportSensorInfo`
|
|
Sealed class holding sensor mapping details for test setup imports.
|
|
* **Constructors**: Accepts full details or partial (serial number, ISO code).
|
|
* **Properties**: `SerialNumber`, `IsoCode`, `IsoChannelName`, `UserCode`, `UserChannelName`, `DASSerialNumber`, `DASChannelIndex`, `GroupType`.
|
|
|
|
### Enums
|
|
* `ImportSeverityError`: `Critical`, `Error`, `Warning`, `Info`.
|
|
|
|
## 3. Invariants
|
|
* **ImportError Defaults**: By default, `ImportError.ContinueImportOnError` is `true`.
|
|
* **ID Normalization**: In `GroupHelper.NormalizeSensorIds`, new sensors (not found in `SensorsCollection`) are assigned temporary negative IDs starting at -2 (-1 is reserved for "no sensor").
|
|
* **Progress Calculation**: In `XMLParseProcessor`, progress is calculated as a ratio of total imported items (Calibrations + Sensors + Groups, etc.) to `itemsToComplete`. Progress is capped at 1.0.
|
|
* **CSV Reading**: `CsvUtil.ReadFields` always trims whitespace from retrieved fields.
|
|
* **ImportObject References**: `ParseProcessor` and `XMLParseProcessor` pass `ImportObject` by reference (`ref`) to `IParseVariant.Parse`, suggesting the object instance itself might be swapped or modified in place by parsers.
|
|
|
|
## 4. Dependencies
|
|
|
|
### Internal Dependencies
|
|
* `DTS.Common.Import.Interfaces`: Used by `ParseProcessor` and `GroupHelper` (`IParseVariant`, `ParseParameters`).
|
|
* `DTS.Common.Import.Enums`: Used by `ImportNotification` and `XMLParseProcessor` (`PossibleStatus`, `ImportExtraStatus`).
|
|
* `DTS.Common.Utils`: Used by `XMLParseProcessor` (specifically `XmlParserFactory` and `XMLUtils`).
|
|
* `DTS.Common.Classes.Sensors`: Used for `SensorCalibration`, `CalibrationRecord`, `ZeroMethod`.
|
|
* `DTS.Common.Enums`: Used for `ExcitationVoltageOptions`, `ZeroMethodType`.
|
|
* `DTS.Common.Interface.Sensors`: Used for `ISensorData`, `ICalibrationRecord`.
|
|
* `DTS.SensorDB`: Used for `SensorData`, `DASHardware`, `SensorsCollection`, `SensorCalibrationList`.
|
|
* `DataPROWin7.DataModel`: Used for `TestTemplate`, `TestObject`, `TestObjectTemplate`.
|
|
* `DTS.Slice.Users`: Used for `User` class.
|
|
* `DTS.Common.ISO`: Used for `CustomerDetails`, `TestEngineerDetails`, `LabratoryDetails`.
|
|
|
|
### External Dependencies
|
|
* `CsvHelper`: Used in `CsvUtil` for CSV parsing.
|
|
|
|
## 5. Gotchas
|
|
|
|
* **Potential Bug in `ImportObject.AssignSensorModelLookup`**: The method accepts a `Dictionary<string, List<SensorCalibration>>` argument named `calibrationLookup` but ignores it completely, initializing `_sensorModelLookup` to an empty dictionary instead. This appears to be a copy-paste error.
|
|
* **Silent Failures in `ImportObject.GetSensorLookup`**: If duplicate sensors (same `DatabaseId`) are found, the method writes to `System.Diagnostics.Trace.WriteLine` rather than throwing an |