DP44/enriched-partialglm/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-16T12:18:31.651015+00:00	zai-org/GLM-5-FP8	1	a5e5bc31a5802f38

Documentation: DTS.Common.Interface.Graphs

1. Purpose

This module defines the data contract for graph configuration within the DTS system. It provides two interfaces—IGraphRecord and IGraph—that model graph definitions persisted to a database, including axis bounds, channel assignments, and threshold markers. IGraphRecord represents the pure data shape of a database record, while IGraph extends it with runtime behaviors for channel management, XML serialization, and string synchronization. These interfaces serve as the abstraction layer between graph persistence and graph rendering/management components.

---

2. Public Interface

IGraphRecord

Base interface describing a database record for a graph configuration.

Property	Type	Access	Description
GraphId	int	get/set	Database primary key for the graph.
TestSetupId	int	get/set	Foreign key linking the graph to a test setup.
GraphName	string	get/set	Display name of the graph. Constrained to 50 characters via [MaxLength(50)].
GraphDescription	string	get/set	Description text for the graph. Constrained to 50 characters via [MaxLength(50)].
ChannelsString	string	get/set	Serialized representation of all channels in the graph. Constrained to 2048 characters via [MaxLength(2048)].
UseDomainMin	bool	get/set	Flag indicating whether the domain (X) axis has a minimum bound.
DomainMin	double	get/set	Minimum value for the domain axis. Only meaningful when UseDomainMin is true.
UseDomainMax	bool	get/set	Flag indicating whether the domain (X) axis has a maximum bound.
DomainMax	double	get/set	Maximum value for the domain axis. Only meaningful when UseDomainMax is true.
UseRangeMin	bool	get/set	Flag indicating whether the range (Y) axis has a minimum bound.
RangeMin	double	get/set	Minimum value for the range axis. Only meaningful when UseRangeMin is true.
UseRangeMax	bool	get/set	Flag indicating whether the range (Y) axis has a maximum bound.
RangeMax	double	get/set	Maximum value for the range axis. Only meaningful when UseRangeMax is true.
ThresholdsString	string	get/set	Serialized representation of threshold lines to display on the graph. Constrained to 2048 characters via [MaxLength(2048)].
LocalOnly	bool	get/set	Flag indicating whether to synchronize the record with a central database. Marked as deprecated in XML documentation.

---

IGraph

Extends IGraphRecord with runtime operations for channel management and serialization.

Method	Signature	Description
AddChannel	void AddChannel(IGroupChannel groupChannel)	Adds a group channel to the graph.
RemoveChannel	void RemoveChannel(IGroupChannel groupChannel)	Removes a group channel from the graph.
ReadXML	void ReadXML(System.Xml.XmlElement root, IReadOnlyDictionary<long, IGroupChannel> channelLookup)	Deserializes graph configuration from an XML element. Uses the provided channelLookup dictionary to resolve channel references by their long key.
WriteXML	void WriteXML(ref System.Xml.XmlWriter writer)	Serializes the graph configuration to XML using the provided XmlWriter. The writer is passed by reference.
UpdateChannelAndThresholdStrings	void UpdateChannelAndThresholdStrings()	Synchronizes the ChannelsString and ThresholdsString properties from the in-memory GroupChannels and Thresholds collections.

---

3. Invariants

• String Length Constraints: GraphName and GraphDescription must not exceed 50 characters. ChannelsString and ThresholdsString must not exceed 2048 characters. These are enforced via MaxLengthAttribute annotations.
• Conditional Axis Bounds: DomainMin, DomainMax, RangeMin, and RangeMax values are only semantically valid when their corresponding Use* flags are true. The interface does not enforce this at compile time.
• Channel Lookup Key Type: The ReadXML method expects channel lookups to use long keys.
• Inheritance Relationship: All implementations of IGraph must also implement IGraphRecord.

---

4. Dependencies

This module depends on:

• DTS.Common.Interface.Channels — for IGroupChannel type used in channel management methods
• System.Collections.Generic — for IReadOnlyDictionary<long, IGroupChannel> parameter
• System.ComponentModel.DataAnnotations — for MaxLengthAttribute on IGraphRecord properties
• System.Xml — for XmlElement and XmlWriter types in serialization methods

What depends on this module:

• Cannot be determined from source alone — no consumers are shown in these files.

---

5. Gotchas

• Deprecated Property: LocalOnly is explicitly marked as deprecated in the XML documentation. Its purpose (controlling synchronization with a central database) suggests historical functionality that may no longer be in use or is planned for removal.

• Asymmetric XML API: ReadXML accepts an XmlElement (a node-oriented approach), while WriteXML accepts a ref XmlWriter (a streaming writer approach). This asymmetry may complicate round-trip serialization logic.

• Hidden Properties Referenced: The UpdateChannelAndThresholdStrings method documentation references GroupChannels and Thresholds properties that are not defined in either interface. These are presumably defined on concrete implementations or another partial interface not shown here. The relationship between these collections and the string properties is managed by this method.

• String Serialization Format: The format of ChannelsString and ThresholdsString is not specified in these interfaces. Implementations must define and document their own serialization scheme (e.g., comma-separated IDs, JSON, custom format).