--- source_files: - DataPRO/DTS.Core.DbAPIWrapper/ApiInfo.cs - DataPRO/DTS.Core.DbAPIWrapper/DbApiWrapper.cs generated_at: "2026-04-16T03:50:33.707237+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "64f38e1e002da8cf" --- # DTS.Core.DbAPIWrapper ## Documentation: `DTS.Core.DbAPIWrapper` Module --- ### 1. **Purpose** This module serves as a thin, opinionated wrapper around the legacy `DbAPI` library to provide a consistent, authenticated, and async-friendly interface for interacting with database-backed test setup and DAS (Data Acquisition System) data. It encapsulates connection setup, user authentication, and API invocation logic, ensuring that all downstream consumers interact with the database through a controlled, validated channel—while abstracting away low-level error handling and state management (e.g., `ApiInfo` tracking of authenticated session context). --- ### 2. **Public Interface** #### `DbApiWrapper` class ##### Constructor ```csharp public DbApiWrapper( string dbServer, string dbName, string dbUsername, string dbPassword, bool adAuthentication, bool useCentralizedDb, int? clientDbVersion = null) ``` - Initializes a new instance with raw connection parameters. - Internally constructs a `ConnectionDetails` object and stores it in `_connectionDetail`. - Does **not** connect to the database at construction time. ##### `AuthenticateUser` ```csharp public void AuthenticateUser(string username, string password) ``` - Performs synchronous database connection and user login via `DbAPI.DbAPI.Connections.LoginUser`. - On success, populates `_apiInfo` with the first entry from `GetLoggedInUsers()` (a tuple of `IUserDbRecord` and `IConnectionDetails`). - Throws `UnauthorizedAccessException` if login fails or no logged-in users are returned. ##### `TestSetupsGet` ```csharp public Tuple TestSetupsGet( int? testSetupId = null, string? testSetupName = null, double defaultROIStart = double.NaN, double defaultROIEnd = double.NaN, bool defaultIgnoreShortedStart = false, bool defaultIgnoreShortedTrigger = false) ``` - Synchronous wrapper around `GetTestSetups`. - Returns a tuple: - `Item1`: Array of `ITestSetupRecord` (test setup definitions). - `Item2`: Array of `string` (error messages from the underlying API). - `Item3`: `ulong` error code returned by `TestSetupsGet`. - Throws `Exception` if authentication is missing or if the underlying call fails. ##### `TestSetupsGetAsync` ```csharp public async Task> TestSetupsGetAsync( int? testSetupId = null, string? testSetupName = null, double defaultROIStart = double.NaN, double defaultROIEnd = double.NaN, bool defaultIgnoreShortedStart = false, bool defaultIgnoreShortedTrigger = false) ``` - Asynchronous wrapper that offloads `GetTestSetups` to a background thread via `Task.Run`. - Behavior and return semantics identical to `TestSetupsGet`. ##### `DASGet` ```csharp public Tuple DASGet( string? dasSerial = null, string? position = null) ``` - Synchronous wrapper around `GetDAS`. - Returns a tuple: - `Item1`: Array of `IDASDBRecord` (DAS device records). - `Item2`: `ulong` error code from `DASGet`. - Throws `Exception` if authentication is missing or underlying call fails. ##### `DASGetAsync` ```csharp public async Task> DASGetAsync( string? dasSerial = null, string? position = null) ``` - Asynchronous wrapper for `GetDAS`, using `Task.Run`. - Behavior and return semantics identical to `DASGet`. --- ### 3. **Invariants** - `_apiInfo` **must** be non-null and contain non-null `UserDbRecord` and `ConnectionDetails` before any `GetTestSetups` or `GetDAS` call is made. Otherwise, an `Exception` with message `"Authentication is required"` is thrown. - `_connectionDetail` is initialized once in the constructor and never modified. - `Connect()` is called unconditionally in `AuthenticateUser`, and failure (non-zero return) throws an `Exception`. - `AuthenticateUser` expects `GetLoggedInUsers()` to return at least one entry; otherwise, it throws `UnauthorizedAccessException`. - All public methods (`TestSetupsGet`, `DASGet`, etc.) wrap internal calls in `try/catch` and re-throw with additional context (e.g., `"TestSetupsGet failed. {ex.Message}"`). --- ### 4. **Dependencies** #### Internal Dependencies (from imports) - `DbAPI.Connections` – Provides `ConnectToDb`, `LoginUser`, `GetLoggedInUsers`, `TestSetups.TestSetupsGet`, and `DAS.DASGet`. - `DTS.Common.Interface.Database` – Defines `IUserDbRecord`, `IConnectionDetails`. - `DTS.Common.Interface.DataRecorders` – Defines `IDASDBRecord`. - `DTS.Common.Interface.TestSetups.TestSetupsList` – Defines `ITestSetupRecord`. #### External Dependencies - The `DbAPI` native/managed interop library (not included in source). - `DTS.Common` assembly (contains shared interfaces and types). - Standard .NET `System` (for `Tuple`, `Task`, `Exception`, etc.). #### Usage - This module is consumed by higher-level services or UI layers that need to fetch test setups or DAS records after authenticating a user. --- ### 5. **Gotchas** - **Authentication state is implicit and per-instance**: `_apiInfo` is stored as a private field; once `AuthenticateUser` succeeds, all subsequent calls on the same `DbApiWrapper` instance assume the session is valid. No explicit session invalidation or logout mechanism is exposed. - **`Connect()` is called twice in `AuthenticateUser`**: Once explicitly, and implicitly inside `LoginUser` (if `LoginUser` internally calls `ConnectToDb`). This may cause redundant connection attempts. - **`_ = userRecord;` is a no-op**: The result of `LoginUser`’s `out var userRecord` is assigned but discarded—only the `hr` return code is checked. This may indicate incomplete error handling or legacy code. - **Async methods use `Task.Run`**: This blocks a thread pool thread and does *not* provide true async I/O (e.g., no async DB APIs used). This may cause scalability issues under high load. - **`clientDbVersion` defaults to `0` if `null`**: The constructor uses `clientDbVersion.HasValue ? clientDbVersion.Value : 0`, which may mask missing version information. - **No validation on input parameters**: e.g., empty strings for `dbServer`, `dbName`, etc., are not explicitly rejected at construction time. - **`GetLoggedInUsers()` returns `Tuple[]`**: The code assumes the first entry (`loggedInUsers[0]`) is valid—no fallback or selection logic is present. > *None of the above constitute bugs per se, but they represent design decisions or legacy patterns that may surprise new developers.*