feat(cli): add enable/disable condition commands (H4 client path)

2026-06-19 01:48:21 -04:00
parent eb328e5761
commit 88d5ba45bf
10 changed files with 488 additions and 0 deletions
@@ -0,0 +1,55 @@
+using CliFx.Attributes;
+using CliFx.Infrastructure;
+using Opc.Ua;
+using ZB.MOM.WW.OtOpcUa.Client.Shared;
+
+namespace ZB.MOM.WW.OtOpcUa.Client.CLI.Commands;
+
+[Command("disable", Description = "Disable an alarm condition (OPC UA Part 9 ConditionType Disable)")]
+public class DisableCommand : CommandBase
+{
+    /// <summary>
+    /// Creates the disable command used to disable an OPC UA alarm condition from the terminal.
+    /// </summary>
+    /// <param name="factory">The factory that creates the shared client service for the command run.</param>
+    public DisableCommand(IOpcUaClientServiceFactory factory) : base(factory)
+    {
+    }
+
+    /// <summary>
+    /// Gets the condition node ID of the alarm to disable.
+    /// </summary>
+    [CommandOption("node", 'n', Description = "Condition node ID of the alarm to disable", IsRequired = true)]
+    public string NodeId { get; init; } = default!;
+
+    /// <summary>
+    /// Connects to the server and disables the specified alarm condition.
+    /// </summary>
+    /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    public override async ValueTask ExecuteAsync(IConsole console)
+    {
+        ConfigureLogging();
+
+        IOpcUaClientService? service = null;
+        try
+        {
+            var ct = console.RegisterCancellationHandler();
+            (service, _) = await CreateServiceAndConnectAsync(ct);
+
+            var statusCode = await service.DisableAsync(NodeId, ct);
+
+            if (StatusCode.IsGood(statusCode))
+                await console.Output.WriteLineAsync($"Disable successful: {NodeId}");
+            else
+                await console.Output.WriteLineAsync($"Disable failed: {statusCode}");
+        }
+        finally
+        {
+            if (service != null)
+            {
+                await service.DisconnectAsync();
+                service.Dispose();
+            }
+        }
+    }
+}
@@ -0,0 +1,55 @@
+using CliFx.Attributes;
+using CliFx.Infrastructure;
+using Opc.Ua;
+using ZB.MOM.WW.OtOpcUa.Client.Shared;
+
+namespace ZB.MOM.WW.OtOpcUa.Client.CLI.Commands;
+
+[Command("enable", Description = "Enable an alarm condition (OPC UA Part 9 ConditionType Enable)")]
+public class EnableCommand : CommandBase
+{
+    /// <summary>
+    /// Creates the enable command used to enable an OPC UA alarm condition from the terminal.
+    /// </summary>
+    /// <param name="factory">The factory that creates the shared client service for the command run.</param>
+    public EnableCommand(IOpcUaClientServiceFactory factory) : base(factory)
+    {
+    }
+
+    /// <summary>
+    /// Gets the condition node ID of the alarm to enable.
+    /// </summary>
+    [CommandOption("node", 'n', Description = "Condition node ID of the alarm to enable", IsRequired = true)]
+    public string NodeId { get; init; } = default!;
+
+    /// <summary>
+    /// Connects to the server and enables the specified alarm condition.
+    /// </summary>
+    /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    public override async ValueTask ExecuteAsync(IConsole console)
+    {
+        ConfigureLogging();
+
+        IOpcUaClientService? service = null;
+        try
+        {
+            var ct = console.RegisterCancellationHandler();
+            (service, _) = await CreateServiceAndConnectAsync(ct);
+
+            var statusCode = await service.EnableAsync(NodeId, ct);
+
+            if (StatusCode.IsGood(statusCode))
+                await console.Output.WriteLineAsync($"Enable successful: {NodeId}");
+            else
+                await console.Output.WriteLineAsync($"Enable failed: {statusCode}");
+        }
+        finally
+        {
+            if (service != null)
+            {
+                await service.DisconnectAsync();
+                service.Dispose();
+            }
+        }
+    }
+}
@@ -135,6 +135,32 @@ public interface IOpcUaClientService : IDisposable
    /// </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>
@@ -461,6 +461,50 @@ public sealed class OpcUaClientService : IOpcUaClientService
        return StatusCodes.Good;
    }

+    /// <inheritdoc />
+    public Task<StatusCode> EnableAsync(string conditionNodeId, CancellationToken ct = default) =>
+        CallEnableDisableAsync(conditionNodeId, enabling: true, ct);
+
+    /// <inheritdoc />
+    public Task<StatusCode> DisableAsync(string conditionNodeId, CancellationToken ct = default) =>
+        CallEnableDisableAsync(conditionNodeId, enabling: false, ct);
+
+    /// <summary>
+    /// Shared body for the H4 Enable/Disable client path. Invokes the OPC UA Part 9 ConditionType
+    /// <c>Enable</c>/<c>Disable</c> method (no input arguments) on the condition object node, mirroring
+    /// the <see cref="AcknowledgeAlarmAsync"/> convention: the methods live on the <c>.Condition</c>
+    /// child node, and a bad call result surfaces as the returned <see cref="StatusCode"/> rather than
+    /// escaping as an uncaught <see cref="ServiceResultException"/>.
+    /// </summary>
+    /// <param name="conditionNodeId">The condition node associated with the alarm.</param>
+    /// <param name="enabling"><c>true</c> to invoke Enable; <c>false</c> to invoke Disable.</param>
+    /// <param name="ct">The cancellation token that aborts the request.</param>
+    private async Task<StatusCode> CallEnableDisableAsync(string conditionNodeId, bool enabling, CancellationToken ct)
+    {
+        ThrowIfDisposed();
+        ThrowIfNotConnected();
+
+        // Enable/Disable live on the same .Condition child node as Acknowledge/Confirm.
+        var conditionObjId = conditionNodeId.EndsWith(".Condition")
+            ? NodeId.Parse(conditionNodeId)
+            : NodeId.Parse(conditionNodeId + ".Condition");
+        var methodId = enabling ? MethodIds.ConditionType_Enable : MethodIds.ConditionType_Disable;
+
+        try
+        {
+            await _session!.CallMethodAsync(conditionObjId, methodId, [], ct);
+        }
+        catch (ServiceResultException ex)
+        {
+            Logger.Warning(ex, "Failed to {Operation} alarm on {ConditionId} (status {Status})",
+                enabling ? "enable" : "disable", conditionNodeId, ex.StatusCode);
+            return ex.StatusCode;
+        }
+
+        Logger.Debug("{Operation} alarm on {ConditionId}", enabling ? "Enabled" : "Disabled", conditionNodeId);
+        return StatusCodes.Good;
+    }
+
    /// <inheritdoc />
    public async Task<IReadOnlyList<DataValue>> HistoryReadRawAsync(
        NodeId nodeId, DateTime startTime, DateTime endTime, int maxValues = 1000, CancellationToken ct = default)
@@ -0,0 +1,75 @@
+using Opc.Ua;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Client.CLI.Commands;
+using ZB.MOM.WW.OtOpcUa.Client.CLI.Tests.Fakes;
+
+namespace ZB.MOM.WW.OtOpcUa.Client.CLI.Tests;
+
+public class DisableCommandTests
+{
+    /// <summary>Verifies that a successful disable prints a success message and targets the node.</summary>
+    [Fact]
+    public async Task Execute_Success_PrintsSuccessMessage()
+    {
+        var fakeService = new FakeOpcUaClientService
+        {
+            DisableResult = StatusCodes.Good
+        };
+        var factory = new FakeOpcUaClientServiceFactory(fakeService);
+        var command = new DisableCommand(factory)
+        {
+            Url = "opc.tcp://localhost:4840",
+            NodeId = "ns=2;s=MyAlarm"
+        };
+
+        using var console = TestConsoleHelper.CreateConsole();
+        await command.ExecuteAsync(console);
+
+        var output = TestConsoleHelper.GetOutput(console);
+        output.ShouldContain("Disable successful");
+        fakeService.DisableCalls.Count.ShouldBe(1);
+        fakeService.DisableCalls[0].ShouldBe("ns=2;s=MyAlarm");
+    }
+
+    /// <summary>Verifies that a bad StatusCode from the service prints a failure message.</summary>
+    [Fact]
+    public async Task Execute_BadStatus_PrintsFailureMessage()
+    {
+        var fakeService = new FakeOpcUaClientService
+        {
+            DisableResult = StatusCodes.BadConditionAlreadyDisabled
+        };
+        var factory = new FakeOpcUaClientServiceFactory(fakeService);
+        var command = new DisableCommand(factory)
+        {
+            Url = "opc.tcp://localhost:4840",
+            NodeId = "ns=2;s=MyAlarm"
+        };
+
+        using var console = TestConsoleHelper.CreateConsole();
+        await command.ExecuteAsync(console);
+
+        var output = TestConsoleHelper.GetOutput(console);
+        output.ShouldContain("Disable failed");
+    }
+
+    /// <summary>Verifies that the command disconnects and disposes in the finally block.</summary>
+    [Fact]
+    public async Task Execute_DisconnectsInFinally()
+    {
+        var fakeService = new FakeOpcUaClientService();
+        var factory = new FakeOpcUaClientServiceFactory(fakeService);
+        var command = new DisableCommand(factory)
+        {
+            Url = "opc.tcp://localhost:4840",
+            NodeId = "ns=2;s=MyAlarm"
+        };
+
+        using var console = TestConsoleHelper.CreateConsole();
+        await command.ExecuteAsync(console);
+
+        fakeService.DisconnectCalled.ShouldBeTrue();
+        fakeService.DisposeCalled.ShouldBeTrue();
+    }
+}
@@ -0,0 +1,75 @@
+using Opc.Ua;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Client.CLI.Commands;
+using ZB.MOM.WW.OtOpcUa.Client.CLI.Tests.Fakes;
+
+namespace ZB.MOM.WW.OtOpcUa.Client.CLI.Tests;
+
+public class EnableCommandTests
+{
+    /// <summary>Verifies that a successful enable prints a success message and targets the node.</summary>
+    [Fact]
+    public async Task Execute_Success_PrintsSuccessMessage()
+    {
+        var fakeService = new FakeOpcUaClientService
+        {
+            EnableResult = StatusCodes.Good
+        };
+        var factory = new FakeOpcUaClientServiceFactory(fakeService);
+        var command = new EnableCommand(factory)
+        {
+            Url = "opc.tcp://localhost:4840",
+            NodeId = "ns=2;s=MyAlarm"
+        };
+
+        using var console = TestConsoleHelper.CreateConsole();
+        await command.ExecuteAsync(console);
+
+        var output = TestConsoleHelper.GetOutput(console);
+        output.ShouldContain("Enable successful");
+        fakeService.EnableCalls.Count.ShouldBe(1);
+        fakeService.EnableCalls[0].ShouldBe("ns=2;s=MyAlarm");
+    }
+
+    /// <summary>Verifies that a bad StatusCode from the service prints a failure message.</summary>
+    [Fact]
+    public async Task Execute_BadStatus_PrintsFailureMessage()
+    {
+        var fakeService = new FakeOpcUaClientService
+        {
+            EnableResult = StatusCodes.BadConditionAlreadyEnabled
+        };
+        var factory = new FakeOpcUaClientServiceFactory(fakeService);
+        var command = new EnableCommand(factory)
+        {
+            Url = "opc.tcp://localhost:4840",
+            NodeId = "ns=2;s=MyAlarm"
+        };
+
+        using var console = TestConsoleHelper.CreateConsole();
+        await command.ExecuteAsync(console);
+
+        var output = TestConsoleHelper.GetOutput(console);
+        output.ShouldContain("Enable failed");
+    }
+
+    /// <summary>Verifies that the command disconnects and disposes in the finally block.</summary>
+    [Fact]
+    public async Task Execute_DisconnectsInFinally()
+    {
+        var fakeService = new FakeOpcUaClientService();
+        var factory = new FakeOpcUaClientServiceFactory(fakeService);
+        var command = new EnableCommand(factory)
+        {
+            Url = "opc.tcp://localhost:4840",
+            NodeId = "ns=2;s=MyAlarm"
+        };
+
+        using var console = TestConsoleHelper.CreateConsole();
+        await command.ExecuteAsync(console);
+
+        fakeService.DisconnectCalled.ShouldBeTrue();
+        fakeService.DisposeCalled.ShouldBeTrue();
+    }
+}
@@ -262,6 +262,32 @@ public sealed class FakeOpcUaClientService : IOpcUaClientService
        return Task.FromResult(ShelveAlarmResult);
    }

+    /// <summary>Gets the list of condition node IDs passed to EnableAsync calls.</summary>
+    public List<string> EnableCalls { get; } = [];
+
+    /// <summary>Gets or sets the status code returned by EnableAsync.</summary>
+    public StatusCode EnableResult { get; set; } = StatusCodes.Good;
+
+    /// <inheritdoc />
+    public Task<StatusCode> EnableAsync(string conditionNodeId, CancellationToken ct = default)
+    {
+        EnableCalls.Add(conditionNodeId);
+        return Task.FromResult(EnableResult);
+    }
+
+    /// <summary>Gets the list of condition node IDs passed to DisableAsync calls.</summary>
+    public List<string> DisableCalls { get; } = [];
+
+    /// <summary>Gets or sets the status code returned by DisableAsync.</summary>
+    public StatusCode DisableResult { get; set; } = StatusCodes.Good;
+
+    /// <inheritdoc />
+    public Task<StatusCode> DisableAsync(string conditionNodeId, CancellationToken ct = default)
+    {
+        DisableCalls.Add(conditionNodeId);
+        return Task.FromResult(DisableResult);
+    }
+
    /// <inheritdoc />
    public Task<IReadOnlyList<DataValue>> HistoryReadRawAsync(
        NodeId nodeId, DateTime startTime, DateTime endTime, int maxValues = 1000, CancellationToken ct = default)
@@ -208,11 +208,25 @@ internal sealed class FakeSessionAdapter : ISessionAdapter
    /// </summary>
    public List<object[]> CallMethodInputArgs { get; } = [];

+    /// <summary>
+    /// Records the object node id passed to each <see cref="CallMethodAsync"/> invocation,
+    /// so tests can assert which condition object a method was invoked on.
+    /// </summary>
+    public List<NodeId> CallMethodObjectIds { get; } = [];
+
+    /// <summary>
+    /// Records the method node id passed to each <see cref="CallMethodAsync"/> invocation,
+    /// so tests can assert the correct Part 9 method (e.g. Enable/Disable) was invoked.
+    /// </summary>
+    public List<NodeId> CallMethodMethodIds { get; } = [];
+
    /// <inheritdoc />
    public Task<IList<object>?> CallMethodAsync(NodeId objectId, NodeId methodId, object[] inputArguments,
        CancellationToken ct = default)
    {
        CallMethodCount++;
+        CallMethodObjectIds.Add(objectId);
+        CallMethodMethodIds.Add(methodId);
        CallMethodInputArgs.Add(inputArguments);
        if (CallMethodException != null)
            throw CallMethodException;
@@ -1174,6 +1174,88 @@ public class OpcUaClientServiceTests : IDisposable
        result.Code.ShouldBe(StatusCodes.BadConditionAlreadyShelved);
    }

+    // --- Enable / Disable tests (H4 client path) ---
+
+    /// <summary>
+    /// Verifies that EnableAsync invokes the ConditionType_Enable method with no input
+    /// arguments and returns <see cref="StatusCodes.Good"/> on success.
+    /// </summary>
+    [Fact]
+    public async Task EnableAsync_OnSuccess_CallsEnableMethodWithNoArgs()
+    {
+        var session = new FakeSessionAdapter();
+        _sessionFactory.EnqueueSession(session);
+        await _service.ConnectAsync(ValidSettings());
+
+        var result = await _service.EnableAsync("ns=2;s=Cond");
+
+        result.ShouldBe(StatusCodes.Good);
+        session.CallMethodCount.ShouldBe(1);
+        session.CallMethodMethodIds[0].ShouldBe(MethodIds.ConditionType_Enable);
+        session.CallMethodInputArgs[0].ShouldBeEmpty();
+    }
+
+    /// <summary>
+    /// Verifies that DisableAsync invokes the ConditionType_Disable method with no input
+    /// arguments and returns <see cref="StatusCodes.Good"/> on success.
+    /// </summary>
+    [Fact]
+    public async Task DisableAsync_OnSuccess_CallsDisableMethodWithNoArgs()
+    {
+        var session = new FakeSessionAdapter();
+        _sessionFactory.EnqueueSession(session);
+        await _service.ConnectAsync(ValidSettings());
+
+        var result = await _service.DisableAsync("ns=2;s=Cond");
+
+        result.ShouldBe(StatusCodes.Good);
+        session.CallMethodCount.ShouldBe(1);
+        session.CallMethodMethodIds[0].ShouldBe(MethodIds.ConditionType_Disable);
+        session.CallMethodInputArgs[0].ShouldBeEmpty();
+    }
+
+    /// <summary>
+    /// Verifies that a <see cref="ServiceResultException"/> from the session is captured and
+    /// returned as a bad <see cref="StatusCode"/> rather than propagating to the caller.
+    /// </summary>
+    [Fact]
+    public async Task EnableAsync_OnServiceResultException_ReturnsBadStatusCode()
+    {
+        var session = new FakeSessionAdapter
+        {
+            CallMethodException = new ServiceResultException(
+                StatusCodes.BadConditionAlreadyEnabled, "already enabled")
+        };
+        _sessionFactory.EnqueueSession(session);
+        await _service.ConnectAsync(ValidSettings());
+
+        var result = await _service.EnableAsync("ns=2;s=Cond");
+
+        StatusCode.IsBad(result).ShouldBeTrue();
+        result.Code.ShouldBe(StatusCodes.BadConditionAlreadyEnabled);
+    }
+
+    /// <summary>
+    /// Verifies that a <see cref="ServiceResultException"/> from the session is captured and
+    /// returned as a bad <see cref="StatusCode"/> rather than propagating to the caller.
+    /// </summary>
+    [Fact]
+    public async Task DisableAsync_OnServiceResultException_ReturnsBadStatusCode()
+    {
+        var session = new FakeSessionAdapter
+        {
+            CallMethodException = new ServiceResultException(
+                StatusCodes.BadConditionAlreadyDisabled, "already disabled")
+        };
+        _sessionFactory.EnqueueSession(session);
+        await _service.ConnectAsync(ValidSettings());
+
+        var result = await _service.DisableAsync("ns=2;s=Cond");
+
+        StatusCode.IsBad(result).ShouldBeTrue();
+        result.Code.ShouldBe(StatusCodes.BadConditionAlreadyDisabled);
+    }
+
    // --- Alarm fallback path (Client.Shared-011) ---

    /// <summary>
@@ -301,6 +301,42 @@ public sealed class FakeOpcUaClientService : IOpcUaClientService
        return Task.FromResult(ShelveResult);
    }

+    /// <summary>Gets or sets the status code returned by enable operations in UI tests.</summary>
+    public StatusCode EnableResult { get; set; } = StatusCodes.Good;
+    /// <summary>Gets or sets the exception thrown to simulate alarm enable failures in the UI.</summary>
+    public Exception? EnableException { get; set; }
+    /// <summary>Gets the number of times EnableAsync has been called.</summary>
+    public int EnableCallCount { get; private set; }
+    /// <summary>Gets the conditionNodeId of the last EnableAsync call.</summary>
+    public string? LastEnableCall { get; private set; }
+
+    /// <inheritdoc />
+    public Task<StatusCode> EnableAsync(string conditionNodeId, CancellationToken ct = default)
+    {
+        EnableCallCount++;
+        LastEnableCall = conditionNodeId;
+        if (EnableException != null) throw EnableException;
+        return Task.FromResult(EnableResult);
+    }
+
+    /// <summary>Gets or sets the status code returned by disable operations in UI tests.</summary>
+    public StatusCode DisableResult { get; set; } = StatusCodes.Good;
+    /// <summary>Gets or sets the exception thrown to simulate alarm disable failures in the UI.</summary>
+    public Exception? DisableException { get; set; }
+    /// <summary>Gets the number of times DisableAsync has been called.</summary>
+    public int DisableCallCount { get; private set; }
+    /// <summary>Gets the conditionNodeId of the last DisableAsync call.</summary>
+    public string? LastDisableCall { get; private set; }
+
+    /// <inheritdoc />
+    public Task<StatusCode> DisableAsync(string conditionNodeId, CancellationToken ct = default)
+    {
+        DisableCallCount++;
+        LastDisableCall = conditionNodeId;
+        if (DisableException != null) throw DisableException;
+        return Task.FromResult(DisableResult);
+    }
+
    /// <inheritdoc />
    public Task<IReadOnlyList<DataValue>> HistoryReadRawAsync(NodeId nodeId, DateTime startTime, DateTime endTime,
        int maxValues = 1000, CancellationToken ct = default)