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