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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T02:07:53.745184+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.