DP44/enriched-qwen3-coder-next/Common/DTS.Common.Import.md

---
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