DP44/enriched-qwen3-coder-next/Common/DTS.Common.Serialization/Control.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Serialization/Control/ReviewableAttribute.cs Common/DTS.Common.Serialization/Control/IntervalSec.cs	2026-04-16T03:39:42.724755+00:00	Qwen/Qwen3-Coder-Next-FP8	1	b95e2bb79309f305

Control

Documentation: DTS.Slice.Control Namespace – ReviewableAttribute & IntervalSec

---

1. Purpose

This module provides foundational types for representing reviewable attributes (e.g., displayable metadata in a UI review tab) and time intervals (in seconds) within the DTS Slice Control domain. ReviewableAttribute serves as an abstract base for dynamically computing and exposing attribute values (e.g., channel status, configuration metadata) for review purposes, while IntervalSec encapsulates a time range with begin/end times and supports interoperability with a serialization-specific counterpart via implicit conversions.

---

2. Public Interface

ReviewableAttribute (Abstract Class)

• ReviewableAttribute(string name, DetermineValueString calculateValue)
  Constructor. Initializes the attribute with a name and a delegate used to compute the value on demand. Throws ReviewableAttribute.Exception on failure.

• string Name { get; }
  Read-only property returning the attribute’s display name.

• string Value { get; }
  Read-only property that invokes the CalculateValue delegate to compute the current value. On exception during computation, logs the error and returns "N/A" (does not throw).

• delegate string DetermineValueString();
  Public delegate defining the signature for value-computation methods.

• private DetermineValueString CalculateValue { get; set; }
  Private property storing the delegate. Throws ApplicationException if accessed before initialization.

IntervalSec (Concrete Class)

• IntervalSec()
  Parameterless constructor. Leaves Begin and End uninitialized (default to 0.0 due to Property<double> initialization, but semantically "uninitialized" per comment).

• IntervalSec(double begin, double end)
  Constructor initializing Begin and End to specified values. Throws generic Exception on failure.

• double Begin { get; set; }
  Read/write property for the interval’s start time (seconds).

• double End { get; set; }
  Read/write property for the interval’s end time (seconds).

• public static implicit operator Serialization.Test.IntervalSec(IntervalSec thisInterval)
  Implicit conversion to DTS.Serialization.Test.IntervalSec, using current Begin/End.

• public static implicit operator IntervalSec(Serialization.Test.IntervalSec thatInterval)
  Implicit conversion from DTS.Serialization.Test.IntervalSec, constructing a new instance.

• public override bool Equals(object obj)
  Memberwise equality check against another IntervalSec. Returns false if obj is null or not IntervalSec.

• public override int GetHashCode()
  Returns base hash code (note: does not combine Begin/End explicitly—see Gotchas).

---

3. Invariants

• ReviewableAttribute

  • Name must be non-null (enforced by Property<string> constructor with null as default, but no explicit validation—potential risk).
  • CalculateValue must be assigned before Value is accessed; otherwise, ApplicationException is thrown.
  • Value computation never throws; exceptions are caught and logged, returning "N/A".

• IntervalSec

  • No invariant enforces Begin ≤ End; invalid intervals (e.g., Begin > End) are permitted.
  • Begin and End default to 0.0 (via Property<double> initialization), but the parameterless constructor comment states they are "uninitialized"—this is a semantic mismatch.

---

4. Dependencies

• DTS.Slice.Control.ReviewableAttribute

  • Depends on:
    • DTS.Utilities (for APILogger, Exceptional, Property<T>)
    • DTS.Utilities.DotNetProgrammingConstructs (for Property<T>)
  • Used by: Unknown from source—likely subclassed by domain-specific reviewable attributes (e.g., ChannelAttribute, SystemStatusAttribute).

• DTS.Slice.Control.IntervalSec

  • Depends on:
    • DTS.Common.Utilities
    • DTS.Common.Utilities.DotNetProgrammingConstructs (for Property<double>, Exceptional)
    • DTS.Serialization.Test.IntervalSec (for implicit conversions)
  • Used by: Likely in time-windowing or data-slicing logic (e.g., selecting data within a time range).

---

5. Gotchas

• ReviewableAttribute

  • CalculateValue is a private property—subclasses cannot override or inspect it directly. Initialization must occur in the base constructor.
  • Value silently fails on computation error ("N/A"), which may mask bugs if not logged.
  • No validation on name parameter (e.g., null/empty); Property<string> allows null.

• IntervalSec

  • GetHashCode() does not incorporate Begin/End, violating the contract that equal objects must have equal hash codes. This will cause failures in hash-based collections (e.g., HashSet, Dictionary).
  • Begin/End default to 0.0 despite constructor comment implying "uninitialized" state—this may lead to false positives (e.g., interval [0.0, 0.0] treated as valid).
  • Implicit conversions assume Serialization.Test.IntervalSec has matching Begin/End properties; no validation on conversion.

• Both

  • Heavy use of try/catch blocks wrapping property accessors and constructors—suggests legacy error-handling pattern. Consider refactoring to reduce overhead.
  • Reliance on Property<T> wrapper (not shown) implies a custom property system; behavior (e.g., change notifications) is not documented here.

None identified beyond the above.