DP44/enriched-partialglm/Common/DTS.Common.Storage.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T11:31:09.102777+00:00	zai-org/GLM-5-FP8	1	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).