dohertj2/lmxopcua
1
0
Fork 0
Code Issues 13 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Auto: opcuaclient-9 — method node mirroring + Call passthrough

Browse Source 
Adds the 9th capability interface (IMethodInvoker) so the OPC UA Client
driver can mirror upstream OPC UA Method nodes into the local address
space and forward Call invocations as Session.CallAsync. Method-bearing
servers (e.g. ProgramStateMachine, Acknowledge / Confirm methods, custom
control surfaces) now show up downstream instead of being silently
filtered out.

- Core.Abstractions: IMethodInvoker + MethodCallResult; default no-op
  IAddressSpaceBuilder.RegisterMethodNode + MirroredMethodNodeInfo +
  MethodArgumentInfo. Default impls keep tag-based drivers and existing
  builders compiling without forced overrides.
- OpcUaClientDriver: BrowseRecursiveAsync now lifts the Method node-class
  filter; for each method it walks HasProperty to pick up InputArguments
  + OutputArguments and decodes the Argument extension objects into
  MethodArgumentInfo. Status-codes pass through verbatim (cascading
  quality), local NodeId-parse + lost-session faults surface as
  BadNodeIdInvalid / BadCommunicationError.
- 7 new unit tests cover the capability surface, the DTO shapes, and the
  back-compat default no-op for RegisterMethodNode. Suite green at
  160/160.

Server-side OnCallMethod dispatch (wiring local MethodNode handlers to
IMethodInvoker.CallMethodAsync inside DriverNodeManager) is deferred to
a follow-up — the driver-side surface + browse mirror ship cleanly here.

Closes #281

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-04-25 20:52:39 -04:00
parent 0f3abed4c7
commit 07abee5f6d
4 changed files with 588 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAddressSpaceBuilder.cs
View File

@@ -60,8 +60,90 @@ public interface IAddressSpaceBuilder
/// </para>
/// </remarks>
void RegisterTypeNode(MirroredTypeNodeInfo info) { /* default: no-op */ }
/// <summary>
/// Register a method node mirrored from an upstream OPC UA server. The method is
/// registered as a child of the current builder scope (i.e. the folder representing
/// the upstream Object that owns the method). Optional surface — drivers that don't
/// mirror methods simply never call it; address-space builders that don't materialise
/// method nodes can leave the default no-op in place. Default implementation drops
/// the call so adding this method doesn't break existing
/// <see cref="IAddressSpaceBuilder"/> implementations.
/// </summary>
/// <param name="info">Metadata describing the method node, including input/output argument schemas.</param>
/// <remarks>
/// <para>
/// The OPC UA Client driver is the primary caller — it picks up
/// <c>NodeClass.Method</c> nodes during the <c>HierarchicalReferences</c> browse
/// pass, then walks each method's <c>HasProperty</c> references to harvest the
/// <c>InputArguments</c> / <c>OutputArguments</c> property values.
/// </para>
/// <para>
/// The OPC UA server-side <c>DriverNodeManager</c> overrides this to materialize
/// a real <c>MethodNode</c> in the local address space and wire its
/// <c>OnCallMethod</c> handler to the driver's
/// <see cref="IMethodInvoker.CallMethodAsync"/>. Other builders (Galaxy, Modbus,
/// FOCAS, S7, TwinCAT, AB-CIP, AB-Legacy) ignore the projection because their
/// backends don't expose method nodes.
/// </para>
/// </remarks>
void RegisterMethodNode(MirroredMethodNodeInfo info) { /* default: no-op */ }
}
/// <summary>
/// Metadata describing a single method node mirrored from an upstream OPC UA server.
/// Built by the OPC UA Client driver during the discovery browse pass and consumed by
/// <see cref="IAddressSpaceBuilder.RegisterMethodNode"/>.
/// </summary>
/// <param name="BrowseName">OPC UA BrowseName segment from the upstream BrowseName.</param>
/// <param name="DisplayName">Human-readable display name; falls back to <paramref name="BrowseName"/>.</param>
/// <param name="ObjectNodeId">
/// Stringified NodeId of the parent Object that owns this method — the <c>ObjectId</c>
/// argument the dispatcher passes back to <see cref="IMethodInvoker.CallMethodAsync"/>.
/// </param>
/// <param name="MethodNodeId">
/// Stringified NodeId of the method node itself — the <c>MethodId</c> argument.
/// </param>
/// <param name="InputArguments">
/// Declaration of the method's input arguments, in order. <c>null</c> or empty when the
/// method takes no inputs (or the upstream property couldn't be read).
/// </param>
/// <param name="OutputArguments">
/// Declaration of the method's output arguments, in order. <c>null</c> or empty when the
/// method returns no outputs (or the upstream property couldn't be read).
/// </param>
public sealed record MirroredMethodNodeInfo(
string BrowseName,
string DisplayName,
string ObjectNodeId,
string MethodNodeId,
IReadOnlyList<MethodArgumentInfo>? InputArguments,
IReadOnlyList<MethodArgumentInfo>? OutputArguments);
/// <summary>
/// One row of an OPC UA Argument array — name + data type + array hint. Mirrors the
/// <c>Opc.Ua.Argument</c> structure but without the SDK-only types so this DTO can live
/// in <c>Core.Abstractions</c>.
/// </summary>
/// <param name="Name">Argument name from the upstream Argument structure.</param>
/// <param name="DriverDataType">
/// Mapped local <see cref="DriverDataType"/>. Unknown / structured upstream types fall
/// through to <see cref="DriverDataType.String"/> — same convention as variable mirroring.
/// </param>
/// <param name="ValueRank">
/// OPC UA ValueRank: <c>-1</c> = scalar, <c>0</c> = OneOrMoreDimensions, <c>1+</c> = array
/// dimensions. Driven directly from the upstream Argument's ValueRank.
/// </param>
/// <param name="Description">
/// Human-readable description from the upstream Argument structure; <c>null</c> when the
/// upstream doesn't carry one.
/// </param>
public sealed record MethodArgumentInfo(
string Name,
DriverDataType DriverDataType,
int ValueRank,
string? Description);
/// <summary>
/// Categorises a mirrored type-definition node so the receiving builder can route it into
/// the right OPC UA standard subtree (<c>ObjectTypesFolder</c>, <c>VariableTypesFolder</c>,

82
src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IMethodInvoker.cs Normal file
View File

@@ -0,0 +1,82 @@
namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;
/// <summary>
/// Driver capability for invoking OPC UA Methods on the upstream backend (the OPC UA
/// <c>Call</c> service). Optional — only drivers whose backends carry method nodes
/// implement it. Currently the OPC UA Client driver is the only implementer; tag-based
/// drivers (Modbus, S7, FOCAS, Galaxy, AB-CIP, AB-Legacy, TwinCAT) don't expose method
/// nodes so they don't need this surface.
/// </summary>
/// <remarks>
/// <para>
/// Per <c>docs/v2/plan.md</c> decision #4 (composable capability interfaces) — the
/// server-side <c>DriverNodeManager</c> discovers method-bearing drivers via an
/// <c>is IMethodInvoker</c> check and routes <c>OnCallMethod</c> handlers to
/// <see cref="CallMethodAsync"/>. Drivers that don't implement the interface simply
/// never have method nodes registered for them.
/// </para>
/// <para>
/// The address-space mirror is driven by <see cref="IAddressSpaceBuilder.RegisterMethodNode"/>
/// — drivers register the method node + its <c>InputArguments</c> /
/// <c>OutputArguments</c> properties during discovery, then invocations land back on
/// <see cref="CallMethodAsync"/> via the server-side dispatcher.
/// </para>
/// </remarks>
public interface IMethodInvoker
{
/// <summary>
/// Invoke an upstream OPC UA Method. The driver translates input arguments into the
/// wire-level <c>CallMethodRequest</c>, dispatches via the active session, and packs
/// the response back into a <see cref="MethodCallResult"/>. Per-argument validation
/// errors flow through <see cref="MethodCallResult.InputArgumentResults"/>; method-level
/// errors (<c>BadMethodInvalid</c>, <c>BadUserAccessDenied</c>, etc.) flow through
/// <see cref="MethodCallResult.StatusCode"/>.
/// </summary>
/// <param name="objectNodeId">
/// Stringified NodeId of the OPC UA Object that owns the method (the <c>ObjectId</c>
/// field of <c>CallMethodRequest</c>). Same serialization as <c>IReadable</c>'s
/// <c>fullReference</c> — <c>ns=2;s=…</c> / <c>i=…</c> / <c>nsu=…;…</c>.
/// </param>
/// <param name="methodNodeId">
/// Stringified NodeId of the Method node itself (the <c>MethodId</c> field).
/// </param>
/// <param name="inputs">
/// Input arguments in declaration order. The driver wraps each value as a
/// <c>Variant</c>; callers pass CLR primitives (plus arrays) — the wire-level
/// encoding is the driver's concern.
/// </param>
/// <param name="cancellationToken">Per-call cancellation.</param>
/// <returns>
/// Result of the call — see <see cref="MethodCallResult"/>. Never throws for a
/// <c>Bad</c> upstream status; the bad code is surfaced via the result so the caller
/// can map it onto an OPC UA service-result for downstream clients.
/// </returns>
Task<MethodCallResult> CallMethodAsync(
string objectNodeId,
string methodNodeId,
object[] inputs,
CancellationToken cancellationToken);
}
/// <summary>
/// Result of a single OPC UA <c>Call</c> service invocation.
/// </summary>
/// <param name="StatusCode">
/// Method-level status. <c>0</c> = Good. Bad codes pass through verbatim from the
/// upstream so downstream clients see the canonical OPC UA error (e.g.
/// <c>BadMethodInvalid</c>, <c>BadUserAccessDenied</c>, <c>BadArgumentsMissing</c>).
/// </param>
/// <param name="Outputs">
/// Output argument values in declaration order. <c>null</c> when the upstream returned
/// no output arguments (or returned a Bad status before producing any).
/// </param>
/// <param name="InputArgumentResults">
/// Per-input-argument status codes. <c>null</c> when the upstream didn't surface
/// per-argument validation results (typical for Good calls). Each entry is the OPC UA
/// status code for the matching input argument — drivers can use this to surface
/// <c>BadTypeMismatch</c>, <c>BadOutOfRange</c>, etc. on a specific argument.
/// </param>
public sealed record MethodCallResult(
uint StatusCode,
object[]? Outputs,
uint[]? InputArgumentResults);

245
src/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/OpcUaClientDriver.cs
View File

@@ -29,7 +29,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient;
/// </para>
/// </remarks>
public sealed class OpcUaClientDriver(OpcUaClientDriverOptions options, string driverInstanceId)
: IDriver, ITagDiscovery, IReadable, IWritable, ISubscribable, IHostConnectivityProbe, IAlarmSource, IHistoryProvider, IDisposable, IAsyncDisposable
: IDriver, ITagDiscovery, IReadable, IWritable, ISubscribable, IHostConnectivityProbe, IAlarmSource, IHistoryProvider, IMethodInvoker, IDisposable, IAsyncDisposable
{
// ---- IAlarmSource state ----
@@ -1349,7 +1349,7 @@ public sealed class OpcUaClientDriver(OpcUaClientDriverOptions options, string d
BrowseDirection = BrowseDirection.Forward,
ReferenceTypeId = ReferenceTypeIds.HierarchicalReferences,
IncludeSubtypes = true,
NodeClassMask = (uint)(NodeClass.Object | NodeClass.Variable),
NodeClassMask = (uint)(NodeClass.Object | NodeClass.Variable | NodeClass.Method),
ResultMask = (uint)(BrowseResultMask.BrowseName | BrowseResultMask.DisplayName
| BrowseResultMask.NodeClass | BrowseResultMask.TypeDefinition),
}
@@ -1408,9 +1408,153 @@ public sealed class OpcUaClientDriver(OpcUaClientDriverOptions options, string d
pendingVariables.Add(new PendingVariable(folder, browseName, displayName, childId, fullName));
increment();
}
else if (rf.NodeClass == NodeClass.Method)
{
// Methods hang off Objects (the parent of this browse step). Walk HasProperty
// to harvest InputArguments / OutputArguments — both are standard properties
// on Method nodes — then project to the address-space builder. Best-effort:
// arguments that fail to read fall through to null so the method still
// registers (the dispatcher returns BadArgumentsMissing if a client tries
// to invoke it without the argument schema).
var (inputArgs, outputArgs) = await ReadMethodArgumentsAsync(session, childId, ct)
.ConfigureAwait(false);
var methodId = BuildRemappedFullName(childId, session.NamespaceUris,
_options.Curation.NamespaceRemap);
var ownerId = BuildRemappedFullName(node, session.NamespaceUris,
_options.Curation.NamespaceRemap);
folder.RegisterMethodNode(new MirroredMethodNodeInfo(
BrowseName: browseName,
DisplayName: displayName,
ObjectNodeId: ownerId,
MethodNodeId: methodId,
InputArguments: inputArgs,
OutputArguments: outputArgs));
increment();
}
}
}
/// <summary>
/// Read a method node's <c>InputArguments</c> and <c>OutputArguments</c> properties.
/// Both are standard <c>HasProperty</c> children of any <c>NodeClass.Method</c> node
/// in OPC UA — they carry the array-of-Argument structure the dispatcher needs to
/// surface a callable signature on the local method node.
/// </summary>
/// <returns>
/// A tuple of (InputArguments, OutputArguments). Either side may be <c>null</c> when
/// the method has no arguments of that kind (the property simply isn't present on the
/// upstream method) or when the read failed — both paths are non-fatal.
/// </returns>
private static async Task<(IReadOnlyList<MethodArgumentInfo>?, IReadOnlyList<MethodArgumentInfo>?)>
ReadMethodArgumentsAsync(ISession session, NodeId methodNodeId, CancellationToken ct)
{
// Browse the method's HasProperty children to find the InputArguments /
// OutputArguments property NodeIds. Standard browse-name-based lookup would also
// work but the property NodeIds aren't stable across servers, so we walk the
// references — the SDK gives us BrowseName + NodeId in the same response.
var browseDescriptions = new BrowseDescriptionCollection
{
new()
{
NodeId = methodNodeId,
BrowseDirection = BrowseDirection.Forward,
ReferenceTypeId = ReferenceTypeIds.HasProperty,
IncludeSubtypes = true,
NodeClassMask = (uint)NodeClass.Variable,
ResultMask = (uint)(BrowseResultMask.BrowseName | BrowseResultMask.NodeClass),
}
};
NodeId? inputPropId = null;
NodeId? outputPropId = null;
try
{
var resp = await session.BrowseAsync(
requestHeader: null,
view: null,
requestedMaxReferencesPerNode: 0,
nodesToBrowse: browseDescriptions,
ct: ct).ConfigureAwait(false);
if (resp.Results.Count == 0) return (null, null);
foreach (var rf in resp.Results[0].References)
{
var name = rf.BrowseName?.Name;
if (string.IsNullOrEmpty(name)) continue;
var propId = ExpandedNodeId.ToNodeId(rf.NodeId, session.NamespaceUris);
if (NodeId.IsNull(propId)) continue;
if (string.Equals(name, BrowseNames.InputArguments, StringComparison.Ordinal))
inputPropId = propId;
else if (string.Equals(name, BrowseNames.OutputArguments, StringComparison.Ordinal))
outputPropId = propId;
}
}
catch
{
return (null, null);
}
if (inputPropId is null && outputPropId is null) return (null, null);
var nodesToRead = new ReadValueIdCollection();
if (inputPropId is not null)
nodesToRead.Add(new ReadValueId { NodeId = inputPropId, AttributeId = Attributes.Value });
if (outputPropId is not null)
nodesToRead.Add(new ReadValueId { NodeId = outputPropId, AttributeId = Attributes.Value });
DataValueCollection values;
try
{
var readResp = await session.ReadAsync(
requestHeader: null,
maxAge: 0,
timestampsToReturn: TimestampsToReturn.Neither,
nodesToRead: nodesToRead,
ct: ct).ConfigureAwait(false);
values = readResp.Results;
}
catch
{
return (null, null);
}
var idx = 0;
IReadOnlyList<MethodArgumentInfo>? inputArgs = null;
IReadOnlyList<MethodArgumentInfo>? outputArgs = null;
if (inputPropId is not null)
{
inputArgs = ConvertArguments(values[idx++]);
}
if (outputPropId is not null)
{
outputArgs = ConvertArguments(values[idx]);
}
return (inputArgs, outputArgs);
}
/// <summary>
/// Convert an OPC UA <c>InputArguments</c>/<c>OutputArguments</c> property value
/// (an array of <c>Argument</c> wrapped in <c>ExtensionObject</c>) into the local
/// <see cref="MethodArgumentInfo"/> DTO. Returns <c>null</c> when the value can't be
/// decoded — non-fatal, the method still registers without arg metadata.
/// </summary>
private static IReadOnlyList<MethodArgumentInfo>? ConvertArguments(DataValue dv)
{
if (StatusCode.IsBad(dv.StatusCode)) return null;
if (dv.Value is not ExtensionObject[] extensionArray) return null;
var result = new List<MethodArgumentInfo>(extensionArray.Length);
foreach (var ext in extensionArray)
{
if (ext?.Body is not Argument arg) continue;
result.Add(new MethodArgumentInfo(
Name: arg.Name ?? string.Empty,
DriverDataType: MapUpstreamDataType(arg.DataType),
ValueRank: arg.ValueRank,
Description: arg.Description?.Text));
}
return result;
}
/// <summary>
/// Render a NodeId as the canonical <c>nsu=&lt;uri&gt;;…</c> string, applying the
/// configured upstream→local namespace-URI remap. Index-namespace nodes (<c>ns=0</c>,
@@ -1917,6 +2061,103 @@ public sealed class OpcUaClientDriver(OpcUaClientDriverOptions options, string d
finally { _gate.Release(); }
}
// ---- IMethodInvoker ----
/// <summary>
/// Forward an OPC UA <c>Call</c> service invocation to the upstream server. The
/// method NodeId + object NodeId come from the address-space mirror set up during
/// discovery (<see cref="MirroredMethodNodeInfo"/>); input values are CLR primitives
/// wrapped into <see cref="Variant"/>s here so the cross-driver capability surface
/// stays SDK-free.
/// </summary>
/// <remarks>
/// <para>
/// Status-code passthrough: per <c>driver-specs.md</c> §8 (cascading quality), an
/// upstream Bad code is returned verbatim through <see cref="MethodCallResult.StatusCode"/>
/// rather than thrown — downstream OPC UA clients see the canonical service result
/// (<c>BadMethodInvalid</c>, <c>BadUserAccessDenied</c>, <c>BadArgumentsMissing</c>,
/// …). Local-side faults (NodeId parse, lost session) surface the corresponding
/// <c>StatusBad*</c> constants the rest of the driver uses.
/// </para>
/// <para>
/// Per-argument validation results are unpacked into a <c>uint[]</c> so the
/// <c>Core.Abstractions</c> DTO stays SDK-free. <c>null</c> when the upstream
/// didn't surface per-argument codes (typical for Good calls).
/// </para>
/// </remarks>
public async Task<MethodCallResult> CallMethodAsync(
string objectNodeId, string methodNodeId, object[] inputs, CancellationToken cancellationToken)
{
var session = RequireSession();
if (!TryParseNodeId(session, objectNodeId, out var objId))
return new MethodCallResult(StatusBadNodeIdInvalid, null, null);
if (!TryParseNodeId(session, methodNodeId, out var methodId))
return new MethodCallResult(StatusBadNodeIdInvalid, null, null);
var inputVariants = new VariantCollection(
(inputs ?? Array.Empty<object>()).Select(v => new Variant(v)));
var callRequests = new CallMethodRequestCollection
{
new CallMethodRequest
{
ObjectId = objId,
MethodId = methodId,
InputArguments = inputVariants,
},
};
CallMethodResultCollection results;
await _gate.WaitAsync(cancellationToken).ConfigureAwait(false);
try
{
try
{
var resp = await session.CallAsync(
requestHeader: null,
methodsToCall: callRequests,
ct: cancellationToken).ConfigureAwait(false);
results = resp.Results;
}
catch
{
// Lost session / decode failure / cancellation. Surface a local
// BadCommunicationError so downstream clients can distinguish 'wire failed'
// from 'upstream rejected the call'.
return new MethodCallResult(StatusBadCommunicationError, null, null);
}
}
finally { _gate.Release(); }
if (results.Count == 0)
return new MethodCallResult(StatusBadInternalError, null, null);
var r = results[0];
// Unwrap output Variants into a CLR object[] so callers don't need an SDK dep.
object[]? outputs = null;
if (r.OutputArguments is { Count: > 0 })
{
outputs = new object[r.OutputArguments.Count];
for (var i = 0; i < r.OutputArguments.Count; i++)
outputs[i] = r.OutputArguments[i].Value!;
}
// Per-input-argument validation results. Most servers return an empty list on
// success; only populate the DTO field when the server actually surfaced per-arg
// codes so callers can use null as 'no per-argument feedback'.
uint[]? inputArgResults = null;
if (r.InputArgumentResults is { Count: > 0 })
{
inputArgResults = new uint[r.InputArgumentResults.Count];
for (var i = 0; i < r.InputArgumentResults.Count; i++)
inputArgResults[i] = r.InputArgumentResults[i].Code;
}
return new MethodCallResult(r.StatusCode.Code, outputs, inputArgResults);
}
private void OnEventNotification(
OpcUaAlarmSubscriptionHandle handle,
HashSet<string> sourceFilter,