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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Classes/Sensors/AnalogDiagnostics/DiagnosticRun.cs Common/DTS.Common/Classes/Sensors/AnalogDiagnostics/DiagnosticEntry.cs	2026-04-16T03:18:16.331578+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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:

  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:

  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.