Joseph Doherty
cfd403710e
Every HistoryUpdate a SQL backend applies now leaves a modification trail
(prior value, principal, Part 11 update type, modification time), and
HistoryReadRaw with IsReadModified=true serves it as HistoryModifiedData.
- Core: HistoryUpdateContext threaded into all three IHistorianDataUpdater
methods; IHistorianDataSource.ReadModifiedAsync (default NotSupported =>
BadHistoryOperationUnsupported on Gateway/Null); HistoryModified* contracts.
- SqlServer: schema v2 (002_sample_modified.sql, RequiredVersion=2, docs copy);
trail written by OUTPUT ... INTO on the same MERGE/DELETE statement, so a
failed update leaves no audit row; retention purges SampleModified per tag on
the source-time cutoff; ReadModifiedAsync keyed on (SourceTimeUtc, ModifiedId).
- QuestDB: append-only {prefix}sample_modified (TTL like samples), trail row
written BEFORE the change (orphan-on-crash, never an untracked change);
existence reads now carry the prior value; ReadModifiedAsync.
- Node manager: modified reads dispatch + page via the #669 continuation store
(HistoryContinuationState gains HistoryCursorKind + LastModifiedId), gated by
the existing HistoryRead decision; session principal / key id passed to the
updater. IsDeleteModified stays unsupported.
- Client.CLI: historyread --modified.
- Tests: node-manager dispatch/paging/cursor binding/principal threading,
over-the-wire HistoryModifiedData, shared ModifiedValueConformance on both
backends, SqlServer atomicity (forced trail failure => no change) + v1->v2
upgrade + retention trail purge.
- Docs: Historian.md (Modified-value history section, schema v2 upgrade note),
security.md, Client.CLI.md, CLAUDE.md.
254 lines
15 KiB
C#
254 lines
15 KiB
C#
using Opc.Ua;
|
|
using ZB.MOM.WW.OtOpcUa.Client.Shared.Models;
|
|
using BrowseResult = ZB.MOM.WW.OtOpcUa.Client.Shared.Models.BrowseResult;
|
|
|
|
namespace ZB.MOM.WW.OtOpcUa.Client.Shared;
|
|
|
|
/// <summary>
|
|
/// Shared OPC UA client service contract for CLI and UI consumers.
|
|
/// </summary>
|
|
public interface IOpcUaClientService : IDisposable
|
|
{
|
|
/// <summary>
|
|
/// Gets a value indicating whether the client is currently connected to an OPC UA endpoint.
|
|
/// </summary>
|
|
bool IsConnected { get; }
|
|
|
|
/// <summary>
|
|
/// Gets the current connection metadata shown to CLI and UI operators after a successful connect or failover.
|
|
/// </summary>
|
|
ConnectionInfo? CurrentConnectionInfo { get; }
|
|
|
|
/// <summary>
|
|
/// Connects the client to the configured OPC UA endpoint set, including failover-capable endpoints when provided.
|
|
/// </summary>
|
|
/// <param name="settings">The endpoint, security, and authentication settings used to establish the session.</param>
|
|
/// <param name="ct">The cancellation token that aborts the connect workflow.</param>
|
|
/// <returns>The connection metadata for the newly established session.</returns>
|
|
Task<ConnectionInfo> ConnectAsync(ConnectionSettings settings, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Disconnects from the active OPC UA endpoint and tears down subscriptions owned by the client.
|
|
/// </summary>
|
|
/// <param name="ct">The cancellation token that aborts disconnect cleanup.</param>
|
|
/// <returns>A task that represents the asynchronous operation.</returns>
|
|
Task DisconnectAsync(CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Reads the current value of an OPC UA node.
|
|
/// </summary>
|
|
/// <param name="nodeId">The node whose value should be retrieved.</param>
|
|
/// <param name="ct">The cancellation token that aborts the read request.</param>
|
|
/// <returns>The current data value of the node.</returns>
|
|
Task<DataValue> ReadValueAsync(NodeId nodeId, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Writes an operator-supplied value to an OPC UA node after applying client-side type conversion when needed.
|
|
/// </summary>
|
|
/// <param name="nodeId">The node whose value should be updated.</param>
|
|
/// <param name="value">The raw value supplied by the CLI or UI workflow.</param>
|
|
/// <param name="ct">The cancellation token that aborts the write request.</param>
|
|
/// <returns>The status code returned by the server for the write.</returns>
|
|
Task<StatusCode> WriteValueAsync(NodeId nodeId, object value, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Browses the children of a node so the client can build an address-space tree for operators.
|
|
/// </summary>
|
|
/// <param name="parentNodeId">The node to browse, or <see cref="ObjectIds.ObjectsFolder"/> when omitted.</param>
|
|
/// <param name="ct">The cancellation token that aborts the browse request.</param>
|
|
/// <returns>The child nodes discovered under <paramref name="parentNodeId"/>.</returns>
|
|
Task<IReadOnlyList<BrowseResult>> BrowseAsync(NodeId? parentNodeId = null, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Subscribes to live data changes for a node.
|
|
/// </summary>
|
|
/// <param name="nodeId">The node whose value changes should be monitored.</param>
|
|
/// <param name="intervalMs">The monitored-item sampling and publishing interval in milliseconds.</param>
|
|
/// <param name="ct">The cancellation token that aborts subscription creation.</param>
|
|
/// <returns>A task that represents the asynchronous operation.</returns>
|
|
Task SubscribeAsync(NodeId nodeId, int intervalMs = 1000, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Removes a previously created live-data subscription for a node.
|
|
/// </summary>
|
|
/// <param name="nodeId">The node whose live-data subscription should be removed.</param>
|
|
/// <param name="ct">The cancellation token that aborts the unsubscribe request.</param>
|
|
/// <returns>A task that represents the asynchronous operation.</returns>
|
|
Task UnsubscribeAsync(NodeId nodeId, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Subscribes to OPC UA alarm and condition events for a source node or the server root.
|
|
/// </summary>
|
|
/// <param name="sourceNodeId">The event source to monitor, or the server object when omitted.</param>
|
|
/// <param name="intervalMs">The publishing interval in milliseconds for the alarm subscription.</param>
|
|
/// <param name="ct">The cancellation token that aborts alarm subscription creation.</param>
|
|
/// <returns>A task that represents the asynchronous operation.</returns>
|
|
Task SubscribeAlarmsAsync(NodeId? sourceNodeId = null, int intervalMs = 1000, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Removes the active alarm subscription.
|
|
/// </summary>
|
|
/// <param name="ct">The cancellation token that aborts alarm subscription cleanup.</param>
|
|
/// <returns>A task that represents the asynchronous operation.</returns>
|
|
Task UnsubscribeAlarmsAsync(CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Requests retained alarm conditions again so a client can repopulate its alarm list after reconnecting.
|
|
/// </summary>
|
|
/// <param name="ct">The cancellation token that aborts the condition refresh request.</param>
|
|
/// <returns>A task that represents the asynchronous operation.</returns>
|
|
Task RequestConditionRefreshAsync(CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Acknowledges an active condition using the event identifier returned by an alarm notification.
|
|
/// </summary>
|
|
/// <param name="conditionNodeId">The condition node associated with the alarm event being acknowledged.</param>
|
|
/// <param name="eventId">The event identifier returned by the OPC UA server for the alarm event.</param>
|
|
/// <param name="comment">The operator acknowledgment comment to write with the method call.</param>
|
|
/// <param name="ct">The cancellation token that aborts the acknowledgment request.</param>
|
|
/// <returns>
|
|
/// <see cref="StatusCodes.Good"/> on success, or the server's bad <see cref="StatusCode"/>
|
|
/// (from the underlying <see cref="ServiceResultException"/>) when the acknowledge call
|
|
/// returns a bad result. Other transport-level failures still surface as exceptions.
|
|
/// </returns>
|
|
Task<StatusCode> AcknowledgeAlarmAsync(string conditionNodeId, byte[] eventId, string comment, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Confirms an acknowledged condition (Part 9 two-stage acknowledgment) using the event identifier returned by an alarm notification.
|
|
/// </summary>
|
|
/// <param name="conditionNodeId">The condition node associated with the alarm event being confirmed.</param>
|
|
/// <param name="eventId">The event identifier returned by the OPC UA server for the alarm event.</param>
|
|
/// <param name="comment">The operator confirmation comment to write with the method call.</param>
|
|
/// <param name="ct">The cancellation token that aborts the confirmation request.</param>
|
|
/// <returns>
|
|
/// <see cref="StatusCodes.Good"/> on success, or the server's bad <see cref="StatusCode"/>
|
|
/// (from the underlying <see cref="ServiceResultException"/>) when the confirm call
|
|
/// returns a bad result. Other transport-level failures still surface as exceptions.
|
|
/// </returns>
|
|
Task<StatusCode> ConfirmAlarmAsync(string conditionNodeId, byte[] eventId, string comment, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Attaches an operator comment to a condition (Part 9 <c>AddComment</c>) using the event identifier of an alarm notification.
|
|
/// </summary>
|
|
/// <param name="conditionNodeId">The condition node the comment is attached to.</param>
|
|
/// <param name="eventId">The event identifier returned by the OPC UA server for the alarm event.</param>
|
|
/// <param name="comment">The operator comment.</param>
|
|
/// <param name="ct">The cancellation token that aborts the request.</param>
|
|
/// <returns><see cref="StatusCodes.Good"/> on success, or the server's bad <see cref="StatusCode"/> when the call is refused.</returns>
|
|
Task<StatusCode> AddCommentAsync(string conditionNodeId, byte[] eventId, string comment, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Shelves or unshelves an active alarm condition (OPC UA Part 9 ShelvedStateMachine).
|
|
/// </summary>
|
|
/// <param name="conditionNodeId">The condition node associated with the alarm being shelved.</param>
|
|
/// <param name="kind">The shelve operation: <c>OneShot</c>, <c>Timed</c>, or <c>Unshelve</c>.</param>
|
|
/// <param name="shelvingTimeSeconds">
|
|
/// For <c>Timed</c> shelving: the shelving duration in seconds (must be > 0).
|
|
/// This value is converted to milliseconds when passed to the OPC UA <c>TimedShelve</c> method
|
|
/// (<c>Duration</c> is milliseconds per OPC UA Part 9). Ignored for <c>OneShot</c> and <c>Unshelve</c>.
|
|
/// </param>
|
|
/// <param name="ct">The cancellation token that aborts the shelve request.</param>
|
|
/// <returns>
|
|
/// <see cref="StatusCodes.Good"/> on success, or the server's bad <see cref="StatusCode"/>
|
|
/// (from the underlying <see cref="ServiceResultException"/>) when the shelve call
|
|
/// returns a bad result. Other transport-level failures still surface as exceptions.
|
|
/// </returns>
|
|
Task<StatusCode> ShelveAlarmAsync(string conditionNodeId, ShelveKind kind, double shelvingTimeSeconds = 0, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Enables an alarm condition by invoking the OPC UA Part 9 ConditionType <c>Enable</c> method
|
|
/// (the H4 client-driven path). The method takes no input arguments.
|
|
/// </summary>
|
|
/// <param name="conditionNodeId">The condition node associated with the alarm being enabled.</param>
|
|
/// <param name="ct">The cancellation token that aborts the enable request.</param>
|
|
/// <returns>
|
|
/// <see cref="StatusCodes.Good"/> on success, or the server's bad <see cref="StatusCode"/>
|
|
/// (from the underlying <see cref="ServiceResultException"/>) when the enable call
|
|
/// returns a bad result. Other transport-level failures still surface as exceptions.
|
|
/// </returns>
|
|
Task<StatusCode> EnableAsync(string conditionNodeId, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Disables an alarm condition by invoking the OPC UA Part 9 ConditionType <c>Disable</c> method
|
|
/// (the H4 client-driven path). The method takes no input arguments.
|
|
/// </summary>
|
|
/// <param name="conditionNodeId">The condition node associated with the alarm being disabled.</param>
|
|
/// <param name="ct">The cancellation token that aborts the disable request.</param>
|
|
/// <returns>
|
|
/// <see cref="StatusCodes.Good"/> on success, or the server's bad <see cref="StatusCode"/>
|
|
/// (from the underlying <see cref="ServiceResultException"/>) when the disable call
|
|
/// returns a bad result. Other transport-level failures still surface as exceptions.
|
|
/// </returns>
|
|
Task<StatusCode> DisableAsync(string conditionNodeId, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Reads raw historical samples for a historized node.
|
|
/// </summary>
|
|
/// <param name="nodeId">The historized node whose samples should be read.</param>
|
|
/// <param name="startTime">The inclusive start of the requested history range.</param>
|
|
/// <param name="endTime">The inclusive end of the requested history range.</param>
|
|
/// <param name="maxValues">The maximum number of raw values to return.</param>
|
|
/// <param name="ct">The cancellation token that aborts the history read.</param>
|
|
/// <returns>The raw historical samples in the requested range, up to <paramref name="maxValues"/>.</returns>
|
|
Task<IReadOnlyList<DataValue>> HistoryReadRawAsync(NodeId nodeId, DateTime startTime, DateTime endTime,
|
|
int maxValues = 1000, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Reads modified-value history (Part 11, <c>IsReadModified = true</c>): what each HistoryUpdate in the window
|
|
/// replaced or deleted, with the server's modification time, update type and user name.
|
|
/// </summary>
|
|
/// <param name="nodeId">The historized node.</param>
|
|
/// <param name="startTime">Window start.</param>
|
|
/// <param name="endTime">Window end.</param>
|
|
/// <param name="maxValues">The maximum number of entries to return.</param>
|
|
/// <param name="ct">The cancellation token.</param>
|
|
/// <returns>The modification entries in server order.</returns>
|
|
Task<IReadOnlyList<HistoryModifiedEntry>> HistoryReadModifiedAsync(NodeId nodeId, DateTime startTime,
|
|
DateTime endTime, int maxValues = 1000, CancellationToken ct = default) =>
|
|
throw new NotSupportedException("This client service does not support modified-value history reads.");
|
|
|
|
/// <summary>
|
|
/// Sends a HistoryUpdate request (insert/replace/update or delete) for the supplied details.
|
|
/// </summary>
|
|
/// <param name="details">The history update details (UpdateDataDetails, DeleteRawModifiedDetails, DeleteAtTimeDetails...).</param>
|
|
/// <param name="ct">The cancellation token that aborts the call.</param>
|
|
/// <returns>The overall service result and per-item status codes.</returns>
|
|
Task<HistoryUpdateOutcome> HistoryUpdateAsync(HistoryUpdateDetails details, CancellationToken ct = default)
|
|
=> throw new NotSupportedException("HistoryUpdate is not supported by this client service.");
|
|
|
|
/// <summary>
|
|
/// Reads aggregate historical values for a historized node using an OPC UA aggregate function.
|
|
/// </summary>
|
|
/// <param name="nodeId">The historized node whose processed values should be read.</param>
|
|
/// <param name="startTime">The inclusive start of the requested processed-history range.</param>
|
|
/// <param name="endTime">The inclusive end of the requested processed-history range.</param>
|
|
/// <param name="aggregate">The aggregate function the operator selected for processed history.</param>
|
|
/// <param name="intervalMs">The processing interval, in milliseconds, for each aggregate bucket.</param>
|
|
/// <param name="ct">The cancellation token that aborts the processed history request.</param>
|
|
/// <returns>The aggregated historical values for each processing interval in the requested range.</returns>
|
|
Task<IReadOnlyList<DataValue>> HistoryReadAggregateAsync(NodeId nodeId, DateTime startTime, DateTime endTime,
|
|
AggregateType aggregate, double intervalMs = 3600000, CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Reads redundancy status data such as redundancy mode, service level, and partner endpoint URIs.
|
|
/// </summary>
|
|
/// <param name="ct">The cancellation token that aborts redundancy inspection.</param>
|
|
/// <returns>The current redundancy status of the connected server.</returns>
|
|
Task<RedundancyInfo> GetRedundancyInfoAsync(CancellationToken ct = default);
|
|
|
|
/// <summary>
|
|
/// Raised when a subscribed node produces a new live data value.
|
|
/// </summary>
|
|
event EventHandler<DataChangedEventArgs>? DataChanged;
|
|
|
|
/// <summary>
|
|
/// Raised when an alarm or condition event is received from the server.
|
|
/// </summary>
|
|
event EventHandler<AlarmEventArgs>? AlarmEvent;
|
|
|
|
/// <summary>
|
|
/// Raised when the client changes connection state during connect, disconnect, or failover.
|
|
/// </summary>
|
|
event EventHandler<ConnectionStateChangedEventArgs>? ConnectionStateChanged;
|
|
}
|