DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/Graphs.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Interface/Graphs/IGraph.cs Common/DTS.Common/Interface/Graphs/IGraphRecord.cs	2026-04-16T03:02:47.862961+00:00	Qwen/Qwen3-Coder-Next-FP8	1	9ab60417b631bbdf

Graphs

Documentation: IGraph Interface

---

1. Purpose

The IGraph interface defines the contract for a graph entity that aggregates and manages a collection of IGroupChannel instances for visualization purposes. It extends IGraphRecord, which provides database-backed metadata (e.g., name, axis limits, thresholds), while adding runtime behavior for channel management and XML serialization/deserialization. This interface serves as the core abstraction for graph configuration in the system—enabling persistence, dynamic channel composition, and axis/threshold configuration—without dictating implementation details (e.g., UI rendering or data acquisition logic).

---

2. Public Interface

IGraph Interface

(Extends IGraphRecord)

• void AddChannel(IGroupChannel groupChannel)
  Adds a new IGroupChannel to the graph’s internal channel collection. Must be called before serialization or rendering to include the channel.

• void RemoveChannel(IGroupChannel groupChannel)
  Removes an existing IGroupChannel from the graph’s internal channel collection. After removal, the channel is no longer part of the graph’s state.

• void ReadXML(System.Xml.XmlElement root, IReadOnlyDictionary<long, IGroupChannel> channelLookup)
  Deserializes graph configuration from an XML element (root). Uses channelLookup to resolve channel references (by ID) into IGroupChannel instances. Populates the graph’s GroupChannels (inferred from ChannelsString) and other properties (e.g., axis limits, thresholds) from XML data.

• void WriteXML(ref System.Xml.XmlWriter writer)
  Serializes the graph’s current state (including channels, thresholds, and axis limits) to XML using the provided XmlWriter. The format is expected to be compatible with ReadXML.

• void UpdateChannelAndThresholdStrings()
  Synchronizes the ChannelsString and ThresholdsString properties with the current in-memory GroupChannels and Thresholds collections. This must be called before persistence or serialization to ensure data consistency.

IGraphRecord Interface

(Base interface—no methods, only properties)

• int GraphId { get; set; }
  Primary key in the database for this graph record.

• int TestSetupId { get; set; }
  Foreign key referencing the associated test setup.

• string GraphName { get; set; }
  Human-readable name (max 50 characters).

• string GraphDescription { get; set; }
  Description of the graph’s purpose (max 50 characters).

• string ChannelsString { get; set; }
  Serialized representation of channel IDs or configurations (max 2048 characters). Must be kept in sync with the in-memory channel collection via UpdateChannelAndThresholdStrings().

• bool UseDomainMin { get; set; }
  Flag indicating whether to constrain the domain (X) axis minimum.

• double DomainMin { get; set; }
  Minimum value for the domain axis (only meaningful if UseDomainMin is true).

• bool UseDomainMax { get; set; }
  Flag indicating whether to constrain the domain (X) axis maximum.

• double DomainMax { get; set; }
  Maximum value for the domain axis (only meaningful if UseDomainMax is true).

• bool UseRangeMin { get; set; }
  Flag indicating whether to constrain the range (Y) axis minimum.

• double RangeMin { get; set; }
  Minimum value for the range axis (only meaningful if UseRangeMin is true).

• bool UseRangeMax { get; set; }
  Flag indicating whether to constrain the range (Y) axis maximum.

• double RangeMax { get; set; }
  Maximum value for the range axis (only meaningful if UseRangeMax is true).

• string ThresholdsString { get; set; }
  Serialized representation of threshold definitions (max 2048 characters). Must be kept in sync with the in-memory thresholds via UpdateChannelAndThresholdStrings().

• bool LocalOnly { get; set; }
  [Deprecated] Flag indicating whether the graph should be local-only (not synchronized with a central database). Do not rely on this property.

---

3. Invariants

• ChannelsString and ThresholdsString must accurately reflect the contents of the in-memory channel and threshold collections after any modification to those collections.
  → Enforced by calling UpdateChannelAndThresholdStrings() explicitly.
• GraphName and GraphDescription are constrained to ≤50 characters (via [MaxLength] attribute).
• ChannelsString and ThresholdsString are constrained to ≤2048 characters (via [MaxLength] attribute).
• DomainMin/DomainMax, RangeMin/RangeMax values are only semantically valid when their respective Use* flags are true.
• LocalOnly is deprecated and its value is ignored; it should not be used for any logic.

---

4. Dependencies

• Depends on:

  • DTS.Common.Interface.Channels.IGroupChannel (for channel management).
  • System.Collections.Generic.IReadOnlyDictionary<long, IGroupChannel> (used in ReadXML to resolve channel IDs).
  • System.Xml (for XML serialization/deserialization).
  • System.ComponentModel.DataAnnotations (for validation attributes on IGraphRecord properties).

• Depended on by:

  • Likely concrete implementations (e.g., Graph, TestGraph) in other modules (not visible here).
  • Persistence layers (e.g., database accessors) that serialize/deserialize graphs via ReadXML/WriteXML.
  • UI components that consume IGraph to render charts with axis limits and thresholds.

---

5. Gotchas

• ChannelsString/ThresholdsString are not auto-updated.
  Modifications to the in-memory channel/threshold collections (e.g., via AddChannel/RemoveChannel) will not automatically update ChannelsString/ThresholdsString. Calling UpdateChannelAndThresholdStrings() is mandatory before persistence or serialization—failure to do so will result in stale or incorrect data being saved.

• ReadXML relies on an external channelLookup dictionary.
  The method does not construct channels itself; it assumes channelLookup contains all referenced channels by their IDs. If a channel ID in the XML is missing from channelLookup, behavior is undefined (likely a runtime error or skipped channel).

• LocalOnly is deprecated and ignored.
  Do not use this property for any logic (e.g., sync decisions). Its presence suggests legacy behavior that may be removed in future versions.

• No explicit GroupChannels or Thresholds properties are declared in IGraph or IGraphRecord.
  These are inferred from the summary comment on UpdateChannelAndThresholdStrings() and likely implemented as read-only properties (e.g., IReadOnlyList<IGroupChannel> GroupChannels { get; }). Their exact signatures are not visible in the provided source.

• No validation on axis limits (e.g., DomainMin < DomainMax) is enforced in the interface.
  Implementation-specific validation (if any) is not visible here.