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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.SerializationPlus/Control/ReviewableAttribute.cs Common/DTS.Common.SerializationPlus/Control/IntervalSec.cs	2026-04-16T03:30:45.406675+00:00	Qwen/Qwen3-Coder-Next-FP8	1	1a23a7f0b15c8ac6

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

---

1. Purpose

This module provides foundational types for representing reviewable attributes and time intervals within the DTS Slice Control subsystem. ReviewableAttribute is an abstract base class for attributes whose values are dynamically computed (e.g., for display in a UI review tab), while IntervalSec models a time interval with Begin and End times in seconds and supports conversion to/from a corresponding serialization type. Together, they support structured, dynamic data representation and time-based filtering or annotation in control/analysis workflows.

---

2. Public Interface

ReviewableAttribute (abstract class)

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

• public string Name { get; }
  Read-only property returning the attribute’s display name (e.g., "Temperature").

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

• public delegate string DetermineValueString();
  Delegate type used for the CalculateValue property—represents a parameterless method returning a string.

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

Note

: ReviewableAttribute inherits from Exceptional (from DTS.Utilities), implying exception-handling infrastructure is integrated (e.g., custom exception types like ReviewableAttribute.Exception).

---

IntervalSec (concrete class)

• IntervalSec()
  Parameterless constructor. Leaves Begin and End uninitialized (default to 0 due to Property<double> initialization).

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

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

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

• public static implicit operator Serialization.Test.IntervalSec(IntervalSec thisInterval)
  Implicit conversion to DTS.Serialization.Test.IntervalSec, using Begin and 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 test against another IntervalSec. Returns false if obj is null or not an IntervalSec.

• public override int GetHashCode()
  Returns base hash code (no custom hashing logic—relies on Exceptional base behavior).

Note

: IntervalSec inherits from Exceptional and uses Property<double> (from DTS.Utilities.DotNetProgrammingConstructs) for its fields.

---

3. Invariants

• ReviewableAttribute

  • Name is immutable after construction (only set in constructor).
  • CalculateValue must be set during construction; accessing it before initialization throws ApplicationException.
  • Value may return "N/A" on delegate failure but never throws (exceptions are logged and suppressed).
  • Name and CalculateValue are required for valid initialization; partial initialization is disallowed.

• IntervalSec

  • Begin and End default to 0 if not explicitly set (via Property<double> default value).
  • No invariant enforces Begin ≤ End; callers must ensure logical consistency.
  • Equality and hash code rely solely on Begin and End values.

---

4. Dependencies

Dependencies of this module:

• DTS.Utilities (provides Exceptional base class and logging via APILogger)
• DTS.Utilities.DotNetProgrammingConstructs (provides Property<T> for property wrappers)
• DTS.Serialization.Test.IntervalSec (for implicit conversions in IntervalSec)

Dependencies on this module:

• ReviewableAttribute is likely extended by concrete subclasses (not shown) to implement domain-specific attributes (e.g., for test result review).
• IntervalSec is used to model time ranges, likely in filtering or data selection logic (e.g., for time-windowed analysis). Its conversions suggest tight coupling with serialization layers.

---

5. Gotchas

• ReviewableAttribute.Value suppresses exceptions silently: If CalculateValue throws, the error is logged via APILogger but Value returns "N/A". This may mask failures if callers do not check logs.
• CalculateValue is not thread-safe: No synchronization is evident; concurrent access to Value may yield inconsistent results if the delegate is stateful.
• IntervalSec uses double for time: Potential for floating-point precision issues (e.g., comparison errors); no tolerance-based equality is provided.
• Equals does not handle null gracefully in the that cast: While obj is checked for null, that is assigned via as, so that will be null if obj is not IntervalSec. The code then calls that.Begin, which will throw NullReferenceException.
  • Fix needed: Add && that != null before accessing that.Begin.
• GetHashCode() is not overridden meaningfully: Returns base.GetHashCode(), which may not align with Equals semantics (violating .NET best practices for value types).
• IntervalSec parameterless constructor leaves properties uninitialized in a logical sense (though technically initialized to 0), which may cause unexpected behavior if used without explicit assignment.