UA-.NETStandard/docs/XRegistry.md

xRegistry — abstract registry base model

The xRegistry libraries implement the generic, registry-agnostic abstract registry base model for OPC UA. They provide the substrate a concrete registry builds on: structural xRegistry identity, an Opaque-NodeId content fast path that resolves a document in a single Read, a model-driven registration lifecycle with auto-bootstrap, and a federation model for resources hosted by another registry, and optional native OPC UA events for registry mutations.

The libraries are deliberately domain-neutral: they know 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 and WoT Connectivity registry are concrete specializations: PubSub resources are schema documents, while WoT resources are Thing Description / Thing Model documents.

Contents

• Packages
• Core concepts
  • Structural identity and content lookup
  • Opaque-NodeId fast path
  • Registration lifecycle and auto-bootstrap
  • File open modes
  • Resource storage
  • Transport security
  • Federation
  • Labels
  • Native xRegistry events
• Server-side usage
  • Async lifecycle
  • Resource-exhaustion bounds
• Client-side usage
  • Extending for a domain registry
• Well-known identifiers
• Related documentation

Packages

Package	Depends on	Contains
OPCFoundation.NetStandard.Opc.Ua.XRegistry	Opc.Ua.Core	The source-generated base companion model (types, NodeIds, NodeStates and *TypeClient proxies), XRegistryWellKnown, IResourceContentIdProvider
OPCFoundation.NetStandard.Opc.Ua.XRegistry.Client	Opc.Ua.XRegistry, Opc.Ua.Client	XRegistryClient — fast-path resolve and lifecycle registration
OPCFoundation.NetStandard.Opc.Ua.XRegistry.Server	Opc.Ua.XRegistry, Opc.Ua.Server	The three node managers and XRegistryServerOptions

Opc.Ua.XRegistry has no dependency on either SDK, so a codec or a shared contracts assembly can reference the identity abstraction without pulling in the client or the server.

Core concepts

Structural identity and content lookup

Xid is always the stable structural path relative to the registry root: / for the registry, /groups/{group} for a group, /groups/{group}/resources/{resource} for a Resource, and that Resource path plus /versions/{version} for a materialized Version file. Replacing document bytes never changes Xid, ResourceId, VersionId, AddressSpace placement, or event Subject.

Every registry may separately supply an IResourceContentIdProvider that maps a document plus its format to an opaque content key:

public interface IResourceContentIdProvider
{
    ByteString ComputeContentId(string format, ReadOnlySpan<byte> document);

    string? GetAlgorithm(string format);
}

GetAlgorithm names the (canonicalization, hash) pair used for a format and returns null for formats the registry does not handle. This key is an implementation fast path, not entity identity. It is tracked per Version and reference-counted, so equal bytes in different Versions share one Opaque node while replacing or deleting one Version releases only that Version's reference.

Opaque-NodeId fast path

A registered resource is reachable at an Opaque NodeId in the registry namespace whose Identifier is the raw content-id bytes. A consumer that received the id on the wire therefore needs no Browse and no fingerprint recomputation — one Read of that node's Value returns the document:

var fastPathNodeId = new NodeId(contentId, registryNamespaceIndex);

// Use the ranged read extension rather than a plain ReadValue: a document larger than the
// session's MaxByteStringLength is fetched in slices instead of failing.
ByteString document = await session.ReadBytesAsync(fastPathNodeId, 0, ct).ConfigureAwait(false);

XRegistryFastPathNodeManager serves these nodes and can optionally pre-publish a seed resource so a freshly started server resolves at least one content-addressed resource before any registration has happened.

Registration lifecycle and auto-bootstrap

The registry serves the model's own Methods. A registry root (RegistryType) is materialized from the compiled model, and groups and resource versions are created beneath it at runtime:

1. RegistryType.CreateGroup(GroupId) returns the new group's NodeId; GetOrCreateGroup is the idempotent form and also reports Created.
2. GroupType.CreateResource(ResourceId, VersionId, RequestFileOpen) creates a resource version and returns (ResourceNodeId, AssignedVersionId, FileHandle). An empty VersionId lets the server assign the next one; GetOrCreateResource additionally reports Created. A non-empty VersionId is preserved exactly and must be 1-128 characters: the first character is an ASCII letter, digit, or _, and subsequent characters may additionally use -, ., ~, :, or @. Lookup is case-sensitive, while sibling Version ids must be unique without regard to case. A Resource may have one contentless pending Version while an upload is open. Allocating it never evicts committed content; retention is applied atomically when the upload closes, and a close that cannot preserve active/default/desired Versions is rejected. An empty Version id reuses that pending Version after an abort or restart; requesting a different explicit Version while it remains pending is rejected. Existing manifests retain compatibility with longer, already-normalized legacy Version ids.
3. Because ResourceType is a FileType, the document is streamed with the standard Write/Read file Methods against the handle — there is no registry-specific transfer.
4. Close compares the staged bytes with the committed bytes captured immediately before Open. Only a successful Close with an accepted, byte-different write commits the document, increments that Version's Epoch, updates its ModifiedAt, and publishes or updates the reference-counted Opaque fast-path node. Clean, aborted, rejected, empty, and byte-identical closes perform no store rewrite and change no metadata.
5. Delete(ExpectedEpoch) on a resource or a group removes it. The epoch is an optimistic-concurrency check: a caller holding a stale epoch is rejected with Bad_InvalidState rather than deleting a newer version. Passing 0 disables the check, which is how a caller deliberately forces the operation without having read the entity first.

Registration commits Resource and Version structural identity before the create Method returns. When RequestFileOpen is true, a later dirty Close is a separate mutation; it updates the Version but does not repeat the create operation or its events.

File open modes

The handle returned by CreateResource / GetOrCreateResource is opened with EraseExisting semantics — a newly created version starts empty. GetOrCreateResource returns a write handle for an existing version too, so a caller can replace its document in the same call; a caller that only wanted to look the version up closes that handle without writing, which releases it and leaves the resource untouched.

Reopening a version with the inherited Open uses the standard FileType mode bits (OPC 10000-5 §C: Read = 1, Write = 2, EraseExisting = 4, Append = 8):

Mode	Behaviour
Read	Read the committed document.
Write | EraseExisting	Replace the document wholesale.
Write | Append	Start from the stored bytes with the cursor at the end.
Write	Start from the stored bytes with the cursor at 0 — writes replace only the range they cover and do not truncate the remainder.

A mode requesting neither read nor write, both together, or EraseExisting/Append without Write is rejected with Bad_InvalidArgument. Each Version permits one writer; a second write open fails with Bad_NotWritable, and a read open while that writer is active fails with Bad_NotReadable. A handle is valid only on the resource and the session that opened it, and a session's handles are released when it closes. EraseExisting stages an empty buffer but does not mutate the committed file until a dirty Close.

Resource storage

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.

var options = new XRegistryServerOptions
{
    // Keeps the documents in the server process (the default).
    ResourceStore = new InMemoryResourceStore()
};

// Or back them with files so they outlive the process and a shared volume can serve a cluster.
options.ResourceStore = new FileSystemResourceStore("/var/lib/xregistry");

FileSystemResourceStore is built on the IFileSystem abstraction, so a deployment can substitute its own — and a test can run it against a VirtualFileSystem without touching disk:

using var fileSystem = new VirtualFileSystem();
using var store = new FileSystemResourceStore("resources", fileSystem);

The server pieces are also wired for dependency injection, with direct construction still supported:

services
    .AddXRegistryContentIdProvider<MyContentIdProvider>()
    .AddXRegistryFileSystemResourceStore("/var/lib/xregistry")
    .AddXRegistryServer(options => options.RequireEncryptionForReads = true);

XRegistryServerOptions is sealed. The three node managers are deliberately not sealed: subclassing them is the server-side extension seam a domain registry uses to serve its own companion model on top of the base one, mirroring how a domain client derives from XRegistryClient.

Implementing a store

Use the in-box InMemoryResourceStore or FileSystemResourceStore unless the application requires another persistence backend. A custom IXRegistryResourceStore must implement four operations:

Operation	Contract
ReadAsync	Read from the requested offset, returning fewer bytes at the end. Return a null ByteString for an unknown key, and an empty non-null value for an empty read of an existing resource.
WriteAsync	Replace the addressed byte range without truncating the remainder. Extend the document and zero-fill any gap when writing beyond its end.
GetLengthAsync	Return the byte length, or -1 for an unknown key.
DeleteAsync	Return whether a resource was deleted; an absent key returns false.

For implementation examples, see InMemoryResourceStore and FileSystemResourceStore. Concurrent writes must preserve non-overlapping updates. A concurrent dictionary alone does not make a read-modify-write sequence atomic.

Two rules make a store substitutable:

• Error reporting. Argument faults throw — ArgumentException for a null or empty key, ArgumentOutOfRangeException for a negative offset or count. Everything a caller is expected to handle is a return value instead: a null ByteString, a -1 length, a false delete. Genuine infrastructure failures (an unreachable share, a permission fault) should throw a ServiceResultException with an appropriate status code, which the node manager surfaces as the Method's result rather than faulting the server.
• Concurrency. Implementations must be safe for concurrent calls.

The contract is exercised by XRegistryResourceStoreContractTests; deriving a fixture from it is the quickest way to validate a new implementation.

Opc.Ua.WotCon.Server is a worked example: WotBlobResourceStore implements this interface over the {root}/{digest}.bin layout the WoT registry has always written, so a domain registry can adopt the shared byte layer without an on-disk migration. See WoT Connectivity — keeping the document bytes in a shared store.

Transport security

Registry writes always require a SignAndEncrypt secure channel. A document and its content lookup are integrity-critical, so CreateGroup, GetOrCreateGroup, CreateResource, GetOrCreateResource, Delete, AddAttribute, RemoveAttribute, opening a file for writing, Write and Close are all rejected with BadSecurityModeInsufficient on a channel that is merely signed or unprotected. This is not configurable.

Reads are permitted on any secure channel by default, because a registry is usually a public catalogue. Set RequireEncryptionForReads when the documents themselves are confidential:

var options = new XRegistryServerOptions
{
    RequireEncryptionForReads = true
};

An in-process call carries no channel at all — the server's own bootstrap, or a test — and is always allowed.

Federation

XRegistryFederationNodeManager publishes a proxy for a resource hosted by another registry. The proxy is itself a ResourceType instance, so a generic xRegistry client drives it through exactly the same generated proxy as a locally hosted resource. It carries an ExternalReference — an ExpandedNodeId whose ServerIndex names the remote server through the local ServerArray, and whose NamespaceUri and Identifier locate the remote resource node — and/or a plain ResourceUrl. ResourceId, VersionId, and Xid retain the remote structural xRegistry identity. A content digest may still be used by the remote NodeId or a local cache, but it never replaces Xid.

Labels

RegistryType, GroupType and each Version ResourceType expose a Labels Object of type AttributesType. Version label Methods use that Version's Epoch, increment it, update Version ModifiedAt, and emit VersionUpdated when events are enabled. Resource Meta is distinct: MetaEpoch, MetaLabels, MetaCreatedAt, and MetaModifiedAt are synchronized across the Resource's Version files. Meta label Methods use MetaEpoch, update only Resource Meta, and emit ResourceUpdated. Adding or removing a Version advances Resource Meta; modifying Version bytes or Version labels does not.

Native xRegistry events

The xRegistry 0.5.0 model includes XRegistryEventType and the 19 concrete registry, model, capabilities, group, resource and version event types. The model source generator emits the typed *EventState, *EventTypeRecord and EventFilters.Build(...) surfaces directly from the NodeSet. Applications subscribe with the standard OPC UA event APIs; there is no separate xRegistry subscription protocol and no CloudEvents document is serialized into a Variable or Method.

Generic event publication is disabled by default. Enable it only with a stable absolute source URL and the concrete registry's canonical collection/document attribute names:

var options = new XRegistryServerOptions
{
    EventsEnabled = true,
    EventSourceUrl = "https://registry.example.com",
    GroupsAttributeName = "groups",
    ResourcesAttributeName = "resources",
    ResourceDocumentAttributeName = "schema"
};

Incomplete enabled configuration throws during node-manager construction. SourceUrl is the configured registry URL, independently of the OPC UA endpoint and event SourceNode; Subject is the changed entity xid. The generic stack leaves CorrelationId absent because its Method responses do not return a corresponding correlation value.

SourceNode identifies the native AddressSpace source rather than the registry URL. A version event uses that version's ResourceType file. A resource event uses the committed default-version file, including the new default after a switch; consequently ResourceCreated and the first VersionCreated share the first/default file. Registry, model, modelsource, and capabilities events always use the registry root. A deleted event retains the removed source's former SourceNode and SourceName, but is reported through the nearest surviving notifier so subscriptions continue to receive it.

One successful Method mutation, dirty file Close, or post-startup projection reconciliation is coalesced into one logical event batch. Events in a batch share one Time; duplicate type-and-subject changes are merged; Changed names are ordinally sorted and de-duplicated; and deleted/created/updated precedence is applied per subject. Initial projection is a silent baseline, and failed, stale, idempotent, clean-close and no-op interactions emit nothing. Recursive deletion reports version leaves before resources, groups and their surviving parent update.

The registration manager registers its registry root with the node manager's root-notifier API. Consequently a MonitoredItem on ObjectIds.Server receives descendant group, Resource, and Version events, while monitoring the registry or a narrower notifier remains supported.

Enabling XREG-Events commits the implementation to every event marked MUST by the xRegistry event specification for each supported mutation mechanism. RegistryCreated, RegistryDeleted, and descendant events caused by deleting an entire registry are recommendations because registry creation/deletion is outside the core mutation API. Descendant events produced by recursive group or resource deletion are required and are never suppressed.

The stack publishes native OPC UA events only. If an application separately serializes one of these events as CloudEvents JSON, it maps the opaque BaseEventType.EventId bytes to the CloudEvents id using standard Base64 encoding.

For projected domain registries, existing IXRegistryProjectionStrategy implementations and the original six-parameter XRegistryProjectionContext constructor remain supported when events are disabled. Event-enabled strategies additionally implement IXRegistryProjectionGenerationProvider, which captures projection data and event metadata from one immutable generation. IXRegistryVersionedProjectionStrategy is additive and lets a domain honor explicit/server-assigned Version ids, materialize stable per-Version NodeIds, and separate Version labels from Resource Meta without breaking existing strategies.

Server-side usage

Configure the node managers through XRegistryServerOptions and add them to the server's node manager list. The options object carries the registry namespace, the content-id provider, the optional seed and federation resources, and the resource-exhaustion bounds:

var options = new XRegistryServerOptions
{
    RegistryNamespaceUri = "http://example.org/UA/MyRegistry/",
    ContentIdProvider = new MyContentIdProvider(),

    // Optional: pre-publish one resource on the fast path at start-up.
    PublishSeedResource = true,
    SeedDocument = seedBytes,
    SeedFormat = "avro",
};

var registration = new XRegistryRegistrationNodeManager(server, configuration, options);
var fastPath = new XRegistryFastPathNodeManager(server, configuration, options);
var federation = new XRegistryFederationNodeManager(server, configuration, options);

All three managers derive from AsyncCustomNodeManager. Register them through the server's AddNodeManager(IAsyncNodeManagerFactory) overload; the factory's CreateAsync returns an IAsyncNodeManager. Direct construction and AddXRegistryServer options/provider registrations are supported. Startup, node publication/removal, session cleanup, and event delivery are awaited rather than routed through a synchronous node-manager wrapper.

The registry's companion model is compiled into the assembly by the OPC UA model source generator: Opc.Ua.XRegistry.NodeSet2.xml is a generator input (AdditionalFiles), so the ObjectTypes, Methods, Variables, NodeId constants, NodeState classes and typed ObjectType proxies are emitted at build time. No NodeSet2 XML is parsed at runtime — each node manager simply returns the generated model from LoadPredefinedNodesAsync:

protected override ValueTask<NodeStateCollection> LoadPredefinedNodesAsync(
    ISystemContext context,
    CancellationToken cancellationToken = default)
{
    cancellationToken.ThrowIfCancellationRequested();
    return new ValueTask<NodeStateCollection>(
        new NodeStateCollection().AddOpcUaXRegistry(context));
}

A concrete registry composes its own companion model on top of the base model in dependency order, declaring RequiredModel on the xRegistry namespace in its NodeSet.

Async lifecycle

Custom subclasses override the async lifecycle hooks and await their base implementations. Use AddPredefinedNodeAsync and DeleteNodeAsync for runtime graph mutations. In-memory lookups such as Find and FindPredefinedNode<T> are synchronous. Hosting and custom callbacks use the async interface without blocking on tasks.

Cancellation is observed before a registration mutation starts and during document reads. Once a dirty Close consumes its handle, or a deletion changes the graph, the manager finishes the commit/cleanup even if the caller subsequently cancels. Await DeleteAddressSpaceAsync before disposal to drain active operations and release handles without disposing the injected store. Failed or cancelled startup removes its partially indexed nodes and does not publish incomplete external references. Await successful startup before invoking registration Methods; a failed startup can be retried on the same manager. Deletion cleanup attempts every removed subtree and stored document before reporting callback or storage failures. Removals that could not complete are retried before an explicit deletion or during teardown, never midway through an unrelated file operation. Retiring resources reject new file handles and label mutations. See Async server support for the async base's hosting and notification contracts.

Note: the model occupies NodeIds 63000-63999 in the registry namespace. The instance identifiers in XRegistryWellKnown live above that range so a materialized instance can never collide with a model node.

Resource-exhaustion bounds

The registration Methods are remotely callable, so XRegistryServerOptions bounds every unbounded dimension. Exceeding a bound fails the call rather than the server:

Option	Default	Enforced on	Status code
MaxConcurrentUploads	64	CreateResource / file Open	BadTooManyOperations
MaxResourceBytes	16 MiB	file Write	BadRequestTooLarge
MaxRegisteredResources	4096	CreateResource	BadTooManyOperations

Client-side usage

The client layer is built entirely on the source-generated ObjectType proxies — no hand-rolled service calls. XRegistryClient is an abstract base carrying the xRegistry-level API; GenericXRegistryClient is the sealed implementation for callers that only need the base model, and a domain registry client derives from the same base:

abstract XRegistryClient
   ├── sealed GenericXRegistryClient   // any registry namespace
   ├── SchemaRegistryClient  (domain)
   └── WotRegistryClient     (domain)

Resolving a resource from an id received on the wire is a single call. It reads through ReadBytesAsync, so a document larger than the session's MaxByteStringLength is fetched with range-based reads rather than failing. It returns a null ByteString — check IsNull — when no fast-path node is registered, so the caller can fall back to a Browse or a registry-specific download:

var client = new GenericXRegistryClient(session, "http://example.org/UA/MyRegistry/", telemetry);

ByteString document = await client.ResolveResourceAsync(contentId, ct: ct).ConfigureAwait(false);
if (document.IsNull)
{
    // Not registered on this server — fall back.
}

Registering a document drives the model's own lifecycle: the group's CreateResource creates the version and opens it for writing, and the document is streamed through the FileType methods that ResourceType inherits.

ResourceRegistrationResult registered = await client.RegisterResourceAsync(
    groupNodeId,
    resourceId: "urn:my:resource",
    document: documentBytes,
    ct: ct).ConfigureAwait(false);

NodeId resourceNodeId = registered.ResourceNodeId;
string assignedVersionId = registered.AssignedVersionId;

Groups, idempotent registration and deletion are covered by the same convenience layer. Delete takes the node's ExpectedEpoch, so a caller working from a stale read is rejected rather than clobbering a concurrent change:

// The registry root sits at a well-known identifier in the registry namespace, so there is no
// need to Browse for it.
GroupRegistrationResult group = await client
    .GetOrCreateGroupAsync(client.RegistryNodeId, "schemas", ct)
    .ConfigureAwait(false);

// Only streams the document when it actually created the version.
ResourceRegistrationResult resource = await client.GetOrRegisterResourceAsync(
    group.GroupNodeId, "urn:my:resource", documentBytes, ct: ct).ConfigureAwait(false);

if (resource.Created)
{
    // The version is new on this server.
}

await client.DeleteResourceAsync(resource.ResourceNodeId, expectedEpoch, ct).ConfigureAwait(false);
await client.DeleteGroupAsync(group.GroupNodeId, groupEpoch, ct).ConfigureAwait(false);

Both results are readonly record structs, so they carry named members instead of positional tuple elements and still deconstruct when that reads better:

(NodeId nodeId, string versionId, bool created) = resource;

The typed proxies are also available directly, which is what a domain client builds on:

GroupTypeClient group = client.GetGroup(groupNodeId);
(NodeId nodeId, string versionId, uint fileHandle) =
    await group.GetOrCreateResourceAsync("urn:my:resource", string.Empty, true, ct)
        .ConfigureAwait(false);

ResourceTypeClient resource = client.GetResource(nodeId);
await resource.WriteDocumentAsync(fileHandle, documentBytes, ct: ct).ConfigureAwait(false);

Extending for a domain registry

A domain model subtypes the xRegistry base types — for example a schema registry declares SchemaFileType : ResourceType — so the generator emits a proxy chain that mirrors the OPC UA hierarchy (SchemaFileTypeClient : ResourceTypeClient : FileTypeClient). Two things follow:

• 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 directly 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. Discovery must be subtype-aware (browse with includeSubtypes, test with IsTypeOf) rather than comparing TypeDefinition NodeIds for equality.

Registry roots that are not well-known

XRegistryWellKnown.RegistryObject (65000) is provisional, and a domain registry generally declares its own root instead — the WoT Connectivity registry publishes WoTRegistry as a HasComponent child of the Server object, which a client discovers by Browse. Pass the resolved NodeId to the constructor so the root is a construction-time input that cannot subsequently drift:

public sealed class WotRegistryClient : XRegistryClient
{
    public WotRegistryClient(ISession session, NodeId registryObjectId, ITelemetryContext telemetry)
        : base(session, Namespaces.WotCon, registryObjectId, telemetry)
    {
        Proxy = new WoTRegistryTypeClient(session, registryObjectId, telemetry);
    }
}

RegistryNodeId then reports that root, and every inherited lifecycle method targets it. Passing a null NodeId selects the well-known root, so the overload stays equivalent to the namespace-only constructor. GenericXRegistryClient exposes the same overload, so a caller can drive a domain registry without deriving a client at all:

var registry = new GenericXRegistryClient(
    session, Namespaces.WotCon, wotRegistryNodeId, telemetry);

Opc.Ua.WotCon.Client is the worked example: WotRegistryClient derives from XRegistryClient, inherits Session, RegistryNodeId and the group/resource lifecycle, and adds only WoT-specific surface — the ForServerAsync Browse resolution, the reserved Thing Description / Thing Model groups, a typed Refresh result and a dependency-ordered bulk load.

Well-known identifiers

XRegistryWellKnown carries the base companion namespace URI and the provisional NodeIds a generic registry materializes. A concrete registry reuses the same numeric identifiers inside its own namespace, so the client-side lookup logic is shared.

Note: the NodeIds are provisional. Final identifiers are assigned by the OPC Foundation.

Member	Value	Meaning
XRegistryNamespaceUri	http://opcfoundation.org/UA/xRegistry/	Abstract base companion namespace
RegistryObject	65000	The registry root, a RegistryType instance
FederationProxyObject	66001	Federated resource proxy, a ResourceType instance
FirstDynamicInstance	100000	Start of the range allocated to runtime groups and resources

Everything else — the ObjectTypes, their Methods and their Variables — comes from the compiled model via the generated ObjectTypeIds, MethodIds and VariableIds classes. The model occupies 63000–63999, so the instance identifiers above can never collide with it.

Related documentation

• Source generation — how the companion model and its typed proxies are compiled into the assembly.
• Node management — the node manager model the three managers build on.
• PubSub (Part 14) — the PubSub Schema Registry specialization of this model.