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

---
source_files:
  - Common/DTS.Common.Import/Interfaces/IPersistImport.cs
  - Common/DTS.Common.Import/Interfaces/IParseImport.cs
  - Common/DTS.Common.Import/Interfaces/IParseVariant.cs
  - Common/DTS.Common.Import/Interfaces/IParseCSVTest.cs
  - Common/DTS.Common.Import/Interfaces/IParseCSVSensor.cs
  - Common/DTS.Common.Import/Interfaces/ICalibrationImport.cs
  - Common/DTS.Common.Import/Interfaces/ILockImport.cs
  - Common/DTS.Common.Import/Interfaces/IGroupImport.cs
generated_at: "2026-04-16T02:07:53.745184+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "4d7a3572ba82cd30"
---

# Interfaces

## Documentation: `DTS.Common.Import` Module

---

### 1. Purpose  
This module provides a structured, interface-driven abstraction layer for importing and persisting test and sensor configuration data—specifically supporting CSV-based import workflows. It defines contracts for parsing raw import files into a canonical `ImportObject`, handling variant-specific parsing logic, managing calibration and group creation, and enforcing database-level locking during import operations. Its role is to decouple import *logic* (e.g., CSV parsing, calibration application, group assignment) from *implementation* (e.g., concrete CSV readers, database access), enabling versioned, testable, and maintainable import pipelines.

---

### 2. Public Interface  

| Interface | Method/Property | Signature | Behavior |
|-----------|-----------------|-----------|----------|
| **`IPersistImport`** | `Save` | `void Save();` | Persists the current state of the `ImportObject` (or associated data) to persistent storage (e.g., database). No parameters; no return value. |
| **`IParseImport`** | `Parse` | `ImportObject Parse(IEnumerable<string> importFiles);` | Parses one or more import files (e.g., CSVs) and returns a fully populated `ImportObject`. Input is a collection of file paths/URIs. |
| **`IParseVariant`** | `FileName` | `string FileName { get; set; }` | Gets or sets the name of the file this variant parser is responsible for. |
| | `Parse` | `void Parse(ref ImportObject importObject);` | Modifies the provided `ImportObject` in-place using data specific to this variant (e.g., test setup, sensor metadata). |
| **`IParseCSVTest`** | `Version` | `int Version { get; }` | Gets the version number this parser supports (e.g., for versioned CSV formats). |
| | `ParseVersion` | `void ParseVersion(CsvReader csvReader, TestSetupImportData tsid);` | Parses version-specific test setup data from a `CsvReader` into the provided `TestSetupImportData` instance. |
| **`IParseCSVSensor`** | `Version` | `int Version { get; }` | Gets the version number this sensor parser supports. |
| | `Initialize` | `void Initialize(ICalibrationImport import, ZeroMethodOptions zmOptions, IImportNotification importNotification, bool importCreateDynamicGroups, bool useIsoCodeFilterMapping, bool useZeroForUnfiltered);` | Configures the parser with dependencies and options required for sensor parsing (e.g., calibration, zero method, group creation behavior). |
| | `ParseVersion` | `void ParseVersion(CSVImportTags.Tags field, string val, ParseParameters pp);` | Parses a single field (`field`) and its value (`val`) into the `ParseParameters` context. Used for incremental sensor data parsing. |
| **`ICalibrationImport`** | `AddLinearCalRecordIfNeeded` | `SensorCalibration AddLinearCalRecordIfNeeded(SensorCalibration sc, bool savedIsProportional, bool savedRemoveOffset);` | Conditionally adds a linear calibration record to `sc` based on `savedIsProportional` and `savedRemoveOffset`. Returns the (possibly modified) `SensorCalibration`. |
| | `AddLinearZeroMethodIfNeeded` | `SensorCalibration AddLinearZeroMethodIfNeeded(SensorCalibration sc, ZeroMethodType zeroMethodType, double zeroMethodStart, double zeroMethodEnd);` | Conditionally adds a linear zero method (e.g., offset, span) to `sc`. Returns the (possibly modified) `SensorCalibration`. |
| | `CheckForExcitationCalibration` | `SensorCalibration CheckForExcitationCalibration(SensorCalibration sc, double sensitivity, ExcitationVoltageOptions.ExcitationVoltageOption excitation, string EU);` | Applies excitation-specific calibration adjustments to `sc` if applicable. Returns the (possibly modified) `SensorCalibration`. |
| **`ILockImport`** | `Contended` | `bool Contended { get; }` | Indicates whether the lock collection contains any items (i.e., whether contention exists). |
| | `SetLock` | `void SetLock(ref ImportObject importObject, ref StringBuilder message);` | Attempts to acquire a database lock for the given `importObject`. Errors (if any) are appended to `message`. |
| | `FreeLock` | `void FreeLock(ref ImportObject importObject);` | Releases the database lock previously acquired for `importObject`. |
| | `StealLock` | `bool StealLock(bool proceed);` | Attempts to forcibly acquire (steal) the lock. Returns `true` on success. `proceed` likely controls whether to proceed despite warnings. |
| **`IGroupImport`** | `ParseParameters` | `ParseParameters ParseParameters { get; set; }` | Gets or sets the shared parsing context used during group creation. |
| | `CreateGroups` | `Tuple<TestTemplate, List<IGroup>> CreateGroups(List<SensorData> sensors, Dictionary<string, List<TsetSetupImportSensorInfo>> groupSensorLookup, TestTemplate testTemplate, bool createDynamicGroups, List<IGroup> staticGroups, Action<double> setProgress);` | Creates groups (static and/or dynamic) from sensor data. Returns a tuple of the updated `TestTemplate` and list of created `IGroup` instances. `setProgress` enables progress reporting. |
| | `GetGroupSensorLookup` | `Dictionary<string, List<TsetSetupImportSensorInfo>> GetGroupSensorLookup(List<SensorData> sensors, Dictionary<string, string> sensorGroupNameLookup, Dictionary<string, List<string>> groupNameSensorListLookup);` | Builds a mapping from group names to their associated sensor info (`TsetSetupImportSensorInfo`) using precomputed lookup dictionaries. |

---

### 3. Invariants  

- **`ImportObject` is the canonical data carrier**: All parsing interfaces (`IParseImport`, `IParseVariant`, `IParseCSVTest`, `IParseCSVSensor`) operate on or modify an `ImportObject` (or its subcomponents like `TestSetupImportData`). This object must be fully initialized before `IPersistImport.Save()` is called.
- **Versioned parsing is mandatory**: All CSV-specific parsers (`IParseCSVTest`, `IParseCSVSensor`) expose a `Version` property, implying that parsing logic must be version-aware and only process data matching its declared version.
- **`ParseParameters` is shared context**: `IGroupImport.ParseParameters` must be set consistently across all parsing steps that influence group creation (e.g., by `IParseCSVSensor.Initialize` or prior parsing steps).
- **Locking is explicit and paired**: `ILockImport.SetLock` and `ILockImport.FreeLock` must be called in matched pairs (or `StealLock` used appropriately) to avoid deadlocks or orphaned locks. The `message` parameter in `SetLock` is *mutated* and must be checked after each call.
- **Calibration is applied incrementally**: `ICalibrationImport` methods modify `SensorCalibration` in-place and return the same instance (or a new one), but callers must ensure methods are invoked in the correct order (e.g., zero method before excitation calibration if dependencies exist).

---

### 4. Dependencies  

**Imports/uses from this module:**
- `DTS.Common.Import` namespace (obvious).
- `DTS.Common.Classes` (e.g., `TestSetupImportData`, `ParseParameters`).
- `DTS.Common.Enums`, `DTS.Common.Enums.Sensors` (e.g., `ZeroMethodType`, `ExcitationVoltageOption`).
- `DTS.SensorDB` (e.g., `SensorCalibration`, `SensorData`).
- `CsvHelper` (for `CsvReader` in `IParseCSVTest`).
- `DataPROWin7.DataModel` (e.g., `TestTemplate` in `IGroupImport`).
- `DTS.Common.Interface.Groups.GroupList` (e.g., `IGroup` in `IGroupImport`).

**Depended upon by (inferred):**
- Any concrete import pipeline (e.g., a `CsvImportService` or `ImportController`) that implements `IParseImport` and orchestrates `IParseVariant`, `IParseCSVSensor`, `ICalibrationImport`, `IGroupImport`, and `ILockImport`.
- Database persistence layers (implementing `IPersistImport`).
- Test setup or sensor configuration UIs that validate or preview imports (using `IParseCSVTest`, `IParseCSVSensor`).

---

### 5. Gotchas  

- **`ref` parameters in `ILockImport` and `IParseVariant.Parse`**: Both `SetLock(ref ImportObject, ref StringBuilder)` and `Parse(ref ImportObject)` use `ref`, meaning the callee may reassign the object reference. Callers must ensure variables are not boxed or copied before passing.
- **`FileName` in `IParseVariant` is mutable but not validated**: The setter allows arbitrary strings; no validation or normalization is guaranteed. Callers must ensure filenames match expected patterns (e.g., case, extensions).
- **`IParseCSVSensor.Initialize` has many flags**: The `Initialize` method accepts 6 parameters, including boolean toggles (`importCreateDynamicGroups`, `useIsoCodeFilterMapping`, `useZeroForUnfiltered`). Misconfiguring these may lead to silent misbehavior (e.g., groups not created, filters ignored).
- **`IGroupImport.CreateGroups` progress reporting is optional**: The `setProgress` parameter is an `Action<double>`—callers may pass `null`, but implementations may assume it’s non-null and throw `NullReferenceException` if not handled.
- **No explicit error handling in interfaces**: None of the interfaces declare exceptions. Implementations may throw (e.g., `CsvHelper` parsing errors), but callers must rely on outer try/catch blocks.
- **`ILockImport.StealLock` behavior is underspecified**: The `proceed` parameter’s semantics (e.g., user prompt, forced override) are not documented in the interface. Implementation-specific behavior may vary.
- **`TsetSetupImportSensorInfo` typo in `IGroupImport`**: The parameter name `groupSensorLookup` and return type use `TsetSetupImportSensorInfo` (likely a typo for `TestSetupImportSensorInfo`). Verify actual type name in implementation.

> **Note**: Several types referenced (e.g., `ImportObject`, `ParseParameters`, `SensorData`, `TsetSetupImportSensorInfo`, `CSVImportTags.Tags`) are not defined in the provided source files. Their structure and behavior must be inferred from usage or consulted in other modules.