Skip to content

NodeManagement.md

Latest commit

 

History

History
229 lines (189 loc) · 12 KB

NodeManagement.md

File metadata and controls

229 lines (189 loc) · 12 KB
Raw

NodeManagement service set

The OPC UA NodeManagement service set (OPC 10000-4 §5.8) gives clients the ability to manipulate the server's address space at runtime:

Service Description
AddNodes Create a new node beneath an existing parent (Object, Variable, ...).
DeleteNodes Remove a node and, optionally, all references that target it.
AddReferences Add a reference between two existing nodes.
DeleteReferences Remove a reference between two existing nodes.

The SDK ships full request validation, per-item dispatch, audit-event emission, and per-NodeManager opt-in. NodeManagers do not need to override the four StandardServer service methods themselves.

Contents

Architecture

  1. The client request lands on StandardServer.AddNodesAsync / DeleteNodesAsync / AddReferencesAsync / DeleteReferencesAsync.

  2. Each service override validates the request and forwards the per-item collection to the matching IMasterNodeManager.AddNodesAsync etc. dispatcher.

  3. For each item, MasterNodeManager selects the owning NodeManager:

    • AddNodes: the requested NodeId namespace, or the BrowseName namespace if the server assigns the NodeId; select the first opted-in NodeManager registered for that namespace.
    • DeleteNodes: the node's owning NodeManager.
    • Reference changes: the source node's owning NodeManager.

    It validates the matching PermissionType, then asks the optional INodeManagementAsyncNodeManager interface to perform the operation. AddNodes requires AddNode in the target namespace's default policy and AddReference on the parent. The server evaluates each Node permission together with the Node's applicable AccessRestrictions.

  4. The aggregated per-item results are wrapped in the matching response envelope and the audit event (AuditAddNodesEvent, AuditDeleteNodesEvent, AuditAddReferencesEvent, AuditDeleteReferencesEvent) is emitted with an aggregated status.

NodeManagers that do not implement INodeManagementAsyncNodeManager — or have not opted in — return BadUserAccessDenied, which is the status defined for "server does not allow this operation". This keeps the default behavior of every existing NodeManager unchanged.

Opting in: INodeManagementAsyncNodeManager

public interface INodeManagementAsyncNodeManager
{
    // Sub-class returns true to opt in. Default is false.
    bool AllowNodeManagement { get; }

    ValueTask<(ServiceResult result, NodeId addedNodeId)> AddNodeAsync(
        OperationContext context,
        AddNodesItem item,
        CancellationToken cancellationToken = default);

    ValueTask<ServiceResult> DeleteNodeAsync(
        OperationContext context,
        DeleteNodesItem item,
        CancellationToken cancellationToken = default);

    ValueTask<ServiceResult> AddReferenceAsync(
        OperationContext context,
        AddReferencesItem item,
        CancellationToken cancellationToken = default);

    ValueTask<ServiceResult> DeleteReferenceAsync(
        OperationContext context,
        DeleteReferencesItem item,
        CancellationToken cancellationToken = default);
}

AsyncCustomNodeManager already implements INodeManagementAsyncNodeManager with default behavior that handles every common case. Sub-classes opt in by overriding a single property:

public sealed class MyNodeManager : AsyncCustomNodeManager
{
    public MyNodeManager(IServerInternal server, ApplicationConfiguration config, ILogger logger)
        : base(server, config, logger, "http://example.org/MyNodes/")
    {
    }

    public override bool AllowNodeManagement => true;
}

That is the only change needed for a NodeManager to start accepting AddNodes / DeleteNodes / AddReferences / DeleteReferences requests.

The reference server's ReferenceNodeManager opts in this way; you can use it as the working example.

The Part 10 Program host deliberately restricts this opt-in. Only explicitly enabled registered Program types can be added; deletion must target a permitted Halted invocation, not its children or containing folder. NodeManagement cannot bypass the Program provider, capacity reservations or lifetime policy. The type's Create method is the primary client creation path.

Dispatch and routing rules

  • AddNodes: routed by the namespace of RequestedNewNodeId when the caller supplies one; otherwise it uses BrowseName.NamespaceIndex. The dispatcher selects the first opted-in NodeManager registered for that namespace. Parent ownership is checked separately for validation and attachment; it does not determine the target manager. There is no fallback to an opted-in manager in another namespace.
  • DeleteNodes: routed to the owning NodeManager of the target node.
  • AddReferences / DeleteReferences: routed to the source node's owning NodeManager. Target-side validation and inverse mutation occur only when the target is explicitly local: targetServerUri is empty, and the ExpandedNodeId has neither a server index nor namespace URI. When that target lives in a different opted-in NodeManager, the dispatcher resolves the actual source and target NodeClass, checks both local endpoints before mutation, and mirrors the complementary edge. If the inverse mutation fails or is cancelled, the source mutation is compensated with an independent bounded cleanup token before the original failure is returned or rethrown.

Request handling on AsyncCustomNodeManager

The default implementation honors the following request fields:

Field Behavior
RequestedNewNodeId Used as the new node's NodeId when valid; otherwise BadNodeIdRejected. When null, a fresh NodeId is allocated via INodeIdFactory.New; if the override returns a null NodeId (for example, because it derives identifiers from a parent that is not yet attached) the SDK falls back to the base allocator so AddNodes always yields a usable identifier. BadNodeIdExists if it collides with an existing node.
BrowseName Must be non-null. BadBrowseNameDuplicated when a sibling under the same parent already uses the same browse name — both local children and previously-added cross-NodeManager children attached to the same parent by this NodeManager are checked.
ParentNodeId Used to attach the new child to the parent. Cross-NodeManager parents are supported — the forward parent → child edge is added via the master so the parent's NodeManager records it, and the inverse child → parent edge is added on the new node.
ReferenceTypeId Must be a HierarchicalReferences subtype.
NodeAttributes Optional VariableAttributes or ObjectAttributes are applied to the new node. Supported fields include DisplayName, Description, DataType, ValueRank, AccessLevel, UserAccessLevel, Historizing, MinimumSamplingInterval, Value, and EventNotifier.
DeleteTargetReferences When true, DeleteNodes also removes references on other NodeManagers that target the deleted node.
DeleteBidirectional When true on DeleteReferences, the inverse edge is also deleted only for an explicitly local target. Remote targets remain source-side operations.

If AddNodes fails after registration recovered previously detached monitored items, rollback detaches those items again before removing the node. They retain their deleted-node status and remain recoverable when a later AddNodes succeeds with the same NodeId.

Error codes returned

Service Status Reason
AddNodes BadBrowseNameInvalid BrowseName is null.
AddNodes BadParentNodeIdInvalid ParentNodeId is null or unknown.
AddNodes BadReferenceTypeIdInvalid ReferenceTypeId is null or unknown.
AddNodes BadReferenceNotAllowed ReferenceTypeId is not a hierarchical reference.
AddNodes BadNodeIdRejected The requested NodeId cannot be resolved locally, the target namespace has no registered NodeManager, or a supplied RequestedNewNodeId has no opted-in manager in its namespace. The selected manager can also reject an invalid requested ID.
AddNodes BadNodeIdExists RequestedNewNodeId already exists.
AddNodes BadBrowseNameDuplicated A sibling beneath the same local parent already uses the browse name.
AddNodes BadNodeClassInvalid Only Object and Variable are supported by the default implementation.
AddNodes BadNodeAttributesInvalid The supplied attributes extension object does not match the node class.
AddNodes BadUserAccessDenied When no NodeId is requested, the BrowseName namespace has registered managers but none has opted in; or the Session lacks the required AddNode or parent AddReference permission.
DeleteNodes / AddReferences / DeleteReferences BadUserAccessDenied The owning NodeManager has not opted in to NodeManagement or the Session lacks the required DeleteNode, AddReference, or RemoveReference permission.
AddNodes / DeleteNodes / AddReferences / DeleteReferences BadSecurityModeInsufficient An applicable namespace, parent, source, or local target AccessRestrictions policy requires a stronger SecureChannel.
DeleteNodes BadNodeIdInvalid / BadNodeIdUnknown The node to delete is null or unknown.
AddReferences BadSourceNodeIdInvalid Source is null or unknown to this NodeManager.
AddReferences BadTargetNodeIdInvalid Target is null.
AddReferences BadDuplicateReferenceNotAllowed The exact reference (type + direction + target) already exists on the source.
DeleteReferences BadNoMatch No reference with the exact triple (type + direction + target) was found on the source.

Audit events

Every NodeManagement service emits its corresponding audit event:

  • AuditAddNodesEventType
  • AuditDeleteNodesEventType
  • AuditAddReferencesEventType
  • AuditDeleteReferencesEventType

The audit Status is the first bad per-item status, or Good when every item succeeded. Audit events are emitted from both the success and failure paths so an early ServiceResultException (request-level validation) still appears in the audit log.

Client-side example

The standard Session / ManagedSession AddNodes / DeleteNodes / AddReferences / DeleteReferences APIs work unchanged against any server whose NodeManager has opted in. See OPC 10000-4 §5.8 for the service contract.

Custom behavior

After opting in, override the matching INodeManagementAsyncNodeManager method to customize a NodeManager. For example, you can enforce a custom NodeId scheme, persist a new node, or veto specific node classes. The following example restricts additions to Object nodes:

public override async ValueTask<(ServiceResult result, NodeId addedNodeId)> AddNodeAsync(
    OperationContext context,
    AddNodesItem item,
    CancellationToken cancellationToken = default)
{
    if (item.NodeClass != NodeClass.Object)
    {
        return (new ServiceResult(StatusCodes.BadNodeClassInvalid), NodeId.Null);
    }
    return await base.AddNodeAsync(context, item, cancellationToken).ConfigureAwait(false);
}

See also