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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Interface/Graphs/IGraph.cs Common/DTS.CommonCore/Interface/Graphs/IGraphRecord.cs	2026-04-16T02:23:21.443229+00:00	Qwen/Qwen3-Coder-Next-FP8	1	a5e5bc31a5802f38

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, along with associated display and persistence metadata. It extends IGraphRecord to combine database-backed metadata (e.g., name, axis limits, thresholds) with runtime graph composition logic (adding/removing channels, XML serialization/deserialization). This module serves as the core abstraction for graph configuration in the system—enabling programmatic manipulation of channel groupings and persistence of graph state to/from XML and database records.

---

2. Public Interface

IGraph Interface (inherits IGraphRecord)

• void AddChannel(IGroupChannel groupChannel)
  Adds the specified IGroupChannel to the graph’s internal collection of channels. Must be called before serialization to ensure the channel is included in ChannelsString.

• void RemoveChannel(IGroupChannel groupChannel)
  Removes the specified IGroupChannel from the graph’s internal collection of channels. Must be followed by UpdateChannelAndThresholdStrings() to persist the change to ChannelsString.

• void ReadXML(System.Xml.XmlElement root, IReadOnlyDictionary<long, IGroupChannel> channelLookup)
  Deserializes graph state from an XML element (root). Uses channelLookup to resolve channel references by ID (keyed by long). Populates the graph’s channels and metadata (e.g., axis limits, thresholds) from XML. Note: Does not automatically call UpdateChannelAndThresholdStrings()—callers must do so explicitly if needed.

• void WriteXML(ref System.Xml.XmlWriter writer)
  Serializes the graph’s state (including channels and thresholds) to XML using the provided XmlWriter. Relies on the current values of ChannelsString and ThresholdsString, which must be up-to-date (e.g., via UpdateChannelAndThresholdStrings()).

• void UpdateChannelAndThresholdStrings()
  Synchronizes the ChannelsString and ThresholdsString properties with the current in-memory state of GroupChannels and Thresholds. This method must be invoked before WriteXML() or any database persistence to ensure consistency.

IGraphRecord Interface (inherited members)

Member	Type	Description
GraphId	int	Database primary key for the graph record.
TestSetupId	int	Foreign key linking the graph to a specific test setup.
GraphName	string	Human-readable name (max 50 chars).
GraphDescription	string	Human-readable description (max 50 chars).
ChannelsString	string	Serialized list of channel identifiers (max 2048 chars).
UseDomainMin, DomainMin	bool, double	Controls whether the domain (X) axis minimum is enforced.
UseDomainMax, DomainMax	bool, double	Controls whether the domain (X) axis maximum is enforced.
UseRangeMin, RangeMin	bool, double	Controls whether the range (Y) axis minimum is enforced.
UseRangeMax, RangeMax	bool, double	Controls whether the range (Y) axis maximum is enforced.
ThresholdsString	string	Serialized list of threshold definitions (max 2048 chars).
LocalOnly	bool	Deprecated flag indicating whether the record is local-only (not synced to central DB).

Note

: IGraphRecord does not expose GroupChannels or Thresholds as properties—these are inferred to be internal to implementations of IGraph. The ChannelsString and ThresholdsString are the persisted representations.

---

3. Invariants

• ChannelsString and ThresholdsString must be kept in sync with the in-memory channel/threshold state via UpdateChannelAndThresholdStrings() before persistence (e.g., WriteXML, DB save).
• GraphName and GraphDescription are constrained to ≤ 50 characters (via [MaxLength(50)]).
• ChannelsString and ThresholdsString are constrained to ≤ 2048 characters (via [MaxLength(2048)]).
• Axis limits (DomainMin, DomainMax, etc.) are only semantically valid when their corresponding Use* flag is true.
• LocalOnly is deprecated and should be ignored in new logic.

---

4. Dependencies

• Depends on:

  • DTS.Common.Interface.Channels.IGroupChannel (for channel management).
  • System.Collections.Generic.IReadOnlyDictionary<long, IGroupChannel> (for XML deserialization channel resolution).
  • System.Xml.XmlElement, System.Xml.XmlWriter (for XML I/O).
  • System.ComponentModel.DataAnnotations (for metadata annotations like [MaxLength]).

• Depended on by:

  • Likely consumed by UI layers (graph rendering), persistence services (DB/XML I/O), and test setup configuration modules (given TestSetupId).
  • Implementations (not shown) would be concrete graph types (e.g., Graph, TimeSeriesGraph).

---

5. Gotchas

• Critical: ReadXML does not automatically call UpdateChannelAndThresholdStrings()—implementations or callers must ensure strings are updated post-deserialization if persistence is required.
• Critical: AddChannel/RemoveChannel modify internal state but do not update ChannelsString; UpdateChannelAndThresholdStrings() must be called explicitly afterward.
• Ambiguity: The interface does not expose GroupChannels or Thresholds as properties—only their serialized string forms (ChannelsString, ThresholdsString). This implies implementations manage these collections internally, but the exact structure (e.g., List<IGroupChannel>, HashSet<IGroupChannel>) is unknown.
• Deprecated Flag: LocalOnly is marked as deprecated but remains part of the interface—avoid using it in new code.
• String Length Limits: ChannelsString and ThresholdsString are capped at 2048 characters; implementations must ensure serialization does not exceed this (e.g., by truncating or rejecting channels).
• No Validation on Axis Values: While Use* flags control whether min/max values are applied, the interface does not enforce logical consistency (e.g., DomainMin < DomainMax).