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

---
source_files:
  - Common/DTS.Common/Interface/Graphs/IGraph.cs
  - Common/DTS.Common/Interface/Graphs/IGraphRecord.cs
generated_at: "2026-04-16T03:02:47.862961+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "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.