DP44/enriched-partialglm/Common/DTS.CommonCore/Interface/Graphs.md

---
source_files:
  - Common/DTS.CommonCore/Interface/Graphs/IGraph.cs
  - Common/DTS.CommonCore/Interface/Graphs/IGraphRecord.cs
generated_at: "2026-04-16T12:18:31.651015+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "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).