UA-.NETStandard/docs

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).

UA Core stack related

• 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.
• 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).
• 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).
• Source generated NodeManagers - Emit an AsyncCustomNodeManager from a model design XML and wire callbacks via the fluent INodeManagerBuilder API; supports NativeAOT single-file servers (samples: MinimalBoilerServer, PumpDeviceIntegrationServer). Covers engineering units, property initialisation, alarms, simulation timers, instance creation, NAMUR-style supervision, multi-model composition, and the fluent state-machine builder on top of any FiniteStateMachineState subclass. Cross-assembly model references are tracked via the ModelDependencyAttribute. Companion-spec packaging — model + server + client library trios — is covered end-to-end by the Device Integration developer guide using the Opc.Ua.Di / Opc.Ua.Di.Server / Opc.Ua.Di.Client trio as the worked example.
• 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.
• 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.
• 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 reads, annotations, and 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.
• 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 application related

• 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)

• GDS Developer Guide — Application registration, certificate management (pull & push models), roles and authorization, provider implementation, end-to-end examples, and a per-requirement OPC UA Part 12 conformance matrix that links every implemented ServerConfiguration/PushManagement, TrustList, certificate-alarm, KeyCredentialService and AuthorizationService requirement to its source and automated tests (with applicable profiles/conformance units and honest complete/partial/optional/unsupported marks).
• KeyCredentialService — Credential issuance for non-OPC UA services (MQTT, REST), IKeyCredentialRequestStore provider guide, ISecretStore integration.
• AuthorizationService — OAuth2-style access token issuance, IAccessTokenProvider implementation guide.
• Role-Based Security — Part 18 roles and claim-based identity-mapping rules.
• Identity Providers — server and client identity-provider architecture.
• Dependency Injection — dependency injection hosting and identity registration extensions.