mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-28 22:55:49 +08:00
Marc Schier
38c7356bc7
# Description xRegistry is the *abstract registry base model*: a registry-agnostic, content-addressed resource registry. It knows nothing about what a resource contains — a concrete registry supplies its own companion namespace and a fingerprinting strategy and reuses everything else. The PubSub Schema Registry in #4007 is the first specialization (its resources are schema documents), and #4093 (WoT Binding) carries a byte-identical copy of the same base NodeSet, so a shared canonical home is worth having. ## Packages | Package | Depends on | Contains | | --- | --- | --- | | `OPCFoundation.NetStandard.Opc.Ua.XRegistry` | `Opc.Ua.Core` | Abstract base companion model (compiled by the model source generator), `XRegistryWellKnown`, `IResourceContentIdProvider` | | `OPCFoundation.NetStandard.Opc.Ua.XRegistry.Client` | + `Opc.Ua.Client` | `XRegistryClient` (abstract) / `GenericXRegistryClient` (sealed), built on the generated ObjectType proxies | | `OPCFoundation.NetStandard.Opc.Ua.XRegistry.Server` | + `Opc.Ua.Server` | Fast-path / registration / federation node managers, `XRegistryServerOptions`, `IXRegistryResourceStore` | `Opc.Ua.XRegistry` deliberately depends on neither SDK, so a codec or a shared contracts assembly can reference the identity abstraction without pulling in the client or the server. ## The model is compiled, not loaded The companion model is compiled into the assemblies by the OPC UA model source generator. `Opc.Ua.XRegistry.NodeSet2.xml` is an `AdditionalFiles` generator input only — there is no `EmbeddedResource`, no runtime NodeSet parsing and no hand-written NodeId tables for anything the model declares. All three node managers load it the same way: ```csharp protected override NodeStateCollection LoadPredefinedNodes(ISystemContext context) { return new NodeStateCollection().AddOpcUaXRegistry(context); } ``` `XRegistryWellKnown` is reduced to the namespace URI plus the identifiers of the *instances* a registry materializes at runtime, which live above the model's own 63000-63999 range so they can never collide with it. ## What it does - **Content-derived identity** — `IResourceContentIdProvider` maps a document + format to a fingerprint and names the (canonicalization, hash) algorithm. Identity is derived from the bytes, not assigned by the server, so it is stable across registries — which is what makes de-duplication and federation work. - **Opaque-NodeId fast path** — a registered resource is reachable at an Opaque `NodeId` whose Identifier is the raw content-id bytes, so a consumer that received the id on the wire resolves the document in a single `Read`: no Browse, no fingerprint recomputation. The client reads it through the `ReadBytesAsync` session extension, so a document larger than `MaxByteStringLength` is fetched with range-based reads rather than failing. Optionally pre-publishes a seed resource so a fresh server can resolve one resource before any registration. - **The model's own lifecycle** — the registry root is a `RegistryType` instance serving `CreateGroup` / `GetOrCreateGroup`; each group serves `CreateResource` / `GetOrCreateResource`; and because `ResourceType : FileType`, the document *is* the file — content is streamed through the inherited `Open` / `Read` / `Write` / `Close`. `Close` fingerprints the accumulated bytes and publishes the Opaque fast-path node at runtime. Identical bytes reuse the existing node, whose lifetime is reference counted so it survives until the last resource resolving to those bytes is gone and is retired when a resource is re-written with different content. - **Optimistic concurrency** — `Delete(ExpectedEpoch)` on both resources and groups, and the same epoch check on label mutations, so a caller working from a stale read is rejected rather than clobbering a concurrent change. - **Labels** — `RegistryType`, `GroupType` and `ResourceType` each expose an `AttributesType` Object with `AddAttribute` / `RemoveAttribute`; labels are published as addressable `String` Properties. - **Federation** — a resource hosted by another registry is published as a real `ResourceType` instance whose `ExternalReference` (`ExpandedNodeId` + `ServerIndex` into the local `ServerArray`) and `ResourceUrl` carry the link and whose `Xid` carries the content-id. Because it is an ordinary `ResourceType`, a generic client drives a federated resource through exactly the same proxy as a local one. ## Extensibility A domain registry subtypes the base model — the PubSub Schema Registry declares `SchemaFileType : ResourceType` — and the generator mirrors that hierarchy across assemblies, so the proxy chain follows automatically (`SchemaFileTypeClient : ResourceTypeClient : FileTypeClient`). ```text abstract XRegistryClient ├── sealed GenericXRegistryClient // any registry namespace ├── SchemaRegistryClient (domain) └── WotRegistryClient (domain) ``` * A **domain client** derives from `XRegistryClient` and inherits the whole lifecycle. Helpers written as extension methods over a base proxy (such as `WriteDocumentAsync` on `ResourceTypeClient`) are callable on the domain proxy with no inheritance in the client layer. * A **generic client** still drives a domain registry, because a domain instance *is* an instance of the base type. This is covered by a test that defines a domain subclass over the base. ## State Document bytes live behind an injectable `IXRegistryResourceStore`. Because a resource is a `ResourceType`, which *is* a `FileType`, the store mirrors the file access model: reads and writes are **offset and length based**, so a document never has to be materialized as a whole and a ranged read touches only the bytes it needs. The document is transferred with the inherited `FileType` Methods, whose mode bits are honoured: a write that does not set `EraseExisting` starts from the stored bytes and replaces only the range it writes rather than truncating the rest. A handle is valid only on the resource and the session that opened it, and a session's handles are released when it closes. Two implementations ship: `InMemoryResourceStore` (the default, in-process) and `FileSystemResourceStore`, built on the `IFileSystem` abstraction so documents outlive the process and a shared volume can back a cluster. `XRegistryResourceStoreContractTests` is a reusable fixture that validates any implementation against the contract. ## Transport security Registry **writes always require a `SignAndEncrypt` secure channel** — a document and its content-derived identity are integrity-critical, so every mutation is rejected with `BadSecurityModeInsufficient` on a channel that is only signed or unprotected. This is not configurable. Reads are allowed on any secure channel by default; `RequireEncryptionForReads` extends the requirement to them when the documents themselves are confidential. An in-process call carries no channel and is always allowed. ## Hardening The lifecycle Methods are remotely callable, so every unbounded dimension is bounded via `XRegistryServerOptions`; exceeding a bound fails the call rather than the server: | Option | Default | Enforced on | Status code | | --- | --- | --- | --- | | `MaxConcurrentUploads` | 64 | `CreateResource`, `Open` | `BadTooManyOperations` | | `MaxResourceBytes` | 16 MiB | `Write` | `BadRequestTooLarge` | | `MaxRegisteredResources` | 4096 | `CreateResource` | `BadTooManyOperations` | ## A source generator bug fixed along the way Building on the compiled model surfaced a defect in shared generator infrastructure. `NodeSetToModelDesign.CreateDecoder` decoded values with an empty `EncodeableFactory`, so a NodeSet2's method `InputArguments` / `OutputArguments` — encoded as a list of `Argument` ExtensionObjects — never decoded, while `HasArguments` was still set. **Every** NodeSet2-sourced model in the stack was silently generating argument-less `MethodState`s and ObjectType proxies. ModelDesign-sourced models (the core stack) were unaffected, which is why this went unnoticed. Fixed in `b87726af` with a regression test that fails without it. Two defects in the xRegistry NodeSet itself were fixed at the same time: `BrowseName="1:InputArguments"` → ns-0 `InputArguments` (published NodeSets never namespace-qualify these), and the `CreateResource` / `GetOrCreateResource` **output** `VersionId` renamed to `AssignedVersionId`, which collided with the input of the same name and produced a duplicate C# parameter. ## Other fixes applied while extracting - `XRegistryRegistrationNodeManager` uses `System.Threading.Lock` instead of an `object`-typed sync root, per the repository locking rules. - Dropped the `InternalsVisibleTo` entries granting internals to `Opc.Ua.PubSub.Server.Tests`. That project only consumes public `XRegistryWellKnown` API. - The `UA.slnx` edit in #4007 accidentally **replaced** the `tests/Opc.Ua.Redundancy.Kubernetes.Tests` entry instead of adding a line, silently dropping that project from the solution. The entry is preserved here and the change is purely additive. ## Tests `tests/Opc.Ua.XRegistry.Tests` (168) covers the group and resource lifecycles, the `FileType` transfer, delete and epoch conflicts, labels, federation, both resource stores, the fast path, transport security and the extensibility contract — positive and negative paths. Passing on `net10.0` and `net48`. Patch line coverage is **98.5%**. Also adds `tests/Directory.Build.props` / `.targets`: the .NET 10 SDK prunes `Microsoft.Extensions.Logging.Abstractions` out of the test output, and coverlet's Mono.Cecil resolver only searches the output directory, so it silently fails to instrument every module that references `ILogger` and reports 0% coverage for them. These force the package back into the restore graph and copy its implementation next to the test binary. ## Documentation New [`docs/XRegistry.md`](docs/XRegistry.md), linked from the documentation index.
OPC UA .NET Standard Stack
🆕 This is version 2.0 of the OPC UA .NET Standard Stack (current
master).Looking for the supported 1.x release? It lives on the
master378branch (last release:1.5.378). All new feature work happens here onmaster;master378continues to receive security and critical-bug fixes for the 1.x line.
The official OPC Foundation reference implementation of OPC UA for .NET — a certified, cross-platform stack with client, server, PubSub, GDS, complex types, and source-generated tooling. Used in production across industrial control, manufacturing, energy, and IoT systems.
📦 What it is
- A full-stack OPC UA implementation — Core / Client / Server / PubSub / GDS / LDS / Complex Types / Device Integration libraries built on .NET, with UA-TCP and HTTPS transports.
- Cross-platform — runs on .NET 10, .NET 9, .NET 8 (LTS), .NET Framework 4.8, and .NET Standard 2.1; ships Native-AOT-friendly assemblies.
- Certified for compliance — the reference server has been certified through an OPC Foundation Certification Test Lab and is continuously verified against the latest Compliance Test Tool (CTT).
- Companion-spec coverage — Part 9 (Alarms & Conditions), Part 11 (Historical Access), Part 13 (Aggregates), Part 16 (State Machines), Part 17 (Alias Names), Part 18 (Role Management), Part 20 (File Transfer), Part 100 (Device Integration), OPC 10100-1 (WoT Connectivity).
- Modern developer surface — first-class
Microsoft.Extensions.DependencyInjectionhosting (services.AddOpcUa()), fluent server + client builders, source-generated NodeManagers and DataTypes, and an MCP server so LLMs / Copilot can drive an OPC UA client.
For the full feature breakdown see OPC UA Profiles and Facets and the What's New in 2.0 tour.
🚀 Getting started
You need the .NET 10 SDK to build the repo. From the repository root:
dotnet restore UA.slnx
dotnet build UA.slnx
For the supported target frameworks and platform notes see
the Developer Guide. The official NuGet packages
are published to nuget.org under the OPCFoundation.NetStandard
prefix — the meta package
OPCFoundation.NetStandard.Opc.Ua
pulls in everything, or pick the split
OPCFoundation.NetStandard.Opc.Ua.Core / .Client / .Server /
.Bindings.Https packages directly. Preview builds for every successful
master build are available in the
Azure DevOps opcua-preview feed.
Sample applications
Each sample has its own README.md with build and run instructions.
Reference applications
- Console Reference Server — the certified reference server (with Quickstarts, CTT, and Mono configs). Also ships as a Docker container.
- Console Reference Client — cross-platform reference client demonstrating sessions, subscriptions, browsing, and method calls.
- Console LDS Server — a standalone
Local Discovery Server built on
Opc.Ua.Lds.Server.
PubSub samples
- Console Reference PubSub Client —
one executable with
publisher,subscriber, andexternal(external-server adapter) modes across the supported transport profiles.
Minimal / Device-Integration samples
- Minimal Calc Server — minimal server built on the source-generated NodeManager pipeline (Calc model).
- Minimal Boiler Server — minimal Boiler-model server with the fluent state-machine builder; Native-AOT publishable.
- Pump Device Integration Server —
minimal Device Integration (Part 100) server using
Opc.Ua.Di.Server's fluent builder.
More sample projects are maintained in the companion OPC UA .NET Samples repository.
Developer tools
- OPC UA MCP Server — installable .NET tool and container that exposes OPC UA client operations as MCP tools for LLMs and Copilot.
🔧 Migrating from 1.5.378 to 2.0
The 2.0 release introduces breaking API changes, and comes with a full prescriptive migration guide that links to per-area documentation covering telemetry, packages, source generation, types, encoders, node states, identity, certificates, configuration, sessions / subscriptions, alarms / model change, and TimeProvider.
Most of the mechanical migration work is automated:
OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzerNuGet — install it in your project to get analyzer warnings (UA0001–UA0022)- one-click code fixes for the patterns in the guide. Setup steps are in the package's NugetREADME.md.
- Migration agent skill — the
opcua-v20-migrationskill walks Copilot / Claude / any coding agent through installing the NuGet, runningdotnet format analyzersto apply auto-fixes, and handling the small residual manual patterns. The skill knows which sub-doc to load for each symptom so it stays context-efficient.
If you are still on 1.x and not ready to upgrade, stay on the
master378
branch — it continues to receive security and critical-bug fixes.
🤝 Contributing and license
Community contributions are welcome. Fork the repository, make your changes on a branch, and open a pull request; see CONTRIBUTING.md for the contribution workflow.
Contributors must sign the OPC Foundation Contributor License Agreement (CLA). The CLA "I AGREE" gate is presented automatically on your first PR.
The project is licensed under the OPC Foundation MIT License. Report security vulnerabilities via the process documented in SECURITY.md.
📚 Further reading
- Documentation index — every per-feature doc with a one-line description.
- What's New in 2.0 — narrative tour of the 1.5.378 → 2.0 changes grouped by theme and layer.
- OPC UA Profiles and Facets — facets / transports / security policies the stack implements.
- Migration Guide — prescriptive
per-version migration reference (links to
docs/migrate/2.0.x/). - OPC UA Online Reference — the official OPC 10000 series specification index.
- OPC UA .NET Samples — companion repository with more sample applications.
- Preview NuGet feed — prerelease builds from Azure DevOps.