init
This commit is contained in:
@@ -0,0 +1,115 @@
|
||||
---
|
||||
source_files:
|
||||
- DataPRO/Modules/DatabaseImporter/DatabaseImport/Controls/SensorsAndModels/ImportSensorsImportControl.cs
|
||||
generated_at: "2026-04-16T04:33:13.762411+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "f5ef3c2722125dc9"
|
||||
---
|
||||
|
||||
# SensorsAndModels
|
||||
|
||||
## Documentation: `ImportSensorsImportControl` Module
|
||||
|
||||
---
|
||||
|
||||
### 1. **Purpose**
|
||||
|
||||
This module provides utility functions for resetting or clearing large swaths of persistent application state—both in-memory collections and database records—prior to importing sensor and model data from an external source (e.g., a TDM export or database import). Its primary role is to ensure a clean state before data ingestion by deleting all non-essential data, including test templates, test objects, sensors, calibrations, users, UI items, tags, and legacy database versions. It is used exclusively during import workflows and is tightly coupled with database operations and legacy data structures.
|
||||
|
||||
---
|
||||
|
||||
### 2. **Public Interface**
|
||||
|
||||
#### `public static void ClearAllTables(bool clearForDbImport)`
|
||||
|
||||
- **Behavior**: Clears all in-memory collections (via `DeleteAll()` calls on static list/collection types) and, if `clearForDbImport` is `true`, also clears corresponding database tables and related entities.
|
||||
- **In-memory deletions include**:
|
||||
- `TestTemplateList.TestTemplatesList`
|
||||
- `TestObjectList.AddedGroupsList`
|
||||
- `TestObjectList.TestObjectsList` *(deleted twice per comment)*
|
||||
- `CustomChannelList.List`
|
||||
- `SensorsCollection.SensorsList`
|
||||
- `SensorModelCollection.SensorModelList`
|
||||
- `SensorCalibrationList`
|
||||
- `CustomerDetailsList`
|
||||
- `LabratoryDetailsList`
|
||||
- `TestEngineerDetailsList`
|
||||
- **Database deletions (only if `clearForDbImport == true`)**:
|
||||
- Non-prototype DAS tables via `DTS.Common.Storage.DbOperations.ClearNonPrototypeDas()`
|
||||
- `LockedItems` table
|
||||
- All users (via stored procedure `sp_UserDelete`)
|
||||
- All UI items (via `sp_UIItemsDelete`)
|
||||
- All tags (via `sp_TagsDelete`)
|
||||
- All database versions older than `DbOperations.CURRENT_DB_VERSION` (via `sp_DbVersionDelete`)
|
||||
|
||||
---
|
||||
|
||||
### 3. **Invariants**
|
||||
|
||||
- **Ordering**: The in-memory `DeleteAll()` calls must precede database operations to avoid stale references or orphaned data in memory.
|
||||
- **Dependency on `clearForDbImport`**: If `false`, *no database operations* are performed. All database-clearing logic is guarded by this flag.
|
||||
- **Assumption about prior state**:
|
||||
- `ClearAllUsers()` must be called before `ClearAllUIItems()` because UI items depend on user metadata (per comment: *"We're assuming that all of the UIItemSettings and Users are already deleted"*).
|
||||
- Similarly, `ClearAllUsers()` is assumed to delete `TagAssignments` before `ClearAllTags()` runs.
|
||||
- **Versioning invariant**: Only database versions `< DbOperations.CURRENT_DB_VERSION` are deleted; the current version and newer versions are preserved.
|
||||
|
||||
---
|
||||
|
||||
### 4. **Dependencies**
|
||||
|
||||
#### **Internal Dependencies**
|
||||
- Static collections:
|
||||
- `TestTemplateList.TestTemplatesList`
|
||||
- `TestObjectList.AddedGroupsList`, `TestObjectList.TestObjectsList`
|
||||
- `CustomChannelList.List`
|
||||
- `SensorsCollection.SensorsList`
|
||||
- `SensorModelCollection.SensorModelList`
|
||||
- `SensorCalibrationList`
|
||||
- `CustomerDetailsList`, `LabratoryDetailsList`, `TestEngineerDetailsList`
|
||||
- `DTS.Common.Storage.DbOperations` (for `ClearNonPrototypeDas()`)
|
||||
- `DbOperations` class (for SQL command generation, connection handling, and stored procedure names)
|
||||
- `DbOperationsEnum.StoredProcedure` enum (used to resolve stored procedure names like `sp_UserDelete`, `sp_UIItemsGet`, etc.)
|
||||
- `Tags.Tag` class (used to parse rows from `sp_TagsGet`)
|
||||
- `DbOperations.Users`, `DbOperations.Users.UserFields`, `DbOperations.Users.UIItemFields`, `DbOperations.DbVersions`, `DbOperations.DbVersions.DbVersionFields` (static field/enum types for column access)
|
||||
|
||||
#### **External Dependencies**
|
||||
- `System.Data.SqlClient` (for `SqlCommand`, `SqlParameter`, `SqlDbType`, etc.)
|
||||
- `System.Data` (for `DataSet`, `DataRow`, `CommandType`)
|
||||
- WPF `UserControl` base class (though `ImportSensorsImportControl` is a UI control, this module’s public method is static and does not rely on UI state)
|
||||
|
||||
#### **Dependents**
|
||||
- Likely invoked by higher-level import logic (e.g., `DatabaseImporter` or `DataImportViewModel`) before populating the cleared state with new data.
|
||||
|
||||
---
|
||||
|
||||
### 5. **Gotchas**
|
||||
|
||||
- **Double deletion of `TestObjectsList`**:
|
||||
`TestObjectList.TestObjectsList.DeleteAll()` is called twice with a comment indicating “we keep two copies of the list around”—a strong signal of legacy duplication or refactoring debt.
|
||||
|
||||
- **Stored procedure usage is environment-specific**:
|
||||
Comments explicitly state that `sp_UserDelete` and `sp_UserGet` are *only used in `DataPROPre20.mdf`*, not `DataPRO.mdf`. This implies the module may behave incorrectly or throw if run against newer database schemas.
|
||||
|
||||
- **Error handling is silent**:
|
||||
In `ClearAllUsers()`, `ClearAllUIItems()`, `ClearAllTags()`, and `ClearAllExceptCurrentDbVersion()`, errors returned via `@errorNumber` are *not logged or propagated*—only commented out (`//errorMessageParam.Value`). This could mask failures during deletion.
|
||||
|
||||
- **Assumption of deletion order**:
|
||||
`ClearAllUsers()` must run before `ClearAllUIItems()` and `ClearAllTags()` due to foreign key or logical dependencies, but this ordering is *not enforced programmatically*—it relies on caller discipline.
|
||||
|
||||
- **`GetAllUIItemIds()` uses `DbOperations.Users.UIItemFields.ID`**:
|
||||
This suggests a possible naming inconsistency or reuse of user-related field enums for UI items, which could be confusing.
|
||||
|
||||
- **`GetAllUsers()` returns all columns as `string[]`**:
|
||||
The method returns raw string arrays with fixed column order (id, username, etc.), making it fragile to schema changes. No type safety or schema validation is applied.
|
||||
|
||||
- **Resource disposal pattern is manual**:
|
||||
All `SqlCommand` objects use `try/finally` to dispose connections manually. While correct, this is error-prone and could be replaced with `using` blocks for clarity and safety.
|
||||
|
||||
- **No transactional safety**:
|
||||
Database deletions are executed in separate commands without an explicit transaction. A failure mid-way (e.g., after deleting users but before deleting tags) could leave the database in a partially cleared state.
|
||||
|
||||
- **`ClearAllExceptCurrentDbVersion()` deletes *older* versions only**:
|
||||
The logic skips versions `>= CURRENT_DB_VERSION`, but does *not* delete newer versions (e.g., if `CURRENT_DB_VERSION` is updated post-deployment). This may be intentional for forward compatibility, but could lead to stale schema data if not managed carefully.
|
||||
|
||||
---
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
source_files:
|
||||
- DataPRO/Modules/DatabaseImporter/DatabaseImport/Controls/TestSetups/ImportTestSetup.cs
|
||||
generated_at: "2026-04-16T04:33:34.717126+00:00"
|
||||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||||
schema_version: 1
|
||||
sha256: "c54de3e2daf5d6b9"
|
||||
---
|
||||
|
||||
# TestSetups
|
||||
|
||||
### **Purpose**
|
||||
The `ImportTestSetup` class is a WPF `UserControl` responsible for parsing and importing structured XML data representing test setup configurations (including sensors, calibrations, hardware, groups, and custom MME metadata) into the system’s database via stored procedures. It acts as the core ingestion layer for legacy or exported test setup files, supporting versioned import logic (v1.0 and v2.0) and maintaining in-memory collections of imported entities prior to database persistence. Its role is to translate XML fragments into domain objects and orchestrate their bulk insertion into the database while preserving data integrity and handling version-specific transformations.
|
||||
|
||||
---
|
||||
|
||||
### **Public Interface**
|
||||
|
||||
#### **Static Fields (Publicly Exposed Collections)**
|
||||
These collections hold imported data *before* it is persisted to the database. They are populated during XML processing and cleared by `Cleanup()`.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `Directions` | `List<MMEDirections>` | Custom MME direction definitions imported from XML. |
|
||||
| `FilterClasses` | `List<MMEFilterClasses>` | Custom MME filter class definitions. |
|
||||
| `FineLoc1s` | `List<MMEFineLocations1>` | First-level fine location definitions. |
|
||||
| `FineLoc2s` | `List<MMEFineLocations2>` | Second-level fine location definitions. |
|
||||
| `FineLoc3s` | `List<MMEFineLocations3>` | Third-level fine location definitions. |
|
||||
| `MainLocs` | `List<MMETransducerMainLocation>` | Transducer main location definitions. |
|
||||
| `TestObjects` | `List<MMETestObjects>` | Custom test object definitions. |
|
||||
| `PhysicalDimensions` | `List<MMEPhysicalDimensions>` | Physical dimension definitions. |
|
||||
| `Positions` | `List<MMEPositions>` | Position definitions. |
|
||||
| `Calibrations` | `List<SensorCalibration>` | Sensor calibration history records. |
|
||||
| `CustomerDetails` | `List<ISO.CustomerDetails>` | Customer metadata imported from XML. |
|
||||
| `LabDetails` | `List<ISO.LabratoryDetails>` | Laboratory metadata imported from XML. |
|
||||
| `Sensors` | `List<SensorData>` | Sensor definitions (note: declared `public static readonly`, but no direct population logic visible in this file—likely populated via `ImportElement` → stored procedure). |
|
||||
| `_testSetups` | `List<TestTemplate>` | Test setup templates (note: declared `public static`, not `readonly`). |
|
||||
| `_sensorsWithDuplicateIds` | `List<SensorData>` | Internal tracking for sensors with duplicate IDs (not exposed publicly). |
|
||||
|
||||
#### **Static Methods**
|
||||
|
||||
| Method | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `ProcessRootNode` | `public static void ProcessRootNode(string name, string outerXML, DbImporter.SetStatusDelegate SetStatus)` | Dispatches XML fragment processing based on `name` (e.g., `"SensorData"`, `"TestSetup"`). Maps element names to corresponding stored procedures and invokes `ImportElement`. Does *not* handle `DbVersion` or `SensorCalibration` directly—those have dedicated logic elsewhere (see `ImportCalibrations`). |
|
||||
| `ImportElement` | `private static void ImportElement(string storedProcedure, string storedProcedureParameter, string outerElementName, string outerXML)` | Wraps `outerXML` in `<outerElementName>...</outerElementName>`, executes the specified stored procedure with the XML as an `@parameter`, and captures output error info. Throws on failure. Does *not* log or handle errors beyond re-throwing. |
|
||||
| `GetTestSetupName` | `private static string GetTestSetupName(string outerXML)` | Extracts `SetupName` from `<TestSetup/Fields/SetupName>` in `outerXML` using `XmlDocument`. Returns `null` if not found. |
|
||||
| `Cleanup` | `private static void Cleanup()` | Clears *all* static collections listed above (including `_sensorsWithDuplicateIds`, `_globalSettings`, `_customChannels`, etc.). Resets state for a new import session. |
|
||||
|
||||
#### **Nested Types (Referenced)**
|
||||
- `PossibleStatus` enum: Defines UI states (`Waiting`, `Working`, `Done`, `Failed`).
|
||||
- `DbOperationsEnum.StoredProcedure`: Used to resolve stored procedure names (e.g., `sp_DBImportSensors`).
|
||||
- `SensorCalibration`, `SensorData`, `TestTemplate`, `DASHardware`, `User`, `TestObject`, etc.: Domain types imported via XML or stored procedures.
|
||||
|
||||
> **Note**: `ProcessRootNode` does *not* handle `SensorCalibration` or `DbVersion`—those are processed separately (implied by `ImportCalibrations` method and `_importedVersion` usage). `DbVersion` is imported via `ImportElement`, but `_importedVersion` is set elsewhere (not shown here).
|
||||
|
||||
---
|
||||
|
||||
### **Invariants**
|
||||
|
||||
1. **XML Structure**:
|
||||
- `outerXML` passed to `ProcessRootNode` must be a well-formed XML fragment corresponding to the expected schema for the given `name` (e.g., `<SensorData>...</SensorData>`).
|
||||
- `GetTestSetupName` assumes `outerXML` contains a `<TestSetup>` root with a `<Fields>` child containing `<SetupName>`.
|
||||
|
||||
2. **Version Handling**:
|
||||
- `_importedVersion` (private) must be set *before* `ImportCalibrations` is called (not shown in this file).
|
||||
- Calibration import logic diverges based on `_importedVersion == 1.0D` or `2.0D`. Version 1.0 applies transformations (e.g., setting `SensitivityUnits`, `AtCapacity = false`).
|
||||
|
||||
3. **Database Interaction**:
|
||||
- All `ImportElement` calls use stored procedures with XML parameters.
|
||||
- Stored procedure output parameters `@errorNumber` and `@errorMessage` are captured but only checked for non-zero `@errorNumber`; error messages are *not* propagated or logged in this method.
|
||||
- Command timeout is fixed at 60 seconds.
|
||||
|
||||
4. **State Management**:
|
||||
- `Cleanup()` must be called before a new import to reset all static collections.
|
||||
- `_sensorsWithDuplicateIds` is populated elsewhere (not visible here) but is cleared on `Cleanup()`.
|
||||
|
||||
---
|
||||
|
||||
### **Dependencies**
|
||||
|
||||
#### **Internal Dependencies**
|
||||
- **Types**:
|
||||
- `DbOperations` (provides `GetSQLCommand` and `SetStatusDelegate`).
|
||||
- `DbOperationsEnum.StoredProcedure` (for stored procedure names).
|
||||
- `ISO.CustomerDetails`, `ISO.LabratoryDetails`, `SensorCalibration`, `SensorData`, `TestTemplate`, `DASHardware`, `User`, `TestObject`, `MME*` types (e.g., `MMEDirections`, `MMEPossibleChannels`).
|
||||
- `Test.Module.Channel.Sensor.SensUnits` (used in `ImportCalibrations` for v1.0 transformations).
|
||||
- **XAML**: `ImportTestSetup.xaml` (interaction logic partial class).
|
||||
|
||||
#### **External Dependencies**
|
||||
- **.NET Framework**: `System.Data`, `System.Data.SqlClient`, `System.Xml`, `System.Windows.Controls`.
|
||||
- **Database**: SQL Server (via stored procedures named `sp_DBImport*`).
|
||||
- **Calling Code**: `DbImporter.SetStatusDelegate` (likely from `DbImporter` class) for status reporting.
|
||||
|
||||
#### **Depended Upon**
|
||||
- Likely invoked by `DbImporter` (or similar orchestrator) during XML parsing of an import file.
|
||||
- Public static fields are consumed by downstream logic (e.g., UI binding, final commit to DB).
|
||||
|
||||
---
|
||||
|
||||
### **Gotchas**
|
||||
|
||||
1. **Static State Management**:
|
||||
- All data is held in *static* collections. This makes the class **not thread-safe** and unsuitable for concurrent imports without external synchronization.
|
||||
- `Cleanup()` must be called explicitly before each import; otherwise, stale data persists across sessions.
|
||||
|
||||
2. **Incomplete Error Handling**:
|
||||
- `ImportElement` captures `@errorNumber` and `@errorMessage` but *does nothing* with them (commented-out error handling block). Errors are silently ignored unless an exception is thrown.
|
||||
- `ProcessRootNode` does *not* handle `SensorCalibration` or `DbVersion`—these require separate processing logic (implied by `ImportCalibrations` and `_importedVersion` usage), which is not visible here.
|
||||
|
||||
3. **Version-Specific Logic Fragility**:
|
||||
- Calibration import for v1.0 assumes exactly one calibration record (`sc.Records.Records[0]`). If the schema changes, this will throw `IndexOutOfRangeException`.
|
||||
- `_importedVersion` is set elsewhere (not in this file), creating a hidden dependency.
|
||||
|
||||
4. **XML Parsing Assumptions**:
|
||||
- `GetTestSetupName` uses `SelectSingleNode` without null-checking beyond the null-conditional operator. If `SetupName` is missing, it returns `null`—callers must handle this.
|
||||
- `outerXML` is naively wrapped in `<outerElementName>...</outerElementName>`. If `outerXML` already contains a root element, this produces invalid XML.
|
||||
|
||||
5. **Naming Inconsistencies**:
|
||||
- `LabDetails` uses `LabratoryDetails` (misspelled) in the type name (`ISO.LabratoryDetails`).
|
||||
- `_testSetups` is `public static List<TestTemplate>`, while other collections (e.g., `Calibrations`) are `readonly`. This suggests `_testSetups` may be reassigned elsewhere.
|
||||
|
||||
6. **No Version Validation**:
|
||||
- No explicit check ensures `_importedVersion` matches `CurrentVersion` (2.0). Mismatched versions may cause silent data loss or corruption.
|
||||
|
||||
7. **Unused/Commented Code**:
|
||||
- `ProcessRootNode` contains commented-out `CancelCheck` calls and `page` parameters, suggesting legacy cancellation UI support that is no longer active.
|
||||
- The `//Store the compressed binary copy...` comment in the `"TestSetup"` case indicates incomplete or deprecated functionality.
|
||||
|
||||
> **None identified from source alone** for thread-safety, serialization, or external API contracts—these require examining `DbImporter` and related types.
|
||||
Reference in New Issue
Block a user