Files
UA-.NETStandard/docs
romanett 105508bcbd Mint runtime NodeIds through a single DefaultNodeIdFactory (#4433)
# Description

Nodes created at runtime now get their NodeIds from a single
`DefaultNodeIdFactory` rather than from a `New` override per
NodeManager.
The factory derives a deterministic identifier from a canonical,
length-prefixed browse path, which is injective where the classic
`{parent}_{child}` concatenation was not — `A_B` + `C` and `A` + `B_C`
both produced `A_B_C` — and it also records the parent's identifier type
and qualifies cross-namespace segments by URI, so identifiers no longer
shift with namespace-table ordering.

A NodeManager selects its style declaratively instead of writing
assignment code:

```csharp
NodeIdFactory = NodeIdFactory.WithMode(NodeIdAssignmentMode.Counter);
```

`NodeIdAssignmentMode` offers `String` (the canonical path verbatim, the
default), `Numeric` / `Guid` / `Opaque` (that path through SHA-256),
`Counter` (sequential, for nodes whose browse paths repeat — per-session
diagnostics, inference jobs, rediscovered assets) and `None`. The
counter
starts above `0x40000000`, out of reach of any authored model, so a
long-running server cannot walk a runtime instance onto a type node.

`New` overrides are gone from every NodeManager the stack ships except
two whose identifiers are a domain scheme rather than an assignment
policy: `FileSystemNodeManager`, whose NodeIds encode the file path they
resolve back to, and `RoboticsNodeManager`, whose build coordinator
reserves identifiers across managers with ownership tracking.

**Namespace rule.** Every identifier is minted into 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), and
a
browse name only names the type that declared the child. NodeManagers
whose instance namespace is not their first one rebase with
`WithDefaultNamespaceIndex`.

**Types vs instances.** An authored NodeId on a node that stands on its
own is kept. A node hanging off a parent is re-minted, because it
reached
the factory through `AssignNodeIds` walking a subtree copied from a type
declaration. Keeping those would alias every instance onto the type's
own
nodes, and the predefined-node index takes the last writer, so the type
would quietly become an instance rather than the clash being reported.

New `ISystemContext.CreateInstance(...)` builds an instance of a
generated
type and rebases its subtree through `AssignInstanceNodeId` — the path
the
generated `CreateInstanceOf<Type>` helpers already took. The AI
NodeManager was the one place calling `NodeState.Create` directly, so
its
roots kept the NodeId their state object is born with (the type's own);
it now uses the shared path.

## Breaking changes

- `IAsyncNodeManager` extends `INodeIdFactory` and gains `AddNode` and
  `AddRootNotifier`. This lets the fluent surface mint and register
  through the interface instead of type-testing for
  `AsyncCustomNodeManager` and silently falling back to a concatenated
  identifier when the test failed — that fallback was itself a source of
  divergent NodeIds.
- `AsyncNodeManagerAdapter` delegates `New` to the wrapped NodeManager,
so
**`CustomNodeManager2` behaves exactly as before**: it mints nothing and
  a node keeps whatever NodeId it already has. Servers built on it are
  unaffected.

## Notes for reviewers

- `docs/NodeIdAssignment.md` is new and describes the whole mechanism:
the
  factory contract, identifier formats, type declarations vs instances,
  the generated helpers and their parameters, per-NodeManager behaviour,
  and an inventory of every member involved.
- The three commits are independently revertible.
- Two pieces that look redundant are deliberately kept, with the
reasoning
  recorded in the doc: `assignInstanceNodeIds` (it *suppresses* minting,
  where the rebase rule *forces* it) and the generator's
  `NodeId.Equals(TypeNodeIdConstant)` guard (it distinguishes a
  caller-assigned NodeId from a declaration's).
- Fluent builder tests previously passed only because of the removed
  fallback; they now run against a real `DefaultNodeIdFactory` through a
  shared `FluentTestNodeManager` helper.

## Related Issues

_No tracking issue yet._

## Checklist

- [ ] I have signed the
[CLA](https://opcfoundation.org/license/cla/ContributorLicenseAgreementv1.0.pdf)
and read the
[CONTRIBUTING](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/CONTRIBUTING.md)
doc.
- [x] I have added tests that prove my fix is effective or that my
feature works and increased code coverage.
- [x] I have added all necessary documentation.
- [x] I have verified that my changes do not introduce (new) build or
analyzer warnings.
- [ ] I ran **all** tests locally using the **UA.slnx** solution against
at least .net **framework** and .net **10**, and all passed.
- [ ] I fixed **all** failing and flaky tests in the CI pipelines and
**all** CodeQL warnings.
- [ ] I have addressed **all** PR feedback received.

> Test runs were on **net10.0 only** — .NET Framework was not exercised
> locally. Suites run green on an idle machine: Server 4950/4955, GDS
> 1116/1170, WotCon 1225/1225, Vision 484/485, DI 424/424, AI 174/174,
> ISA95 136/136, Positioning 69/69, RobotIntent 22/22. One unrelated
> pre-existing failure remains in `Opc.Ua.Types.Tests`
> (`EveryEmbeddedExampleMatchesItsRecordedHash`) — a WoT fixture checked
> out with CRLF, fixed by
> `git add --renormalize tests/Opc.Ua.Types.Tests/Wot/Assets`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-08 14:37:19 +00:00
..

OPC UA .NET Standard stack documentation

Here is a list of available documentation for different topics:

New contributor? Start with the Developer Guide — prerequisites, building, testing, coding standards, and how-to recipes (including how to add logging).

  • Sample applications - Platform-independent reference, PubSub, minimal API, companion-model, robotics, Vision, AI, ISA-95, and OpenUSD demos included in this repository.
  • OPC UA Profiles and Facets - Overview of supported OPC UA profiles, facets, security policies, and transport protocols.
  • Transport Profiles - Developer guide for the wire transports: opc.tcp / HTTPS (binary + JSON + REST) / WSS (binary + JSON), including server hosting and client connect examples.
  • REST Binding (OpenAPI Mapping) - OPC UA Part 6 §G.3 OpenAPI mapping: ASP.NET Core MVC controllers for every spec service, Compact / Verbose encoding negotiation, four pluggable auth modes (Anonymous / Bearer JWT / HTTP Basic / Mutual TLS), and the symmetric IWebApiClient.
  • What's New in 2.0 - Developer-facing tour of the 1.5.378 → 2.0 changes, grouped by theme and layer, with links to deeper feature docs.
  • Migration Guide - How to migrate from a previous version.
  • Sessions, Reconnection, and Subscription Engines - Architectural overview of Session, ManagedSession, SessionReconnectHandler, and the classic / V2 subscription engines, including guidance on which to use.
  • About .NET platform support, NuGet packages and versioning.
  • About continuous integration — which pipeline runs what, how to start a validation build on a pull request with /azp run, and the coverage gates a change has to satisfy.
  • How X.509 Certificates are used in the certificate stores.
  • CertificateManager - Centralized certificate lifecycle management, server-side push certificate rotation, and the OPC UA Part 12 PushManagement transaction model (ApplyChanges/CancelChanges, staged TrustList/Certificate updates, DeleteCertificate, pending-key persistence).
  • Crypto provider - Replacing the stack's cryptography with another library, a remote service or hardware (TPM, HSM, PKCS#11, cloud key service), keeping private keys inside the device, selecting providers per purpose and security policy, and auditing the use of uncertified cryptography.
  • Using the Reverse Connect for the UA-TCP and WSS transports.
  • Support for the TransferSubscriptions service set.
  • Diagnostics — logging, telemetry, server audit events, server diagnostics nodes, and packet capture.
  • Performance Benchmarks — BenchmarkDotNet methodology, the 2.0 (master) vs 1.5.378 (master378) comparison, root-cause analysis of the encoder/decoder/session regressions and their real-world impact, the subscription-notification (pooled encodeable) micro-benchmarks, server session scalability (the 500-session capability, sizing and bottlenecks), and planned future work.
  • Server Session Scalability — why a single node tops out at ~2000 concurrent sessions, the establishment vs steady-state boundaries (socket backlog, the BadTcpInternalError retry-storm amplifier, the O(N²) diagnostics rescan, CreateSession crypto-under-lock, the RSA CPU wall, and the held-Publish worker-accounting coupling) with code references, and a prioritized admission-control / rate-limiting roadmap for moving beyond it.
  • Rate Limiting and Admission Control — the server's deterministic, configurable connection- and session-establishment limiters (on by default, System.Threading.RateLimiting-based, DI-pluggable), the BadServerTooBusy signalling, the diagnostics-independent server retry-after carriers (ResponseHeader.additionalHeader, HTTP Retry-After, UA-TCP ERR, and load-based Server.ServiceLevel), and the client's server-signal-aware adaptive reconnect backoff (IReconnectPolicy.TryGetNextDelay).
  • Support for WellKnownRoles & RoleBasedUserManagement.
  • Pluggable Identity Providers — interfaces (IClientIdentityProvider, IUserTokenAuthenticator, IAccessTokenProvider, ITokenIssuer, IIdentityClaims) plus the OPC 10000-6 §6.5.2.2 IssuerEndpointUrl JSON parser for OAuth2 / OIDC / Entra / JWT flows.
  • Support for ECC Certificates.
  • Working with ComplexTypes - Custom structures and enumerations.
  • Client-based NodeSet Export - Export server address space to NodeSet2 XML.
  • Source generated [DataTypes] - How to annotate POCO classes and let the source generator generate the IEncodeable implementation.
  • Runtime Schema Generation - Produce XSD, OPC Binary (BSD) and JSON Schema (Part 6 Annex C, compact + verbose) for generated encodeable types and dynamically added complex types via the injectable ISchemaProvider; schemas are built as object models in code (trimmable, NativeAOT compatible).
  • NodeManagers - Overview of the server node-manager architecture, built-in managers (master, core, diagnostics/configuration), CoreNodeManager vs CustomNodeManager2 guidance, registration and runtime lifecycle rules, namespace metadata and historical-access reconciliation, and source-generated AsyncCustomNodeManager authoring with the fluent INodeManagerBuilder API. Includes NativeAOT single-file server guidance and samples such as MinimalBoilerServer and PumpDeviceIntegrationServer.
  • Runtime NodeSets - Load one or more NodeSet2 XML documents into the server address space at startup without source generation. Covers file and stream sources, dependency ordering, parent-child browse-path resolution, fluent Configure callbacks, default namespace inference, and the default complex-type loading path. Use when the XML content changes independently of the server binary or for rapid prototyping.
  • WoT / NodeSet conversion - WotNodeSetConverter readable mapping, preservation projections, and the WoT-to-NodeSet default/failure table.
  • WoT Connectivity - OPC 10100-1 asset connectivity, the WoT Connectivity 1.1 registry/client, dependency-closure materialization, and runtime NodeSet projection.
  • WoT protocol bindings - The bindings that ship today (planner/executor architecture, bundled and separate packages, operation coverage, target mapping, lazy channels, generation lifetime) and the contributor guide for adding your own, with a complete memory binding, registration, diagnostics, tests, packaging, TFM, trimming, and NativeAOT guidance.
  • WoT aggregation sample - Two flat OPC UA sources aggregated into a runtime-loaded DI/Machinery/Pumps Pump model, including commands, Refresh, monitoring, replacement, troubleshooting, and NativeAOT publishing.
  • Device Integration (DI) developer guide - End-to-end documentation for the Opc.Ua.Di* library trio: fluent IDeviceBuilder, device sub-type extensions (AddSoftware, AddBlock, AddConfigurableObject, AddLifetimeIndication, WithSupportInfo), hosting integration (AddOpcUaDi / ConfigureDevicesFor), lock service, software-update package store, and client helpers (DiLockClient, DiTopologyClient, SoftwareUpdateClient). Includes a section enumerating supported OPC 10000-100 features against the spec.
  • OpenUSD — bridge an OPC UA address space to an OpenUSD stage, in two parts. Part 1 — bindings: the generic domain-agnostic OpenUsdConnector (discovers Server/OpenUSD/Representations, subscribes, composes, verifies stage/asset digests, replays history), the Variant-based IUsdSink with UsdFileSink / MockUsdSink, the fluent/DI AddOpenUsdConnector extensions + OpenUsdConnectorFactory / OpenUsdConnectorOptions, server-side UsdAssetDelivery, and the optional --view viewport. Part 2 — scene materialization: materializes a composed USD stage inside the address space so the prim tree is the node hierarchy — the Opc.Ua.OpenUsd.Scene companion and scene-document APIs, Opc.Ua.OpenUsd.Scene.Conversion .usda reader/writer and §6.2 UsdValueTypeMap (USD roles as DataTypes subtyping their built-in), and Opc.Ua.OpenUsd.Server.Scene materialization/export APIs with unknown-type fallbacks, Mode-A live attributes, portable Cesium georeference dual-authoring, discovery and Part 1 binding-target resolution. Both parts ship in the Opc.Ua.OpenUsd and Opc.Ua.OpenUsd.Server packages, and both companion models are currently drafts.
  • Robotics developer guide — the Opc.Ua.Robotics / Opc.Ua.Robotics.Server / Opc.Ua.Robotics.Client trio for OPC 40010 Robotics 1.02 over OPC 40001-1 IA and OPC 10000-100 DI: source-generated models, AddRobotics / AddRoboticsModel / ConfigureRobotics(For) hosting, IRoboticsModelProvider / IRoboticsConfigurator / IRoboticsBuildContext, validated fluent topology builders (AddMotionDeviceSystemAsync down to axes, power trains, motors, gears, drives, safety states, and task controls), semantic references, ArrayOf<T> snapshot contracts, and RoboticsClient discovery. It also covers Robot Intent, the draft task-level motion verbs OPC 40010 leaves undefined, including the MCP surface for LLM agents.
  • Vision developer guide — the Opc.Ua.Vision / Opc.Ua.Vision.Server / Opc.Ua.Vision.Client / Opc.Ua.Vision.OpenUsd package family for the draft OPC UA — Vision companion specification: source-generated Vision model, AddVision / ConfigureVision hosting with IVisionMediaProvider / IVisionInferenceProvider / IVisionFeedbackSink, the two perception paths behind one contract (OnServer deterministic detector vs EdgeOffServer agent submissions), fluent topology builders for frames, sensors, calibrations, media endpoints and inference pipelines, VisionClient discovery + VisionFrameGraph §5.12 pose composition + VisionResultReader streaming detections + VisionFeedbackClient for off-server VLM agents, the §6.4 media-gating states, the NoRenderingBackend degrade path, facet derivation, and the composed vision MCP profile with the BinPickingCell / BinPickingClient example.
  • AI Model Management developer guide — the Opc.Ua.AI / Opc.Ua.AI.Inference / Opc.Ua.AI.Server / Opc.Ua.AI.Client package family for the draft OPC UA — AI Model Management and Inference companion specification over xRegistry: source-generated catalogues, datasets, deployments, inference endpoints and learning jobs, the IInferenceBackend contract with Microsoft.Extensions.AI IChatClient and OpenAI-compatible REST backends, AINodeManagerFactory hosting via AddNodeManager<AINodeManagerFactory>, Invoke routing, standard file-transfer artefact streaming, credential resolvers that keep secret material out of the address space, and the ModelManagementServer / ModelManagementClient example.
  • Relative Spatial Location and Global Positioning — source-generated OPC 10000-210 RSL and OPC 10000-211 GPOS models, standalone/composed server hosting, provider contracts, high-level clients, frame-chain resolution, WGS84/ENU conversion, and ground-control-point fitting.
  • Generators (generating sets) — the draft Generators companion specification realised end to end by GeneratorServer: a datasheet-driven simulation in which load fraction is the only independent variable, DI + Machinery integration, and one independent OpenUSD twin per configured set. Includes SiteCompositionServer, a supervisory server that owns no devices and composes the pump and generator servers into a single scene through cross-server components.
  • ISA-95 developer guide - End-to-end documentation for the Opc.Ua.ISA95* library trio: the OPC-10030 Common Model and OPC-10031-4 Job Control V1/V2, the two transparently-documented normative NodeSet repairs, AddIsa95Server/AddIsa95Client hosting, the typed common-model builder, the shared Job Control state engine and its Uncertain/Annex-B ReturnStatus result model, the provider-backed GeoSpatialLocationType seam and planned Part 210/211 RSL/GPOS integration, and a conformance matrix distinguishing static NodeSet structure from runtime-tested behavior.
  • Alias Names - Full server + client support for the OPC UA Part 17 alias-name model (AliasNameType, AliasNameCategoryType, FindAlias, FindAliasVerbose, AddAliasesToCategory, DeleteAliasesFromCategory, LastChange).
  • Alarms and Conditions - Full server + client support for OPC UA Part 9. Server-side state types for latched/silenced/out-of-service alarms, alarm groups and suppression engine, alarm rate metrics. Client-side AlarmClient, typed alarm event records, fluent AlarmEventFilterBuilder, IAsyncEnumerable alarm streaming via AlarmStreamExtensions.
  • Historical Access (Part 11) - Server provider model (IHistorianProvider family) and InMemoryHistorianProvider, plus the client HistoryClient (session.Historian()) for raw/modified/at-time/processed/event reads, modification audit metadata, annotations, and data/event/structured updates.
  • Aggregates (Part 13) - All 37 standard Part 13 v1.05.07 aggregate functions over historical data: server AggregateManager / calculators, native push-down vs framework fallback, AnnotationCount via the annotation provider, AggregateConfiguration defaults, and the client ReadProcessedAsync helper.
  • Subscriptions and Monitored Items Service Set - V2 subscription engine API. Covers ISubscriptionManager for long-lived callback-based subscriptions, the declarative+imperative SetTriggering API with N:M support and automatic replay on recreate/reconnect, and IStreamingSubscription (IAsyncEnumerable-based) for state-machine waits and short-lived monitoring (ManagedSession.DefaultStreaming, TakeUntilAsync / WithTimeoutAsync helpers).
  • Unbounded Monitored Items - V2 logical-subscription wrapper that transparently splits monitored items across multiple server-side partitions when the per-subscription cap is exceeded (IPartitionedSubscription, MonitoredItemOptions.Affinity, reactive Bad_TooManyMonitoredItems fallback, secondary-partition idle-delete).
  • State Machines - Generic, extensible Part 16 state-machine API. Client side: streaming + read helpers on the source-generated *TypeClient proxies (GetCurrentFiniteStateAsync, ObserveFiniteTransitionsAsync, WaitForStateAsync). Server side: unified fluent StateMachineBuilder with two complementary modes — definition (Create(...) + AddState / AddTransition / OnCause for ad-hoc machines via FluentFiniteStateMachineState) and lifecycle (For(...) / INodeBuilder.AsStateMachine() + OnEnterState / WithCause / WithTimedTransition to attach behavior to stack-shipped or generator-emitted FSMs). Vendor state machines inherit both ends of the API automatically.
  • Model Change Tracking - Client-side address-space change tracking with per-node INodeCache invalidation; server-side ModelChangeAggregator and auto-emitted GeneralModelChangeEvent from CustomNodeManager.CreateNode/DeleteNode.
  • NodeManagement Service Set - Server-side AddNodes / DeleteNodes / AddReferences / DeleteReferences, including the INodeManagementAsyncNodeManager opt-in pattern and per-NodeManager AllowNodeManagement gate.
  • High Availability and OPC UA Redundancy - OPC 10000-4 §6.6 mapping for server, client, and network redundancy; RedundancySupport, ServiceLevel, manual failover, transparent/non-transparent ManagedSession modes, HotAndMirrored/Transparent state mirroring, distributed address-space/session/subscription stores with CRDT (eventual) or Raft (strong) consistency, shared certificate/trust-list stores, snapshot+delta hydration, and the optional GetEndpoints load-direction seam.
    • Kubernetes High Availability Deployment - Consolidated Kubernetes guide for the Opc.Ua.Redundancy.Kubernetes package: Lease leader election, EndpointSlice peer discovery, ServiceLevel-driven readiness, StatefulSet/Deployment and Service manifests, RBAC, probes, time sync, secrets, and GDS/NTRS registration.
    • Redundant Sample Integration Tests - Process-level integration tests that launch the RedundantServer / RedundantClient / RedundantPubSub sample apps and assert on their failover, reconnect, and data-loss-visibility behavior; short-haul variants run on every PR, long-haul soak variants run via dedicated manual/scheduled GitHub Actions and Azure DevOps jobs (SAMPLE_HA_DURATION_MINUTES).
  • Dependency Injection - The unified services.AddOpcUa() / IOpcUaBuilder surface for hosting OPC UA components in Microsoft.Extensions.DependencyInjection / the .NET Generic Host (servers as IHostedService, options via Action<T> or IConfiguration, AOT-friendly).
  • AuthorizationService - Modern Part 12 StartRequestToken / FinishRequestToken, ITokenIssuer, and GDS token issuance.
  • Fuzz testing - SharpFuzz + afl-fuzz + libFuzzer integration. Three areas: Encoders (Binary/JSON/XML decoders, built-in type readers, parser entry points), Certificates (X509CRL, X509 extension parsers, PEMReader, Pkcs10CertificationRequest, ASN.1 helpers), and Network (UA-SC framing via Opc.Ua.Core.Diagnostics + internal TcpMessageParsers seam on Opc.Ua.Core). The fuzz-tester custom agent drives the whole toolchain autonomously: it detects OS-available engines, runs them in parallel, fixes novel findings per repo guidelines, adds the failing input as a regression asset, and pushes one commit per fix until the user says stop.
  • KeyCredentialService - Pull, Push, and experimental bridge guidance for Part 12 KeyCredential flows.
  • xRegistry (abstract registry base model) - Generic registry with structural Xid identity and a separate IResourceContentIdProvider Opaque-NodeId document fast path, true dirty-Close registration, federated resource proxies, native events, and resource-exhaustion bounds. Shipped as Opc.Ua.XRegistry, Opc.Ua.XRegistry.Client, and Opc.Ua.XRegistry.Server.
  • PubSub (Part 14) - Publisher/subscriber support library: architecture, fluent builder, transports (UDP / MQTT 3.1.1 + 5.0 / Kafka / Ethernet Layer 2), encodings (UADP / JSON), security, and server-side address space.
    • PubSub High Availability - Distributed Part 14 §9.1.6 active/standby publishers and subscribers with Cold/Warm/Hot modes, leader election or fenced leases, shared runtime checkpoints, protected SKS key storage, consistency guidance, and Kubernetes deployment notes.
    • Migration sub-doc - 1.5.378 → 2.0 breaking API, transport, JSON, and field-encoding changes, plus the compatibility matrix.
    • Ethernet transport - Layer 2 PubSub (opc.eth://, EtherType 0xB62C, 802.1Q VLAN) with native AF_PACKET / BPF, SharpPcap, and in-memory backends.
    • Kafka transport - Apache Kafka broker transport (kafka://, kafkas://) for UADP and JSON PubSub profiles with SASL/TLS and NativeAOT support on net10.0.
    • PubSub Transcoding - In-process subscriber-to-publisher transcoding with UADP/JSON cross-encoding, field/value/metadata transforms, identifier remap, receive hooks, egress, and managed UADP re-securing.
    • External server adapter - Bind PubSub publishers, subscribers, and Action responders to an external OPC UA server through ManagedSession.
    • Dependency Injection extensions - AddPubSub, AddPubSubPublisher, AddPubSubSubscriber, AddPubSubSecurityKeyServiceClient/Server, AddPubSubAddressSpace.
    • Profiles - Datagram-v2, SKS pull / push, AES-128/256-CTR security facets.
    • PubSub Diagnostics - packet capture, dissection and replay of UDP / MQTT PubSub traffic, including decryption of encrypted UADP messages.
  • Reference Client documentation for configuration of the console reference client using parameters.
  • Reference Server documentation for running against CTT.
  • ConsoleReferencePubSubClient documentation for the PubSub reference sample (publisher / subscriber / external-server adapter modes).
  • Provisioning Mode for secure certificate provisioning and initial server configuration.
  • Using the Container support of the Reference Server in Visual Studio 2026 and for local testing.

Starting with version 1.5.375.XX the Windows Forms reference client & reference server were moved to the OPC UA .NET Standard Samples repository.

Global Discovery Server (GDS)