UA-.NETStandard/docs/AliasNames.md

OPC UA Part 17 — Alias Names

OPC UA Part 17 defines a small but valuable address-space pattern: a hierarchy of human-readable alias names that point at one or more nodes via a non-hierarchical reference type. Clients can search the hierarchy by wildcard pattern and resolve a name to its targets without needing to know the target NodeId in advance — useful for tag-naming schemes (PI / SCADA / DCS), pub/sub topic registries, MES integration, and any scenario where humans pick names but machines need ids.

This stack ships full Part 17 support in Opc.Ua.Server (server side) and Opc.Ua.Client (client side). The implementation covers:

Spec section	Type / Method	Status
§6.2	AliasNameType (browsable instance nodes)	✔ opt-in — see below
§6.3.1	AliasNameCategoryType (incl. nesting)	✔ (nested instances opt-in — see below)
§6.3.1	LastChange (VersionTime)	✔
§6.3.2	FindAlias	✔
§6.3.3	FindAliasVerbose	✔
§6.3.4	AddAliasesToCategory	✔
§6.3.5	DeleteAliasesFromCategory	✔
§7.2	AliasNameDataType	✔
§7.3	AliasNameVerboseDataType	✔
§8.2	AliasFor reference type	✔
§9.2	Well-known Aliases (i=23470)	✔ wired; optional methods opt-in — see below
§9.3	Well-known TagVariables (i=23479)	✔ wired; optional methods opt-in — see below
§9.4	Well-known Topics (i=23488)	✔ wired; optional methods opt-in — see below
Annex D	PubSub replication (LastChange notifications)	✔ transport-agnostic — see below

Server side — Opc.Ua.Server.AliasNames

Search patterns use the shared LikePattern parser and matcher, with case-sensitive whole-string matching. Backslashes escape literal characters inside and outside character sets; [^...] negates a set ([!...] remains accepted for compatibility). Wildcards match line breaks. Trailing escapes, malformed sets, descending ranges, and unescaped ^ outside the start of a set return BadInvalidArgument from both FindAlias variants even with an empty store. Matching each alias name has a 100 ms time limit; exceeding it returns BadTimeout. The server also checks for request cancellation before matching the next name.

The server library exposes a pluggable backend (IAliasNameStore) plus a default in-memory implementation. Apps assemble their alias inventory inside a store, then either:

1. Register the store through AddAliasNameStore(...) on the DI server builder, or directly with the server-wide IAliasNameStoreRegistry, so the standard well-known Aliases/TagVariables/Topics nodes start dispatching through it, or
2. Wrap the store in an AliasNameNodeManager to expose application- defined categories under a custom namespace (with full AddAliasesToCategory / DeleteAliasesFromCategory support).

Both approaches can be combined.

Quick start — serving standard categories

using Microsoft.Extensions.DependencyInjection;
using Opc.Ua;
using Opc.Ua.Server.AliasNames;

var tagVariables = new AliasNameCategoryDescriptor(
    ObjectIds.TagVariables,
    QualifiedName.From(BrowseNames.TagVariables),
    AliasNameCapabilities.FindAliasVerbose);

var store = new InMemoryAliasNameStore([tagVariables]);
store.Seed(ObjectIds.TagVariables, "ServerCurrentTime",
    new ExpandedNodeId(VariableIds.Server_ServerStatus_CurrentTime),
    serverUri: null,
    referenceTypeId: ReferenceTypeIds.AliasFor);

services.AddOpcUa()
    .AddServer(options =>
    {
        options.ApplicationName = "AliasServer";
        options.EndpointUrls.Add("opc.tcp://localhost:4840/AliasServer");
    })
    .AddAliasNameStore(store)
    .ConfigureAliasNames(options => options.MaterializeAliasNodes = true);

AddAliasNameStore(...) and AddAliasNameStoreRegistry(...) register their stores before address-space startup, after application IServerPreStartupTask registrations have finished initializing source registries. The opt-in ConfigureAliasNames(Action<AliasNameServerOptions>) extension is on IOpcUaServerBuilder in Microsoft.Extensions.DependencyInjection. AliasNameServerOptions is in Opc.Ua.Server.AliasNames, and its MaterializeAliasNodes property defaults to false.

When enabled, the normal ConfigurationNodeManager materializes registered standard-category aliases and their declared optional capabilities after the standard nodes have loaded. No server or diagnostics-node-manager subclass is needed. The same setting applies to stores for Topics; their targets must be PublishedDataSetType instances. Omit ConfigureAliasNames(...) when only method-based lookup is needed.

When a client calls Aliases.FindAlias (i=23476), TagVariables.FindAlias (i=23485) or Topics.FindAlias (i=23494), DiagnosticsNodeManager's late binder routes the call through the registry to the matching store.

Direct IAliasNameStoreRegistry registration remains available for custom hosting. Register stores before the materialization pass when their aliases must also be browsable.

Quick start — application-defined categories

AliasNameNodeManager is a CustomNodeManager2 that owns a namespace and creates its own category tree from the store's RootCategories. Add it to your server's node-manager list:

var myRoot = new AliasNameCategoryDescriptor(
    new NodeId("My/Category", myNamespaceIndex),
    new QualifiedName("My/Category", myNamespaceIndex),
    AliasNameCapabilities.All);            // expose every optional method
var store = new InMemoryAliasNameStore([myRoot]);
nodeManagers.Add(new AliasNameNodeManager(server, configuration, store));

Options:

• NamespaceUri — controls the namespace under which the manager registers its category instances. Defaults to http://opcfoundation.org/UA/AliasName/. Every category descriptor's NodeId must lie in this namespace; descriptors pointing anywhere else are skipped with a warning rather than claiming another manager's ids.
• MaterializeAliasNodes (default true, unchanged for AliasNameNodeManagerOptions) — creates one browsable AliasNameType node per alias, with AliasFor references to its targets, exactly as the standard-node materialization below does. Disable to expose only the category tree.
• LinkToStandardAliasesObject (default true) — adds Organizes external references from the well-known Aliases (i=23470) object to the manager's root categories so they show up in the standard browse tree.
• RequireSecurityAdminForMutations (default true) — rejects AddAliasesToCategory / DeleteAliasesFromCategory calls from unauthenticated users or sessions without the WellKnownRole_SecurityAdmin role on a SignAndEncrypt channel.
• RegisterWithServerRegistry (default true) — also registers the store with IAliasNameStoreRegistry so the well-known standard nodes see it.

Browsable alias nodes

Registering a store makes FindAlias answer from it, but the aliases themselves stay inside the store — nothing in the address space shows them. Part 17 §6.2 clients (the OPC Foundation CTT among them) also browse for aliases, so a server under conformance test needs the alias hierarchy materialized as real nodes.

Both materialization paths — AliasNameNodeManager for application-defined namespaces and DiagnosticsNodeManager.MaterializeRegisteredAliasNameNodesAsync for the standard well-known nodes — run the same shared walker (AliasNameNodeMaterializer), so they produce structurally identical Part 17 trees and every fix lands in both at once.

For the standard DI server, ConfigureAliasNames(options => options.MaterializeAliasNodes = true) makes the normal ConfigurationNodeManager invoke that helper. Its default is false, independent of the custom AliasNameNodeManagerOptions default of true. Metadata, resource, and alias configuration use the DependencyInjectionStandardServer hooks; a non-DI custom AddServer<TServer>() rejects these DI-only settings rather than silently ignoring them.

DiagnosticsNodeManager.MaterializeRegisteredAliasNameNodesAsync does that for every registered store: one AliasNameType instance per alias — BrowseName carrying the alias name, AliasFor references to its targets, and the inverse HasAlias reference added on each local target — plus an AliasNameCategoryType instance for every store category the standard NodeSet does not already ship (nested categories included; a root category from the store is organized under the standard Aliases object so it stays browse-discoverable). Remote targets get their server URI registered in the server's ServerUris table and referenced with the matching ServerIndex. Server-defined BrowseNames that a descriptor left in namespace 0 — reserved for OPC-Foundation-defined names — are re-homed into the diagnostics namespace; Part 17 clients compare alias names ignoring the namespace, so this is transparent to them. The pass is idempotent, and only creates category nodes whose NodeId lies in the diagnostics namespace — a descriptor pointing anywhere else is skipped with a warning rather than claiming another manager's (or the standard NodeSet's) ids. Custom diagnostics-node-manager implementations can still call the helper from an overridden CreateAddressSpaceAsync, after base has loaded the standard categories:

public override async ValueTask CreateAddressSpaceAsync(
    IDictionary<NodeId, IList<IReference>> externalReferences,
    CancellationToken cancellationToken = default)
{
    await base.CreateAddressSpaceAsync(externalReferences, cancellationToken)
        .ConfigureAwait(false);

    await MaterializeRegisteredAliasNameNodesAsync(
        externalReferences, cancellationToken).ConfigureAwait(false);
}

The same pass also instantiates the optional Part 17 members — FindAliasVerbose, AddAliasesToCategory, DeleteAliasesFromCategory and LastChange — on every category whose descriptor declares them through AliasNameCapabilities, including the well-known ones the standard NodeSet ships without them:

var tagVariables = new AliasNameCategoryDescriptor(
    ObjectIds.TagVariables,
    QualifiedName.From(BrowseNames.TagVariables),
    AliasNameCapabilities.All);       // verbose + add + delete + LastChange

Mutation calls are gated on a SecurityAdmin caller over a SignAndEncrypt channel and return BadUserAccessDenied otherwise.

Standard-category materialization is opt-in: servers that only need FindAlias to answer from their store do not create alias instance nodes. The created nodes are a snapshot taken at address-space creation — aliases added or removed later through AddAliasesToCategory / DeleteAliasesFromCategory change what FindAlias returns and advance LastChange, but do not add or remove AliasNameType nodes.

The browse view carries AliasFor associations only: an entry a store holds under an unrelated reference type is not a Part 17 §6.2 alias association, so it is served by FindAlias (with a matching filter) but not materialized. Entries stored under an AliasFor subtype are materialized, but always as the base AliasFor reference — the verbose record does not carry the concrete reference type.

Two things the caller controls:

• Give category descriptors a BrowseName in a namespace the server owns. The store stamps that namespace onto every alias QualifiedName it reports, and the materializer re-homes ns=0 BrowseNames out of the reserved OPC Foundation namespace — with a server-owned descriptor namespace the query results and the browsable nodes agree, so a returned alias name resolves via TranslateBrowsePathsToNodeIds. The reference server uses the diagnostics namespace for all its descriptors.
• Part 17 §9 constrains Topics aliases to PublishedDataSetType targets. Neither the store nor AddAliasesToCategory enforces this — a server that exposes the mutation methods on Topics should only grant them to operators who preserve the constraint.

Quickstarts.ReferenceServer uses this in ReferenceServerConfigurationNodeManager, which also creates the PublishedDataSet instances and seeds the Topics aliases that point at them — in the same place, so an alias can never target a dataset that was not created. The nested Devices sub-category under TagVariables is declared with the store seeding in ReferenceServer.ConfigureAliasNameStore.

Custom backend

Implement IAliasNameStore to back the alias inventory with your own storage (DB, file, MES, …). The interface is small:

public interface IAliasNameStore
{
    IReadOnlyList<AliasNameCategoryDescriptor> RootCategories { get; }
    event EventHandler<AliasStoreChangedEventArgs>? Changed;

    uint? GetLastChange(NodeId categoryId);
    bool OwnsCategory(NodeId categoryId);

    ValueTask<IReadOnlyList<AliasNameDataType>> FindAliasAsync(...);
    ValueTask<IReadOnlyList<AliasNameVerboseDataType>> FindAliasVerboseAsync(...);
    ValueTask<StatusCode[]> AddAliasesAsync(...);
    ValueTask<StatusCode[]> DeleteAliasesAsync(...);
}

The reference InMemoryAliasNameStore is thread-safe (SemaphoreSlim), supports nested categories and emits Changed events that bubble up to the address-space LastChange property. A mutation on a nested category bumps — and notifies for — every ancestor category as well, per Part 17 §6.3.1/§9.2: a category's LastChange reflects the most recent change anywhere in its subtree, and the root Aliases value reflects any change at all.

Client side — Opc.Ua.Client.AliasNames

The client library provides a high-level AliasNameClient plus a caching AliasNameResolver.

using Opc.Ua.Client.AliasNames;

// Standard categories have hardcoded method NodeIds so the first call
// is one round-trip — no extra TranslateBrowsePaths probe needed.
AliasNameClient client = AliasNameClient.OpenStandardTagVariables(session);

IReadOnlyList<AliasNameDataType> result =
    await client.FindAliasAsync("TIC%", referenceTypeFilter: null, ct);

AliasNameClient exposes the full Part 17 method surface:

• FindAliasAsync(pattern, referenceTypeFilter, ct)
• FindAliasVerboseAsync(...) — throws NotSupportedException when the category does not expose the optional method.
• AddAliasesToCategoryAsync(IEnumerable<AliasNameAddRequest>, ct)
• DeleteAliasesFromCategoryAsync(IEnumerable<AliasNameDeleteRequest>, ct)
• EnumerateSubCategoriesAsync(ct) — IAsyncEnumerable of child AliasNameSubCategoryInfo.
• ReadLastChangeAsync(ct) — returns the VersionTime (or null when the category does not expose LastChange).

Per-call errors map to typed exceptions:

Status code	Exception
BadUserAccessDenied	UnauthorizedAccessException
BadNotSupported	NotSupportedException
BadNotImplemented	NotSupportedException
other BadXxx	ServiceResultException

AliasNameResolver — cached alias→NodeId

await using var resolver = new AliasNameResolver(
    AliasNameClient.OpenStandardTagVariables(session));

IReadOnlyList<ExpandedNodeId> targets =
    await resolver.ResolveAsync("TIC101_Setpoint", ct);

string aliasName = await resolver.ResolveAliasNameAsync(targets[0], ct);

Default refresh mode is Manual — callers invoke RefreshAsync (or rely on lazy-load via ResolveAsync). Opt in to automatic cache invalidation via one of:

AliasNameResolverRefreshMode	Strategy	When to use
Manual (default)	ManualAliasNameRefreshStrategy	Caller drives refresh explicitly. Safe everywhere.
AutoOnLastChangePolling	PollingAliasNameRefreshStrategy	Server lacks Subscriptions or you want a fixed Read cadence.
AutoOnLastChangeMonitoredItem	MonitoredItemAliasNameRefreshStrategy	Server supports Subscriptions. Push-based — no Read per interval.

Custom strategies (e.g. the Annex D PubSub bridge in Opc.Ua.Client.AliasNames.PubSub — see Annex D below) plug in via:

new AliasNameResolverOptions
{
    RefreshStrategy = new MyCustomStrategy()  // takes precedence over RefreshMode
}

The IAliasNameRefreshStrategy contract is tiny:

public interface IAliasNameRefreshStrategy : IAsyncDisposable
{
    ValueTask StartAsync(AliasNameClient client, Action onInvalidate, CancellationToken ct);
}

Implementations watch for stale-cache triggers and invoke onInvalidate whenever they detect a change. MonitoredItemAliasNameRefreshStrategyOptions controls the underlying Subscription: it can be left owned (default — created + deleted by the strategy) or set via SharedSubscription to plug the monitored item into an externally managed subscription.

Disposing the resolver (await using / DisposeAsync) tears down the strategy: timer for polling, MonitoredItem + Subscription for the monitored-item variant. Disposal is idempotent and never throws.

Spec deviations / wrinkles

• AliasNameDataType.ReferencedNodes — the wire format defines this as ExpandedNodeId[] (NodeSet i=18), not NodeId[]. The source-generated AliasNameDataType is correct; the historical Quickstart sample used NodeId[] and has been removed.

• Standard well-known nodes — the OPC UA NodeSet instantiates only FindAlias on Aliases/TagVariables/Topics (plus LastChange on Aliases), so the always-on binder wires just those. The optional methods are added by MaterializeRegisteredAliasNameNodesAsync through the generated AddFindAliasVerbose / AddAddAliasesToCategory / AddDeleteAliasesFromCategory optional- child helpers, for each category whose descriptor declares the matching AliasNameCapabilities. Each child is created at the NodeId the OPC Foundation reserves for it (Aliases.FindAliasVerbose = i=24054, TagVariables.LastChange = i=32854, and so on).

  Those identifiers are allocated in the standard identifier registry (StandardTypes.csv) but are deliberately not declared in the ModelDesign and not present in the published NodeSet — the standard address space does not instantiate optional children. A reserved id is a number set aside for the node if a server chooses to expose it, not a node the server must have. Consequently the source generator emits no parent-to-instance mapping and no MethodIds constant for them, and DiagnosticsNodeManager.ReservedChildIds supplies the nine method ids and the two missing LastChange ids explicitly, each traceable to its registry row. The argument properties do have generated VariableIds constants and are referenced through those.

  Do not "fix" this by declaring the children in StandardTypes.xml: that file is a verbatim copy of the OPC Foundation's ModelDesign and is re-synced from upstream, so a local edit is lost on the next sync and the NodeIds silently revert to factory-minted ones.

• AliasNameCapabilities.AddAliasesToCategory / DeleteAliasesFromCategory — on an AliasNameNodeManager this defaults to SecurityAdmin-only via AliasNameNodeManagerOptions.RequireSecurityAdminForMutations; on the standard well-known nodes the same check is always applied and cannot be opted out of. It requires both the role grant AND a SignAndEncrypt channel.

• ReferenceTypeFilter semantics — null/empty and ReferenceTypeIds.References match every alias regardless of reference type. Otherwise matches are limited to aliases whose reference type is, or is a subtype of, the filter (using Server.TypeTree.IsTypeOf).

Annex D — PubSub LastChange notifications

Part 17 Annex D defines a lightweight PubSub schema for alias-change notifications between servers. The schema carries only each category's current LastChange value (a VersionTime/uint) — subscribers learn that a publisher's category changed, then refetch alias contents via FindAlias/FindAliasVerbose if needed.

The data types (already emitted by the source generator):

NodeId	Type	Fields
i=24052	AliasCategoryUpdateDataType	Category : PortableNodeId, LastChange : VersionTime
i=24053	AliasUpdateDataType	ApplicationUri : string, Categories : AliasCategoryUpdateDataType[]

Server side — Opc.Ua.Server.AliasNames.PubSub

The server library exposes a transport-agnostic publisher that emits fully-built AliasUpdateDataType messages whenever an IAliasNameStoreRegistry-tracked store changes:

using Opc.Ua.Server.AliasNames;
using Opc.Ua.Server.AliasNames.PubSub;

// inside server startup (after the alias store is registered):
var resolver = new ServerPortableNodeIdResolver(server);
var publisher = new AliasNamePublisher(
    registry: ((IAliasNameStoreRegistryProvider)server).AliasNameStoreRegistry,
    portableResolver: resolver,
    applicationUri: configuration.ApplicationUri);

publisher.AliasUpdateProduced += (_, e) =>
{
    // Hand `e.Update` to your transport — e.g. publish a DataSetMessage
    // through Opc.Ua.PubSub.UaPubSubApplication with the DataSet
    // built by AliasUpdateDataSetFactory.Create(...).
};

Helpers shipped:

• IPortableNodeIdResolver + ServerPortableNodeIdResolver — converts a local NodeId into the spec-required PortableNodeId (NamespaceUri + Identifier with namespace index stripped).
• AliasUpdateDataSetFactory.Create(dataSetClassId) — builds the fixed-by-spec DataSetMetaDataType describing the AliasUpdate DataSet (ApplicationUri : string, Categories : AliasCategoryUpdateDataType[]).
• AliasNamePublisher — subscribes to the registry, builds and emits AliasUpdateDataType messages via the AliasUpdateProduced event.

The library deliberately stays transport-agnostic: it raises the fully-built AliasUpdateDataType and lets the application wire it into Opc.Ua.PubSub.UaPubSubApplication (UDP / JSON / MQTT) or any other transport that can carry the AliasUpdateDataType payload.

Client side — Opc.Ua.Client.AliasNames.PubSub

The client library mirrors the publisher:

using Opc.Ua.Client.AliasNames;
using Opc.Ua.Client.AliasNames.PubSub;

var reader = new AliasNamePubSubReader(
    new AliasNamePubSubReaderOptions
    {
        ExpectedApplicationUri = "urn:opcfoundation:publisher",
    });

// Hand incoming AliasUpdateDataType messages off to the reader from
// your transport (e.g. UaPubSubApplication.DataReceived, an MQTT
// subscriber callback, ...):
reader.Submit(receivedAliasUpdate);

// Wire reader into the resolver so the cache invalidates on every
// LastChange bump observed via PubSub.
await using var resolver = new AliasNameResolver(
    AliasNameClient.OpenStandardAliases(session),
    new AliasNameResolverOptions
    {
        RefreshStrategy = new AliasNamePubSubRefreshStrategy(reader),
    });

Helpers shipped:

• AliasNamePubSubReader — surfaces incoming AliasUpdateDataType messages as the AliasUpdateReceived event. Optional ExpectedApplicationUri filter drops messages from other publishers.
• AliasNamePubSubRefreshStrategy : IAliasNameRefreshStrategy — bridges the reader into the resolver. Matches incoming entries by the resolver's category NamespaceUri + identifier; fires Invalidate on any value-difference (wrap-safe — the comparison is inequality, not strict greater-than).

The PubSub bridge plugs into the same IAliasNameRefreshStrategy extension point as the polling and monitored-item strategies — apps can mix-and-match, e.g. fall back to polling on a particular category while letting PubSub drive the rest.

See also

• OPC UA Part 17 specification: https://reference.opcfoundation.org/v105/Core/docs/Part17/
• Dependency Injection — hosted store registration and standard-category materialization.
• tools/Opc.Ua.SourceGeneration.Core/Design/StandardTypes.xml — Part 17 type definitions consumed by the source generator.
• tests/Opc.Ua.Server.Tests/AliasNames/ — server-side unit tests.
• tests/Opc.Ua.Client.Tests/AliasNames/ — mocked-session and live integration tests.
• samples/Quickstarts.Servers/ReferenceServer/ReferenceServer.cs — ConfigureAliasNameStore shows how to seed and register a store.