141 lines
6.7 KiB
Markdown
141 lines
6.7 KiB
Markdown
---
|
||
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.* |