171 lines
11 KiB
Markdown
171 lines
11 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/Modules/DatabaseImporter/DatabaseImport/CustomChannel.cs
|
||
- DataPRO/Modules/DatabaseImporter/DatabaseImport/TestGraph.cs
|
||
- DataPRO/Modules/DatabaseImporter/DatabaseImport/SerializedSettings.cs
|
||
- DataPRO/Modules/DatabaseImporter/DatabaseImport/DbImporter.cs
|
||
generated_at: "2026-04-16T04:28:50.017817+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "35545dbb44d8a4ab"
|
||
---
|
||
|
||
# Documentation: Database Import Module
|
||
|
||
## 1. Purpose
|
||
|
||
This module provides functionality for importing database content from XML files and managing custom channels and test graphs within the DataPRO system. It serves as the core data ingestion layer for migrating legacy or external test configurations into the application’s internal database schema, while supporting both ISO 13499-standardized and user-defined (custom) channels. The module enables safe, structured population of database tables—including sensors, calibrations, test objects, and custom definitions—without disrupting existing ISO-defined data, and includes specialized handling for hardware-specific migrations (e.g., TDAS G5 VDS, SPS) and per-user setting inheritance.
|
||
|
||
## 2. Public Interface
|
||
|
||
### `CustomChannel` class
|
||
|
||
- **`public MMEPossibleChannels Channel { get; }`**
|
||
The underlying ISO channel definition wrapped by this custom channel. Immutable after construction.
|
||
|
||
- **`public string Text1 { get; set; }`**
|
||
Exposes `Channel.Text_L1` via a property setter that delegates to `Channel.SetText1(value)`. Used for user-facing display name.
|
||
|
||
- **`public CustomChannel(MMEPossibleChannels channel, bool newChannel = true)`**
|
||
Constructor. If `newChannel` is `true`, creates a copy of the input `channel`; otherwise uses the reference directly. Initializes private fields (`_direction`, `_filterClass`, `_finLoc1`, etc.) by querying `IsoDb` via `App.IsoDb` methods. Catches and stores `ISO13499FileDb.ExpiredISOFieldException` for expired ISO fields (e.g., main location) in `_expiredErrors`.
|
||
|
||
- **`public int CompareTo(CustomChannel other)`**
|
||
Implements `IComparable<CustomChannel>`. Returns `0` if references are equal; otherwise compares `Text1` values using ordinal string comparison.
|
||
|
||
### `CustomChannelList` class (singleton)
|
||
|
||
- **`public static CustomChannelList List { get; }`**
|
||
Thread-safe singleton accessor. Uses double-checked locking with `LockObject`.
|
||
|
||
- **`public void ReloadAll()`**
|
||
Clears cached channel lists (`_listChannels`, `_dictChannels`), refreshes all ISO data via `IsoDb.RefreshAllData()`, and repopulates channels via `PopulateChannelsIfNecessary()`.
|
||
|
||
- **`public void DeleteAll()`**
|
||
Clears cached lists and calls `IsoDb.DeleteSQL()` to delete all custom channels and related tables. Does *not* delete DAS tables (per comment).
|
||
|
||
- **`public ISO13499FileDb IsoDb { get; }`**
|
||
Lazy-initialized singleton for ISO database access. Instantiates `ISO13499FileDb`, calls `RefreshAllData()`, and caches the instance.
|
||
|
||
### `TestGraph` class
|
||
|
||
- **`public TestGraph(TestTemplate template)`**
|
||
Constructor. Initializes `_template`, `_groups`, and `_addedGroups` from `template.TestObjectsWithChannels` and `template.AddedGroups`.
|
||
|
||
- **`public void SetThresholdsFromSQL(string sThresholds)`**
|
||
Parses a semicolon-separated (`§`) string of numeric thresholds (braces `{}` stripped), adding valid doubles to `_thresholds`.
|
||
|
||
- **`public void SetChannelsFromSQL(string sChannels)`**
|
||
Parses a semicolon-separated (`§`) string of channel IDs (parentheses `()` stripped), looks up each ID in `AvailableChannels`, and adds matching channels via `AddChannel()`.
|
||
|
||
- **`public TestObjectChannel[] AvailableChannels { get; }`**
|
||
Returns up to `MAX_CHANNELS_PER_GRAPH` (8) available channels. Builds list by iterating `_groups` and `_addedGroups`, adding non-disabled, non-optional channels with valid sensor serial numbers. Special handling for SQUIB sensors: adds both current and voltage sub-channels if not already present. Returns `null` if any group fails to add channels (e.g., missing ISO test object). Sorts result before returning.
|
||
|
||
### `SerializedSettings` class (static, sealed)
|
||
|
||
- **`public enum Keys`**
|
||
Contains 100+ named keys for global settings (e.g., `IgnorePowerMode`, `RealtimeSampleRate`, `SLICE6_PowerSetting`, etc.).
|
||
|
||
- **`public static string ExportINIFile { get; set; }`**
|
||
Gets/sets the path of the export INI file via `SettingsDB.GetGlobalValue`/`SetGlobalValue`.
|
||
|
||
- **`public static IsoChannelSensorCompatibilityLevels IsoChannelSensorCompatibilityLevel { get; set; }`**
|
||
Gets/sets compatibility level (warn/error/etc.) for ISO channel-sensor mismatches. Defaults to `Warn`.
|
||
|
||
- **`public static ISOSupportLevels ISOSupportLevel { get; set; }`**
|
||
Gets/sets ISO support mode: `ISO_ONLY`, `TRANSITORY`, or `NO_ISO`. Defaults to `ISO_ONLY`.
|
||
|
||
- **`public static SensorTypeToDimension[] AllSensorTypeToDimensions { get; set; }`**
|
||
Gets/sets a list of sensor-type-to-ISO-dimension mappings (code, name, dimension). Stored as serialized strings in `SettingsDB` with index-based keys (`SENSORTYPE_0`, `SENSORTYPE_1`, …). Default includes 7 mappings (e.g., Acceleration → AC, Force → FO).
|
||
|
||
- **`public static Dictionary<string, string> GetAllSensorTypeToDimensionMappings()`**
|
||
Returns a dictionary mapping sensor type codes to ISO physical dimension codes.
|
||
|
||
- **`public static bool TestSetupDefaultDontAllowOutOfCalSensors { get; set; }`**
|
||
Gets/sets whether out-of-calibration sensors are disallowed by default in test setup.
|
||
|
||
### `DbImporter` class
|
||
|
||
- **`public DbImporter(int dbType, string dbName, string server, bool useNTLMAuthentication, string localDbUser, string localDbPassword)`**
|
||
Constructor. Configures `DbOperations.Connection` for local or centralized database access.
|
||
|
||
- **`public void ImportXML(string ImportFile, SetStatusDelegate SetStatus)`**
|
||
Imports database content from an XML file. Clears all tables via `ImportSensorsImportControl.ClearAllTables(true)`, then iterates XML elements mapping to `TopLevelFields` (e.g., `"CustomChannels"`, `"Sensors"`, `"Calibrations"`), calling `ImportTestSetup.ProcessRootNode` for each. Handles special post-import steps: `AssignSettingsToAllUsers()`, `MigrateG5ChannelSupportedBridges()`, `MigrateSPSChannelSupportedBridges()`.
|
||
|
||
- **`public bool MigrateG5ChannelSupportedBridges()`**
|
||
Fixes TDAS G5 VDS channel bridge compatibility by updating `DASChannels.SupportedBridges` from `12` to `140` for DAS IDs where `DAS.Type = 12`.
|
||
|
||
- **`public void MigrateSPSChannelSupportedBridges()`**
|
||
Fixes SPS channel bridge compatibility by updating `DASChannels.SupportedBridges` from `15` to `143` for DAS IDs where `DAS.Type = 19` and `ProtocolVersion >= 154`.
|
||
|
||
- **`public bool IsServerConnected()`**
|
||
Returns `DbOperations.IsServerConnected()`.
|
||
|
||
## 3. Invariants
|
||
|
||
- **`CustomChannel`**:
|
||
- `_expiredErrors` may contain `ISO13499FileDb.ExpiredISOFieldException` instances only for fields that failed during construction (e.g., main location), not for other fields.
|
||
- `Channel` is either a copy (if `newChannel == true`) or the original reference; never null after construction.
|
||
- `Text1` is always synchronized with `Channel.Text_L1`.
|
||
|
||
- **`CustomChannelList`**:
|
||
- `_listChannels` and `_dictChannels` are either both `null` or both fully populated and consistent (same channels, keyed by ISO code).
|
||
- Channel ISO codes (from `ISO.IsoCode.GetString(ch.Channel, false)`) are unique in `_dictChannels`.
|
||
- `List` is lazily initialized once per AppDomain; thread-safe via `lock`.
|
||
|
||
- **`TestGraph`**:
|
||
- `AvailableChannels` returns at most 8 channels.
|
||
- SQUIB channels are added as *two* distinct channels (current and voltage) only if not already present in the graph.
|
||
- `ContainsCurrentChannel` checks for both the channel itself and its current variant suffixed with `DTS.Common.Constants.CURRENT_SUFFIX`.
|
||
- `AvailableChannels` returns `null` if any group fails to contribute channels (e.g., missing ISO test object).
|
||
|
||
- **`SerializedSettings`**:
|
||
- `AllSensorTypeToDimensions` defaults to 7 mappings; index-based storage uses `(char)149` (`ō`) as delimiter.
|
||
- Settings values are stored as strings in `SettingsDB`; parsing may fall back to defaults on failure.
|
||
|
||
- **`DbImporter`**:
|
||
- `ImportXML` clears *all* tables before import (including custom tables).
|
||
- Post-import migrations (`MigrateG5ChannelSupportedBridges`, `MigrateSPSChannelSupportedBridges`) are unconditional and do not update DB version.
|
||
|
||
## 4. Dependencies
|
||
|
||
### Imports/References:
|
||
- `System`, `System.Collections.Generic`, `System.Linq`, `System.Xml`, `System.Data`, `System.Data.SqlClient`
|
||
- `System.Windows` (for `Application.Current`)
|
||
- `DTS.Common.Constants` (used in `TestGraph.ContainsCurrentChannel`)
|
||
- `Test.Module.Channel.Sensor` (for `BridgeType.SQUIB`)
|
||
- `SensorsCollection.SensorsList` (for `GetSensorBySerialNumber`)
|
||
- `ISO.IsoCode` (for `GetString`)
|
||
- `App` class (accessed via `Application.Current` for `IsoDb`)
|
||
- `ISO13499FileDb`, `MMEPossibleChannels`, `MMEPositions`, etc. (ISO-related enums/objects)
|
||
- `SettingsDB`, `DbOperations`, `DbOperationsEnum` (for settings and DB access)
|
||
- `ImportTestSetup`, `ImportSensorsImportControl` (external classes for XML processing)
|
||
|
||
### Depends on:
|
||
- `ISO13499FileDb` for ISO data lookup and persistence.
|
||
- `SettingsDB` for global and user-specific settings.
|
||
- `DbOperations` for SQL execution and connection management.
|
||
- `ImportTestSetup` and `ImportSensorsImportControl` for XML parsing and table population.
|
||
- `App` singleton for application-wide database and configuration access.
|
||
|
||
## 5. Gotchas
|
||
|
||
- **`CustomChannel`**:
|
||
- `_expiredErrors` is populated but never exposed or used elsewhere in the provided source—potential silent failure point.
|
||
- Constructor silently ignores failures for most fields (e.g., `_position`, `_testObject`) but only catches exceptions for `_mainLocation`. Other fields may throw or default silently.
|
||
|
||
- **`CustomChannelList`**:
|
||
- `ReloadAll()` calls `IsoDb.RefreshAllData()` *inside* the lock, which may block UI or other threads if refresh is slow.
|
||
- `DeleteAll()` clears `_listChannels` and `_dictChannels` *before* calling `IsoDb.DeleteSQL()`—if the DB call fails, the in-memory state is already corrupted.
|
||
|
||
- **`TestGraph`**:
|
||
- `AvailableChannels` returns `null` on *any* group failure, not just partial failure—this may be overly strict.
|
||
- SQUIB voltage channel reuses the original `channel` object (sets `SquibChannelType` and `NameOfTheChannel` in-place), which may cause side effects if the original channel is reused elsewhere.
|
||
|
||
- **`SerializedSettings`**:
|
||
- `AllSensorTypeToDimensions` uses `(char)149` as delimiter—non-standard and may break with different encodings or string operations.
|
||
- Default mappings are hardcoded in `GetSensorTypeMapping(int, string, string, string)`; changing defaults requires updating both the method and `AllSensorTypeToDimensions` setter logic.
|
||
|
||
- **`DbImporter`**:
|
||
- `ImportXML` clears *all* tables unconditionally—no backup is performed despite commented-out code.
|
||
- `MigrateG5ChannelSupportedBridges` and `MigrateSPSChannelSupportedBridges` are called unconditionally during import, even if not needed (e.g., non-migration imports).
|
||
- `AssignSettingsToAllUsers` silently swallows all exceptions—settings may fail to propagate without notification. |