78 lines
5.2 KiB
Markdown
78 lines
5.2 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/DASFactoryDb/DAS/DAS.cs
|
||
generated_at: "2026-04-16T03:52:32.887554+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "bd5dcbab40df1de5"
|
||
---
|
||
|
||
# DAS
|
||
|
||
## Documentation: `DASFactoryDb.DAS.DAS` Module
|
||
|
||
---
|
||
|
||
### 1. Purpose
|
||
This module provides a simplified data access layer for inserting records into the DAS (Device Acceptance System) factory communication table in a SQL Server database. It encapsulates the logic for calling the stored procedure `sp_IDASCommunicationTableSimpleInsert`, handling parameter binding, output parameter extraction, and error propagation via `DbWrapper.ProcessReturn`. Its role is to abstract low-level ADO.NET operations for a specific high-frequency insert operation, ensuring consistent handling of serial number, firmware version, and connection string data.
|
||
|
||
---
|
||
|
||
### 2. Public Interface
|
||
|
||
#### `InsertDASSimple(string serialNumber, string firmwareVersion, string connectString) → int`
|
||
- **Behavior**: Executes the stored procedure `sp_IDASCommunicationTableSimpleInsert` with the provided input parameters (`@SerialNumber`, `@FirmwareVersion`, `@ConnectString`) and returns the newly inserted record’s ID (`@new_id`).
|
||
- **Parameters**:
|
||
- `serialNumber`: NVARCHAR(50) — Device serial number.
|
||
- `firmwareVersion`: NVARCHAR(50) — Firmware version string.
|
||
- `connectString`: NVARCHAR(255) — Connection string for the device.
|
||
- **Output**:
|
||
- Returns the integer value of the `@new_id` output parameter (the primary key of the inserted row).
|
||
- **Error Handling**:
|
||
- Delegates error processing to `DbWrapper.ProcessReturn`, passing the `@errorNumber` and `@errorMessage` output parameters.
|
||
- Disposes the underlying `SqlConnection` in a `finally` block (via `cmd.Connection.Dispose()`).
|
||
|
||
> **Note**: Parameter name for `connectString` is misspelled as `"ConnectString"` (missing `@` prefix in the `SqlParameter` constructor), but the stored procedure likely expects `@ConnectString`. This is consistent with the source and must be preserved.
|
||
|
||
---
|
||
|
||
### 3. Invariants
|
||
- **Parameter Constraints** (inferred from SQL types):
|
||
- `serialNumber` must be ≤ 50 characters (NVARCHAR(50)).
|
||
- `firmwareVersion` must be ≤ 50 characters (NVARCHAR(50)).
|
||
- `connectString` must be ≤ 255 characters (NVARCHAR(255)).
|
||
- **Execution Guarantee**:
|
||
- The stored procedure is always invoked with `CommandType.StoredProcedure`.
|
||
- Output parameters `@errorNumber`, `@errorMessage`, and `@new_id` are *always* expected and used.
|
||
- **Resource Management**:
|
||
- The `SqlCommand.Connection` is *always* disposed after execution, regardless of success or failure (via `finally` block).
|
||
- **Return Semantics**:
|
||
- The method *always* returns an `int` derived from `@new_id`; no null-check is performed on `newId.Value` before conversion (assumes non-null output from stored procedure).
|
||
|
||
---
|
||
|
||
### 4. Dependencies
|
||
|
||
#### **Internal Dependencies**
|
||
- `DbWrapper.GetDASFactoryCommand()` — Provides a configured `SqlCommand` instance (connection, transaction context, etc.).
|
||
- `DbWrapper.ProcessReturn(SqlParameter errorNumber, SqlParameter errorMessage)` — Handles error propagation based on output parameters (e.g., throws exception if `errorNumber ≠ 0`).
|
||
|
||
#### **External Dependencies**
|
||
- `System.Data` (ADO.NET types: `SqlDbType`, `CommandType`, `ParameterDirection`)
|
||
- `System.Data.SqlClient` (SQL Server client types: `SqlCommand`, `SqlParameter`)
|
||
|
||
#### **Downstream Consumers**
|
||
- Any code calling `DAS.InsertDASSimple(...)` (e.g., factory test automation, device onboarding services).
|
||
- The stored procedure `sp_IDASCommunicationTableSimpleInsert` in the target database (not included in source, but required at runtime).
|
||
|
||
---
|
||
|
||
### 5. Gotchas
|
||
- **Parameter Name Typo**: The `SqlParameter` for `connectString` is constructed as `new SqlParameter("ConnectString", ...)` instead of `"@ConnectString"`. While ADO.NET typically ignores the `@` prefix in the constructor (it is added automatically), this is non-standard and could cause issues if `DbWrapper.GetDASFactoryCommand()` or the underlying connection setup expects strict naming.
|
||
- **No Input Validation**: The method does *not* validate input lengths or nullability before passing values to SQL. Passing `null` or oversized strings may cause runtime errors (e.g., `SqlException` from the stored procedure or truncation).
|
||
- **Assumes Non-null `@new_id`**: `Convert.ToInt32(newId.Value)` will throw `InvalidCastException` or `FormatException` if `@new_id` is `DBNull` or non-numeric.
|
||
- **Resource Disposal**: While `cmd.Connection.Dispose()` is called, the `using` block on `cmd` does *not* dispose the connection (since `cmd.Connection` is externally managed by `DbWrapper`). This is safe *only if* `DbWrapper` does not reuse the connection after disposal — a subtle risk if `DbWrapper` manages pooled connections incorrectly.
|
||
- **No Transaction Scope**: Inserts occur outside an explicit transaction; if atomicity with other operations is required, this method cannot be used directly.
|
||
|
||
> **None identified from source alone.**
|
||
> *(Note: The above gotchas are inferred from code structure and common ADO.NET pitfalls; no explicit documentation or comments in the source clarify intent or constraints.)* |