---
source_files:
  - Common/DTS.CommonCore/Interface/Graphs/IGraph.cs
  - Common/DTS.CommonCore/Interface/Graphs/IGraphRecord.cs
generated_at: "2026-04-16T02:23:21.443229+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "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`).