DP44/enriched-qwen3-coder-next/DataPRO/DTS.Core.DbAPIWrapper.md

---
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<ITestSetupRecord[], string[], ulong> 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<Tuple<ITestSetupRecord[], string[], ulong>> 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<IDASDBRecord[], ulong> 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<Tuple<IDASDBRecord[], ulong>> 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<IUserDbRecord, IConnectionDetails>[]`**: 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.*