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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/DTS.Core.DbAPIWrapper/ApiInfo.cs DataPRO/DTS.Core.DbAPIWrapper/DbApiWrapper.cs	2026-04-16T03:50:33.707237+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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

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

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

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

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

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

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.