134 lines
7.2 KiB
Markdown
134 lines
7.2 KiB
Markdown
---
|
||
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. |