--- 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 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` (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 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.