167 lines
9.6 KiB
Markdown
167 lines
9.6 KiB
Markdown
---
|
||
source_files:
|
||
- Common/DTS.Common/Classes/Sensors/AnalogDiagnostics/DiagnosticRun.cs
|
||
- Common/DTS.Common/Classes/Sensors/AnalogDiagnostics/DiagnosticEntry.cs
|
||
generated_at: "2026-04-16T03:18:16.331578+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "00d9f02148080370"
|
||
---
|
||
|
||
# DiagnosticRun and DiagnosticEntry Documentation
|
||
|
||
## 1. Purpose
|
||
This module defines core data transfer objects (`DiagnosticRun` and `DiagnosticEntry`) used to represent analog sensor diagnostic test sessions and individual channel measurements within the DTS (Data Transfer System) framework. `DiagnosticRun` models a single diagnostic test execution (e.g., a pre-test or post-test run), capturing metadata like user, test ID, and run type. `DiagnosticEntry` models a single sensor channel’s diagnostic results within a run, including measured values (excitation, offset, range, noise, shunt), status flags, and associated sensor/DAS (Data Acquisition System) identification. These classes are primarily used for deserializing data from SQL Server database queries (via `SqlDataReader`) and serve as the canonical in-memory representation of diagnostic test data for reporting, analysis, and persistence.
|
||
|
||
## 2. Public Interface
|
||
|
||
### `DiagnosticRun`
|
||
- **`DiagnosticRun()`**
|
||
Parameterless constructor; initializes all properties to their default values (`null` for nullable types, `string.Empty` for strings, `true` for `PreTest`).
|
||
|
||
- **`DiagnosticRun(SqlDataReader reader)`**
|
||
Constructor that populates the object from a `SqlDataReader` positioned on a valid row. Reads columns: `Id`, `DataPROUser`, `TestId`, `TestName`, `PreTest`. Skips assignment if the column value is `DBNull.Value`.
|
||
|
||
- **`long? Id { get; set; }`**
|
||
Database primary key or unique identifier for the diagnostic run. Nullable; defaults to `null`.
|
||
|
||
- **`string DataPROUser { get; set; }`**
|
||
Username of the operator who executed the diagnostic run. Defaults to `string.Empty`.
|
||
|
||
- **`int? TestId { get; set; }`**
|
||
Foreign key or identifier linking to a specific test configuration. Nullable; defaults to `null`.
|
||
|
||
- **`string TestName { get; set; }`**
|
||
Human-readable name of the test being run. Defaults to `string.Empty`.
|
||
|
||
- **`bool PreTest { get; set; }`**
|
||
Indicates whether this run is a *pre-test* (`true`) or *post-test* (`false`). Defaults to `true`.
|
||
|
||
---
|
||
|
||
### `DiagnosticEntry`
|
||
- **`DiagnosticEntry()`**
|
||
Parameterless constructor; initializes all properties to their default values (`null` for nullable types, `0` for numeric primitives, `DateTime.MinValue` for `Timestamp`, `DiagnosticStatus.Untested` for status fields, `string.Empty` for strings).
|
||
|
||
- **`DiagnosticEntry(SqlDataReader reader)`**
|
||
Constructor that populates the object from a `SqlDataReader` row. Reads columns: `Id`, `DiagnosticRunId`, `Excitation`, `ExcitationStatus`, `Offset`, `OffsetStatus`, `ActualRange`, `ActualRangeStatus`, `Noise`, `NoiseStatus`, `Shunt`, `ShuntStatus`, `SensorId`, `SensorSerialNumber`, `DASId`, `DASSerialNumber`, `DASChannelIdx`, `UserCode`, `UserChannelName`, `IsoCode`, `IsoChannelName`, `ScaleFactor`, `CalibrationRecordId`, `CalibrationRecordXML`, `Timestamp`. Skips assignment if the column value is `DBNull.Value`.
|
||
|
||
- **`long? Id { get; set; }`**
|
||
Database primary key or unique identifier for the diagnostic entry. Nullable; defaults to `null`.
|
||
|
||
- **`long DiagnosticRunId { get; set; }`**
|
||
Foreign key linking this entry to a `DiagnosticRun`. Non-nullable; defaults to `-1`.
|
||
|
||
- **`double? Excitation { get; set; }`**
|
||
Measured excitation voltage (e.g., in mV/V). Nullable; defaults to `null`.
|
||
|
||
- **`DiagnosticStatus ExcitationStatus { get; set; }`**
|
||
Status of the excitation measurement (e.g., Passed, Failed, Untested). Defaults to `DiagnosticStatus.Untested`.
|
||
|
||
- **`double? Offset { get; set; }`**
|
||
Measured offset voltage. Nullable; defaults to `null`.
|
||
|
||
- **`DiagnosticStatus OffsetStatus { get; set; }`**
|
||
Status of the offset measurement. Defaults to `DiagnosticStatus.Untested`.
|
||
|
||
- **`double? ActualRange { get; set; }`**
|
||
Measured actual range (e.g., span). Nullable; defaults to `null`.
|
||
|
||
- **`DiagnosticStatus ActualRangeStatus { get; set; }`**
|
||
Status of the range measurement. Defaults to `DiagnosticStatus.Untested`.
|
||
|
||
- **`double? Noise { get; set; }`**
|
||
Measured noise level. Nullable; defaults to `null`.
|
||
|
||
- **`DiagnosticStatus NoiseStatus { get; set; }`**
|
||
Status of the noise measurement. Defaults to `DiagnosticStatus.Untested`.
|
||
|
||
- **`double? Shunt { get; set; }`**
|
||
Measured shunt calibration value. Nullable; defaults to `null`.
|
||
|
||
- **`DiagnosticStatus ShuntStatus { get; set; }`**
|
||
Status of the shunt measurement. Defaults to `DiagnosticStatus.Untested`.
|
||
|
||
- **`int? SensorId { get; set; }`**
|
||
Identifier for the sensor being tested. Nullable; defaults to `null`.
|
||
|
||
- **`string SensorSerialNumber { get; set; }`**
|
||
Serial number of the sensor. Defaults to `string.Empty`.
|
||
|
||
- **`int? DASId { get; set; }`**
|
||
Identifier for the Data Acquisition System used. Nullable; defaults to `null`.
|
||
|
||
- **`string DASSerialNumber { get; set; }`**
|
||
Serial number of the DAS. Defaults to `string.Empty`.
|
||
|
||
- **`int DASChannelIdx { get; set; }`**
|
||
Zero-based index of the channel on the DAS. Defaults to `0`.
|
||
|
||
- **`string UserCode { get; set; }`**
|
||
User-defined code or label for the channel. Defaults to `string.Empty`.
|
||
|
||
- **`string UserChannelName { get; set; }`**
|
||
User-friendly name for the channel. Defaults to `string.Empty`.
|
||
|
||
- **`string IsoCode { get; set; }`**
|
||
ISO-standard code for the channel configuration. Defaults to `string.Empty`.
|
||
|
||
- **`string IsoChannelName { get; set; }`**
|
||
ISO-standard name for the channel. Defaults to `string.Empty`.
|
||
|
||
- **`double ScaleFactor { get; set; }`**
|
||
Scaling factor applied to raw measurements. Defaults to `1`.
|
||
|
||
- **`int CalibrationRecordId { get; set; }`**
|
||
Identifier linking to a calibration record. Non-nullable; defaults to `-1`.
|
||
|
||
- **`string CalibrationRecordXML { get; set; }`**
|
||
XML blob containing full calibration record details. Defaults to `string.Empty`.
|
||
|
||
- **`DateTime Timestamp { get; set; }`**
|
||
Timestamp of when the diagnostic entry was recorded. Defaults to `DateTime.MinValue`.
|
||
|
||
---
|
||
|
||
## 3. Invariants
|
||
- **`DiagnosticRunId` in `DiagnosticEntry` is non-nullable and defaults to `-1`**, implying a valid `DiagnosticRun` must be associated (though `-1` may indicate an unassigned or invalid state).
|
||
- **`DASChannelIdx` is a non-nullable `int` defaulting to `0`**, suggesting zero-based indexing is assumed.
|
||
- **All `DiagnosticStatus` properties default to `DiagnosticStatus.Untested`**, indicating a safe initial state before validation.
|
||
- **`PreTest` defaults to `true`**, implying the system assumes pre-test unless explicitly marked otherwise.
|
||
- **Null handling in constructors**: Values from `SqlDataReader` are only assigned if `!DBNull.Value.Equals(...)`. This means missing database columns or `NULL` values result in the property retaining its default value (e.g., `null`, `0`, `string.Empty`, `DiagnosticStatus.Untested`).
|
||
- **`DiagnosticEntry` properties map directly to database column names** (e.g., `reader["Timestamp"]` → `Timestamp` property). Column name casing must match exactly in the database.
|
||
|
||
## 4. Dependencies
|
||
- **Depends on**:
|
||
- `DTS.Common.Interface.Sensors.AnalogDiagnostics` namespace (for `IDiagnosticRun` and `IDiagnosticEntry` interfaces).
|
||
- `System.Data.SqlClient` (for `SqlDataReader` usage).
|
||
- `DiagnosticStatus` enum (used in `DiagnosticEntry` properties; defined in `DTS.Common.Interface.Sensors.AnalogDiagnostics`, not shown in source).
|
||
- **Depended on by**:
|
||
- Data access layers (e.g., repositories or data readers) that populate these objects from SQL queries.
|
||
- Reporting or analysis modules that consume diagnostic test results.
|
||
- Likely used in conjunction with `IDiagnosticRun`/`IDiagnosticEntry` interfaces for testability or inversion of control.
|
||
|
||
## 5. Gotchas
|
||
- **`DASChannelIdx` is read as `short` from `SqlDataReader` but stored as `int`**:
|
||
```csharp
|
||
DASChannelIdx = (short)reader["DASChannelIdx"];
|
||
```
|
||
This may cause runtime exceptions if the database column is larger than `Int16` (e.g., `int` or `bigint`). Type mismatch is not validated at compile time.
|
||
|
||
- **`DiagnosticStatus` cast assumes underlying type is `short`**:
|
||
```csharp
|
||
ExcitationStatus = (DiagnosticStatus)(short)reader["ExcitationStatus"];
|
||
```
|
||
If the database column is stored as `int` or `tinyint`, this cast may throw `InvalidCastException` or produce incorrect values.
|
||
|
||
- **No validation or business logic**: These are pure DTOs. Consumers must enforce constraints (e.g., `DiagnosticRunId != -1`, `PreTest` semantics).
|
||
|
||
- **Default `DiagnosticRunId = -1` is ambiguous**: May indicate "uninitialized" or "invalid", but no explicit check or constant is defined for this sentinel value.
|
||
|
||
- **No immutability guarantees**: All properties have public setters; objects can be mutated after construction.
|
||
|
||
- **`Timestamp` property name vs. database column**: The property is named `Timestamp` (PascalCase), but SQL Server column is likely `Timestamp` (case-insensitive). However, if the DB uses `timestamp` (deprecated synonym for `rowversion`) instead of `datetime`, the cast `(DateTime)reader["Timestamp"]` will fail.
|
||
|
||
- **No null-safety for string properties**: If `reader["DataPROUser"]` returns `null` (not `DBNull`), the cast `(string)reader["..."]` succeeds but may yield `null` (not `string.Empty`). Only `DBNull` is guarded against.
|
||
|
||
- **No error handling in constructor**: Exceptions from invalid casts or missing columns propagate unhandled. |