DP44/enriched-qwen3-coder-next/Common/DTS.Common/Classes/Sensors/AnalogDiagnostics.md

---
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.