UA-.NETStandard/docs/NodeIdAssignment.md

NodeId Assignment

Every node a server creates at runtime needs a NodeId. This document describes the mechanisms the stack uses to produce one: the factory contract, the identifier formats, how type declarations differ from instances, what the source generator emits, and what each NodeManager base class does.

Contents

• The contract
• DefaultNodeIdFactory
  • The canonical path
  • Modes
  • Collision detection
  • Which namespace
  • When an existing NodeId is kept
  • Nodes with no derivable path
• Types and instances
• What the source generator emits
• NodeManager behaviour
  • CustomNodeManager2
  • AsyncCustomNodeManager
  • FluentNodeManagerBase and the fluent builders
• Configuring the factory
• Who forces a fresh identifier

The contract

INodeIdFactory (Opc.Ua.Types/State/ISystemContext.cs) has one member:

NodeId New(ISystemContext context, NodeState node);

It reaches node code through ISystemContext.NodeIdFactory. A NodeManager publishes itself as that factory in its constructor (SystemContext.NodeIdFactory = this), so any node-authoring code holding the manager's SystemContext mints identifiers through the manager. This points at the NodeManager, not at its factory, so that a subclass overriding New is still the one node-level code reaches — which is why AsyncCustomNodeManager and CustomNodeManager2 do it once for every manager that derives from them, and a subclass never repeats it.

IRebasableNodeIdFactory (Opc.Ua.Server/NodeManager/IRebasableNodeIdFactory.cs) extends that with what a NodeManager needs and a bare INodeIdFactory cannot express: which namespace to mint into, which identifier style to mint, and an identifier for a node that does not exist yet.

NodeIdAssignmentMode Mode { get; }
ushort DefaultNamespaceIndex { get; }
IRebasableNodeIdFactory WithDefaultNamespaceIndex(ushort defaultNamespaceIndex);
IRebasableNodeIdFactory WithMode(NodeIdAssignmentMode mode);
NodeId NextCounterNodeId();
NodeId CreateChildNodeId(NodeId parentNodeId, QualifiedName browseName, ushort namespaceIndex, NamespaceTable namespaceUris);

The factory needs the NodeManager's namespace index, but the server adds that namespace only after constructing the manager. A factory registered through dependency injection is therefore created too early to receive the final index as constructor configuration.

For that reason, IRebasableNodeIdFactory is a contract rather than constructor configuration. Implementations are immutable, and the With… methods return views with different namespaces. One registered factory can serve managers that own different namespaces.

AsyncCustomNodeManager.NodeIdFactory uses this interface. A caller can decorate DefaultNodeIdFactory with a custom rule—for example, claim one subtree and delegate other nodes—instead of overriding New on the NodeManager and scattering the rule across it.

The property is nullable; a null factory disables automatic assignment. Code that requires a factory should call ISystemContext.RequireNodeIdFactory() for a diagnosable failure when none is configured. Node copying suppresses new identifier assignment with assignInstanceNodeIds: false; the original context and its factory remain available.

New may be called more than once for the same node — AssignNodeIds walks a subtree on every create pass — so an implementation has to be idempotent or the address space ends up with orphaned references.

DefaultNodeIdFactory

Opc.Ua.Server/NodeManager/DefaultNodeIdFactory.cs is the stack's implementation. It is immutable and safe to share.

The canonical path

Every mode except Counter derives from one canonical browse path: a length-prefixed encoding of the parent identifier and the child browse name.

v1:10:l:6:s=Root:10:l:6:Group1

Each segment carries its own length, so no combination of parent and browse name can produce the same path as a different combination. The classic {parentIdentifier}_{browseName} convention could: A_B plus C and A plus B_C both gave A_B_C. The parent segment keeps the parent's identifier type prefix (s=, i=, g=, b=), so a string parent "42" never reads as a numeric parent 42.

Segments are qualified by namespace:

Prefix	Meaning
l:	in the namespace being minted into
z:	in namespace 0
u:<uri>:	in another namespace, named by URI
x:<index>:	in another namespace that has no URI registered

The URI form makes an identifier independent of namespace-table ordering. The index form is a fallback for an unregistered namespace; it is deliberately distinct so identifiers minted before the namespace was registered cannot collide with the ones minted after.

The path is temporary. Except in String mode, the factory hashes it and discards it without creating a string. It builds the path in a stack buffer, or rents a buffer from ArrayPool<char> when needed. One routine measures and writes the path, so the reserved segment length always matches the written length.

Modes

NodeIdAssignmentMode selects how the path becomes an identifier.

Mode	Identifier	Stable across restarts	Collides when browse paths repeat
None	none — raises BadConfigurationError	—	—
Numeric	first 32 bits of the path's SHA-256	yes	yes, plus hash collisions
String	the canonical path verbatim	yes	yes
Guid	first 128 bits of the path's SHA-256	yes	yes
Opaque	first 128 bits of the path's SHA-256	yes	yes
Counter	sequential number	no	no

Numeric is the default: it is the most compact form on the wire and the most readable in a client UI.

String is the only mode that cannot collide for distinct browse paths, because it keeps the canonical path whole and two different paths are never the same text. The others project the path through SHA-256 and inherit that hash's collision probability — negligible for Guid and Opaque at 128 bits, but real for Numeric at 32.

Collision detection

A 32 bit identifier is a birthday problem: distinct browse paths are expected to land on one after roughly 2^16 of them. Left alone that is silent damage, because the predefined-node index takes the last writer — one node would replace the other.

So the factory records what it mints and raises BadConfigurationError when a second browse path lands on an identifier that a different one already has. The error names the path that was refused and the modes that do not have the problem.

Minting the same path twice is normal — AssignNodeIds walks a subtree on every create pass — so the record keeps a witness of the path alongside the identifier, and only a differing witness is a collision. The witness is the tail of the same hash, so two paths would have to agree on the identifier and on a further 64 bits before a real collision could pass as a re-mint.

Three consequences worth knowing:

• The factory keeps a record per namespace because identifiers in different namespaces cannot collide. Views derived from one factory share that record. Therefore, two NodeManagers that rebase the registered factory onto the same namespace are checked against each other and draw sequential identifiers from one counter. NodeManagers that construct separate factories instead of using the registered factory do not share records.
• The factory never prunes the record. An identifier handed to a client remains reserved after its node is removed, so re-minting it for another path is a collision. The record costs roughly 50 bytes per distinct path.
• It covers identifiers the factory mints, not identifiers a caller assigns. String identifiers cannot collide, so the factory keeps no record for them. Counter identifiers cannot collide with each other, but they use the same numeric namespace as hashes. When checking is enabled, the factory reserves each counter value to prevent another mode from minting it. If a counter value is already taken, the factory advances to the next value because the counter can move.

Counter is for nodes whose browse paths repeat over time — per-session diagnostics objects, inference jobs, rediscovered assets. Its counter starts above 0x40000000, separating its initial allocations from lower numeric identifiers. This is not a reserved range or a guarantee against authored-ID collisions. Authored numeric identifiers at or above 0x40000000 in the same namespace can collide with Counter identifiers; the factory does not detect these collisions. (The predefined-node index takes the last writer, so such a collision silently replaces the type rather than failing.)

Which namespace

Every identifier is minted into the factory's DefaultNamespaceIndex — the NodeManager's own namespace. Neither the parent's namespace nor the browse name's is consulted:

• a parent can belong to a companion-specification model whose NodeIds are fixed by its NodeSet (DeviceSet in the DI namespace, for instance). A server may not mint identifiers there.
• a browse name only names the type that declared the child.

A NodeManager whose instance namespace is not its first one rebases the factory with WithDefaultNamespaceIndex.

When an existing NodeId is kept

New keeps a node's current NodeId when the caller can plausibly have chosen it, and mints a fresh one otherwise. Two cases qualify:

• the identifier is already in this NodeManager's namespace, which no other model's NodeIds ever are;
• the node stands on its own rather than hanging off a parent. NodeState.Create hands a root its NodeId before running the assignment pass, so a caller naming a node explicitly arrives this way.

Everything else is re-minted, because it reached New through AssignNodeIds walking a subtree copied from a type declaration and still carrying that declaration's identifiers. See Who forces a fresh identifier.

Nodes with no derivable path

A node with no browse name, or one hanging off a transient parent that has no NodeId (an event instance and its fields), has no stable path. Those fall back to the counter whatever mode is selected, so a NodeManager never has to special-case them.

Types and instances

An information model ships type declarations: PumpType and every child below it, each with a NodeId fixed by the NodeSet. When a server creates an instance, NodeState.CreateInstance copies that subtree — and the copy carries the declaration's NodeIds.

NodeState.AssignNodeIds rebases the copy onto per-instance identifiers: it walks the subtree calling INodeIdFactory.New on each node, collects an old-to-new mapping table, and hands it to UpdateReferenceTargets so references inside the subtree follow.

If New returns the declaration NodeId unchanged, every instance of the type aliases onto the type's own nodes. The failure is silent: the predefined-node index replaces rather than rejects, so the ObjectType becomes an instance node. Guarding against that is the reason DefaultNodeIdFactory re-mints anything it did not mint itself, and the reason the generator's helpers check the declaration constant before rebasing.

Type nodes themselves are never passed through AssignNodeIds; they are loaded from the NodeSet and registered as predefined nodes.

What the source generator emits

For each child of a generated type the generator emits helpers that materialise it, each with its own NodeId policy.

Create{Type} / CreateInstanceOf{Type}Type(parent, browseName) — builds an instance and rebases the subtree through the context's factory.

Add{Child}(context, nodeId = default):

Argument	Behaviour
nodeId non-null	the child takes that NodeId, then its descendants are rebased around it
nodeId null	rebased through the factory, but only if the child still carries its declaration constant

CreateOrReplace{Child}(context, replacement, assignInstanceNodeIds):

Argument	Behaviour
assignInstanceNodeIds false	the child keeps whatever NodeId it has
assignInstanceNodeIds true	rebased, but only if the NodeId is null or still the declaration constant

The declaration-constant guard (nodeState.NodeId.Equals(TypeNodeIdConstant)) is the generator's compile-time way of asking "is this still a declaration identifier?". It also means a caller who assigned an identifier explicitly keeps it.

NodeManager behaviour

CustomNodeManager2

Unchanged, for backwards compatibility:

public virtual NodeId New(ISystemContext context, NodeState node)
{
    return node.NodeId;
}

It mints nothing. A node keeps whatever NodeId it already has, and a node with none keeps NodeId.Null. Subclasses that need identifiers override New themselves. Existing servers built on this base see no change in behaviour.

AsyncCustomNodeManager

New delegates to the NodeIdFactory property and does nothing else. The manager holds no counter of its own. A subclass selects its identifier style by assigning that factory in its constructor rather than by overriding New:

NodeIdFactory = NodeIdFactory.WithMode(NodeIdAssignmentMode.Counter);

WithMode and WithDefaultNamespaceIndex both return a copy, so a factory shared through dependency injection is never mutated. Assigning a factory that names no namespace (a bare new DefaultNodeIdFactory(mode)) adopts the manager's own namespace; one that names a namespace is left alone.

The default is NodeIdAssignmentMode.Numeric, so a manager that overrides nothing gets compact deterministic browse-path identifiers, checked for collisions.

When AddNodes receives no RequestedNewNodeId, the preferred identifier may already belong to a live node, for example after that node's BrowseName was changed. The manager then asks the configured factory for a fresh counter identifier, skipping identifiers already registered or reserved by another in-flight AddNodes request. It reserves the choice before asynchronous registration and releases the reservation if registration fails or is canceled. The existing node and its references are not replaced. Clients must use the addedNodeId returned by the service rather than assuming the preferred browse-path identifier was available.

A client-supplied RequestedNewNodeId is never substituted: an occupied or reserved identifier returns BadNodeIdExists. Duplicate BrowseNames and invalid namespaces are still rejected. Factory errors remain visible; a counter factory that repeats an occupied identifier reports BadConfigurationError instead of causing an unbounded retry.

FluentNodeManagerBase and the fluent builders

FluentNodeManagerBase derives from AsyncCustomNodeManager and inherits its behaviour. The fluent builders — AddObject, WithProperty, CreateInstance, and the alarm and state-machine helpers — mint through FluentNodeRegistration.AssignNodeId, which routes to the owning manager's New. They no longer each spell out a {parentIdentifier}_{browseName} concatenation.

Inside a Configure delegate the mode can be selected for everything created after it:

builder.WithNodeIdAssignment(NodeIdAssignmentMode.Guid);

Every builder mints through the owning NodeManager's New, so there is no second identifier shape to fall back to. WithNodeIdAssignment needs the factory itself, which only an AsyncCustomNodeManager carries, so on any other NodeManager it raises BadConfigurationError rather than quietly doing nothing.

Configuring the factory

Through dependency injection, once for the whole server:

builder.AddNodeIdFactory(NodeIdAssignmentMode.Guid);

DependencyInjectionStandardServer resolves the registered IRebasableNodeIdFactory, StandardServer threads it into ServerInternalData, and every AsyncCustomNodeManager picks it up through INodeIdFactoryProvider, rebased onto its own namespace.

The registration is keyed on the interface, so an implementation of your own — typically a decorator holding a DefaultNodeIdFactory — can be registered in its place:

builder.AddNodeIdFactory(new ReservingNodeIdFactory(new DefaultNodeIdFactory()));

Who forces a fresh identifier

For a redundant server set, use UseReplicaNodeIdentity rather than configuring independent default factories. It reserves the same shared namespace indexes before node-manager construction, binds the assignment policy across replicas, and preserves IDs during hydration. Counter/no-path allocation is not independently reproducible; only the configured active/passive writer may register those shared allocations. Ordinary single-server defaults are unchanged.

Two things can be true of a node arriving at New with a NodeId already set: the caller chose that identifier, or it is a type declaration's identifier that NodeState.CreateInstance copied onto an instance. The factory cannot tell them apart, so the rule is positional rather than inferred:

• a node that stands on its own keeps its NodeId;
• a node hanging off a parent is re-minted, because it reached New through AssignNodeIds walking a copied subtree.

A root that must also shed a declaration identifier says so by naming the identifier it wants. ISystemContext.CreateInstance is the short way to do that: it builds the subtree and then rebases it through AssignInstanceNodeId, which forces a fresh identifier by clearing the NodeId and asking again. That is the same path the generated CreateInstanceOf{Type} helpers take, so hand-written and generated authoring agree.

Reaching for NodeState.Create(..., NodeId.Null, ..., assignNodeIds: true) on a generated state object is the trap: the object is born carrying its own type's NodeId, Create only replaces that when handed an identifier, and the result is an instance sitting on the type's node.