97 lines
8.0 KiB
Markdown
97 lines
8.0 KiB
Markdown
|
---
|
||
|
|
source_files:
|
||
|
|
- Common/DTS.Common.Storage/SensorDB.cs
|
||
|
|
- Common/DTS.Common.Storage/LocalOnlyOperations.cs
|
||
|
|
- Common/DTS.Common.Storage/TestHistory.cs
|
||
|
|
- Common/DTS.Common.Storage/TypeConverter.cs
|
||
|
|
- Common/DTS.Common.Storage/MMETables.cs
|
||
|
|
- Common/DTS.Common.Storage/DatabaseServices.cs
|
||
|
|
- Common/DTS.Common.Storage/TestSetups.cs
|
||
|
|
- Common/DTS.Common.Storage/UserMigrationHelper.cs
|
||
|
|
generated_at: "2026-04-16T11:31:09.102777+00:00"
|
||
|
|
model: "zai-org/GLM-5-FP8"
|
||
|
|
schema_version: 1
|
||
|
|
sha256: "5cf7683c6017efd4"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Documentation: DTS.Common.Storage
|
||
|
|
|
||
|
|
## 1. Purpose
|
||
|
|
The `DTS.Common.Storage` namespace provides the data access layer, database schema definitions, and connection management utilities for the DTS DataPRO system. It bridges the application logic and the persistence layer (SQL Server and LocalDB). This module defines database schemas via constants and enums for Sensors, Test Setups, and MME (Measurement and Monitoring Equipment) tables, manages local/remote database connections, handles test history serialization, and provides utilities for type conversion and user data migration.
|
||
|
|
|
||
|
|
## 2. Public Interface
|
||
|
|
|
||
|
|
### `DTS.Common.Storage.DatabaseServices`
|
||
|
|
An abstract class providing static methods for database lifecycle management.
|
||
|
|
* `static void RestoreLocalDatabase(string defaultDbName)`: Restores the local database from `.BAK` files by stopping the LocalDB instance, copying files, and restarting the instance.
|
||
|
|
* `static void BackupLocalDatabase(string defaultDbName)`: Creates backups of the local database `.mdf` and `_log.ldf` files.
|
||
|
|
* `static int SetupLocal(string defaultDbName)`: Initializes the connection for a local database using `DbOperations`.
|
||
|
|
* `static int SetupLocal2(string defaultDbName)`: Initializes the connection for a local database using `LocalOnlyOperations`.
|
||
|
|
* `static int SetupForRemoteDb(string dbHost, bool userNTLMAuthentication, string user, string password, string defaultDbName)`: Configures the connection for a centralized remote SQL database.
|
||
|
|
* `static bool SimpleDbTest()`: Executes a simple query (`SELECT TOP 1 [DASId] FROM [DAS]`) to verify database connectivity.
|
||
|
|
|
||
|
|
### `DTS.Common.Storage.LocalOnlyOperations`
|
||
|
|
A singleton class used to access the local database independently of the remote database connection.
|
||
|
|
* `static LocalOnlyOperations Connection { get; }`: Singleton instance accessor.
|
||
|
|
* `static void CreateParam(IDbCommand icmd, string name, SqlDbType type, object value)`: Adds a parameter to a command. **Note:** Contains specific logic to convert `DateTime` values to strings or `SqlDateTime.MinValue`.
|
||
|
|
* `static SqlCommand GetSQLCommand(bool newCommand)`: Retrieves a `SqlCommand`. Reuses a static command object unless `newCommand` is true. Manages connection opening automatically.
|
||
|
|
* `int ExecuteCommand(IDbCommand icmd)`: Executes a non-query command against a newly opened connection.
|
||
|
|
* `string GetLocalConnectionString()`: Constructs and caches the connection string using `Server` and `DbName` properties.
|
||
|
|
|
||
|
|
### `DTS.Common.Storage.TestHistory`
|
||
|
|
A serializable entity class representing a record from the test history table.
|
||
|
|
* `TestHistory(IDataReader reader)`: Constructor that populates the object from a data reader.
|
||
|
|
* `static TestHistory[] GetTestHistory(string name)`: Retrieves all test histories matching a test setup name via the stored procedure `sp_TestHistoryGet`.
|
||
|
|
* `static string SerializeToString(TestHistory[] histories)`: Serializes an array of `TestHistory` objects to an XML string using the `TestHistoryCollection` helper class.
|
||
|
|
|
||
|
|
### `DTS.Common.Storage.TypeConvertor`
|
||
|
|
A sealed utility class for mapping between .NET types, `DbType`, and `SqlDbType`.
|
||
|
|
* `static Type ToNetType(DbType dbType)`
|
||
|
|
* `static Type ToNetType(SqlDbType sqlDbType)`
|
||
|
|
* `static DbType ToDbType(Type type)`
|
||
|
|
* `static DbType ToDbType(SqlDbType sqlDbType)`
|
||
|
|
* `static SqlDbType ToSqlDbType(Type type)`
|
||
|
|
* `static SqlDbType ToSqlDbType(DbType dbType)`
|
||
|
|
|
||
|
|
### `DTS.Common.Storage.UserMigrationHelper`
|
||
|
|
A helper class for migrating user data from database version 52 to 53.
|
||
|
|
* `UserMigrationHelper(DataRow row)`: Parses user data, permissions, and visibility from a `DataRow`.
|
||
|
|
* `void Commit(Dictionary<string, long> IUIItemNameToID)`: Inserts the user into `DataPROUsers` and related tables (`UserUIItemSettings`, `TagAssignments`). Supports both MSSQL and SQLite execution paths.
|
||
|
|
|
||
|
|
### `DTS.Common.Storage.DbOperations` (Partial Classes)
|
||
|
|
Contains nested abstract classes defining database schemas via constants and enums.
|
||
|
|
|
||
|
|
* **`DbOperations.SensorDB`**:
|
||
|
|
* Constants: `SensorCalibrationTable`, `SensorDataTable`, `SensorModelsTable`.
|
||
|
|
* Enums: `SensorDataFields`, `SensorModelFields`, `SensorCalibrationFields`, `SensorCalibrationRecordFields`.
|
||
|
|
* **`DbOperations.MMETables`**:
|
||
|
|
* Constants: `MMEPossibleChannelsTable`, `MMEDirectionsTable`, `MMEFilterClassesTable`, etc.
|
||
|
|
* Enums: `MMEPossibleChannelsFields`, `MMEDirectionsFields`, etc.
|
||
|
|
* Legacy Constants: `MyType`, `CustomChannelType`, `Id` (marked as replaced in specific versions).
|
||
|
|
* **`DbOperations.TestSetups`**:
|
||
|
|
* Constants: `HardwareTable`, `DASSettingsTable`, `TestSetupsTable`, etc.
|
||
|
|
* Enums: `HardwareFields`, `ChannelSettingFields`, `Fields`, `SettingsFields`, etc.
|
||
|
|
|
||
|
|
## 3. Invariants
|
||
|
|
* **Singleton Access**: `LocalOnlyOperations.Connection` and `DbOperations.Connection` are accessed via a singleton pattern protected by a lock (`DbLock`).
|
||
|
|
* **Schema Consistency**: The `enum` values in `SensorDB`, `MMETables`, and `TestSetups` define the column order or IDs for database tables. `SerialNumber` in `SensorDataFields` is explicitly value `1`.
|
||
|
|
* **Type Mapping**: `TypeConvertor` maintains a static 1-to-1 mapping between specific .NET types (e.g., `bool`, `DateTime`, `int`) and SQL types (e.g., `Bit`, `DateTime`, `Int`). Unsupported types throw `ApplicationException`.
|
||
|
|
* **Connection String**: `LocalOnlyOperations` uses Windows Authentication (`Trusted_Connection=TRUE`) exclusively for its connection string.
|
||
|
|
|
||
|
|
## 4. Dependencies
|
||
|
|
* **External Libraries**:
|
||
|
|
* `System.Data.SqlClient`: Used heavily for SQL Server interaction.
|
||
|
|
* `System.Xml.Serialization`: Used by `TestHistory` for XML serialization.
|
||
|
|
* `DTS.Common.Utilities.Logging`: Used for logging (`APILogger.Log`).
|
||
|
|
* `DbAPI`: Used for connection details and error codes (`DbAPI.Connections.ConnectionDetails`, `DbAPI.Errors.ErrorCodes`).
|
||
|
|
* **Internal Coupling**:
|
||
|
|
* `DatabaseServices` depends on `LocalOnlyOperations`, `DbOperations`, and `Utils.Database`.
|
||
|
|
* `UserMigrationHelper` depends on `DbOperations` to determine if MSSQL or SQLite is being used (`DbOperations._usingMSSQL`).
|
||
|
|
* `TestHistory` depends on `DbOperations.GetSQLCommand`.
|
||
|
|
|
||
|
|
## 5. Gotchas
|
||
|
|
* **Static Command Reuse**: `LocalOnlyOperations.GetSQLCommand()` reuses a static `SqlCommand` field (`cmd`) by default. If `newCommand` is false, the same object is returned for every call. While `Parameters.Clear()` is called, this creates shared state which may cause issues in multi-threaded scenarios.
|
||
|
|
* **DateTime Conversion Hack**: In `LocalOnlyOperations.CreateParam`, `DateTime` objects are converted to formatted strings (`yyyy-MM-dd HH:mm:ss`) rather than being passed as native SQL parameters. Additionally, `DateTime` values below `SqlDateTime.MinValue` are clamped to `SqlDateTime.MinValue`. This is likely a workaround for SQL Server `DateTime` range limitations.
|
||
|
|
* **SQLite vs MSSQL Duality**: `UserMigrationHelper.Commit` checks `DbOperations._usingMSSQL` to switch between `ExecuteCommand` and `ExecuteSQLiteCommand`. However, `LocalOnlyOperations` appears hardcoded to use `SqlConnection` (MSSQL), suggesting the SQLite support is incomplete or localized to specific migration paths.
|
||
|
|
* **Legacy Schema Constants**: `DbOperations.MMETables` contains constants `MyType`, `CustomChannelType`, and `Id` with comments indicating they were replaced by different string values in software versions 1.3.496 through 1.3.515. Developers should use the current constants (`TYPE`, `ID`) rather than the legacy ones.
|
||
|
|
* **Typo**: The class `TypeConvertor` is spelled with an "or" suffix instead of the standard "er" (`TypeConverter`).
|