UA-.NETStandard/docs/AsyncServerSupport.md

Support of the TAP (Task Asynchronous Pattern) for server operations

The OPC UA .NET Standard stack has long supported asynchronous server operations through the APM (Asynchronous Programming Model). APM uses IAsyncResult and the Begin/End pattern. .NET Framework 1.0 introduced this pattern, which remains supported in .NET 8.0.

The stack also supports TAP for server operations. TAP uses task-based APIs with async/await and is the recommended pattern for asynchronous server code.

Server applications can implement node managers with TAP to await I/O without blocking a request worker.

The server library provides these TAP features:

• Task-based RequestQueue and TransportListenerCallback
• Generated code and MasterNodeManager support Task-based operations.
• The IAsyncNodeManager interface supports fully asynchronous node managers.
• AsyncNodeManagerAdapter and SyncNodeManagerAdapter let synchronous and asynchronous node managers run side by side.

Contents

• Upgrading an existing server
• Async method calls
• AsyncCustomNodeManager
  • Registering an AsyncCustomNodeManager
  • Async browse iteration
  • Locking strategy vs CustomNodeManager2
    • 1. Global write semaphore — m_writeSemaphore
    • 2. Monitored-item semaphore — m_monitoredItemSemaphore
    • 3. Per-node locking for read and attribute access
  • Monitored-item manager selection
  • Fully asynchronous change notifications
  • Creating a custom node manager

Upgrading an existing server

• Update INodeManager.CreateMonitoredItems to support the new MonitoredItemIdFactory.
• AsyncCustomNodeManager is the recommended base class for fully asynchronous node managers; see AsyncCustomNodeManager.
• Keep using CustomNodeManager2 and implement the asynchronous interfaces your server needs:
  • IAsyncNodeManager for full async support
  • ICallAsyncNodeManager for async method calls
  • IReadAsyncNodeManager for async reading
  • IWriteAsyncNodeManager for async writing
  • IHistoryReadAsyncNodeManager for async history read
  • IHistoryUpdateAsyncNodeManager for async history update
  • IConditionRefreshAsyncNodeManager for async condition refresh
  • ITranslateBrowsePathAsyncNodeManager for async translate browse path
  • IBrowseAsyncNodeManager for async browsing
  • ISetMonitoringModeAsyncNodeManager for async monitoring mode changes
  • ITransferMonitoredItemsAsyncNodeManager for async monitored item transfer
  • IDeleteMonitoredItemsAsyncNodeManager for async monitored item deletion
  • IModifyMonitoredItemsAsyncNodeManager for async monitored item modification
  • ICreateMonitoredItemsAsyncNodeManager for async monitored item creation

MasterNodeManager detects which asynchronous interfaces a node manager implements. It uses an asynchronous implementation when available and otherwise falls back to the synchronous implementation.

• The server supports fully asynchronous node managers that implement IAsyncNodeManager. Register one with StandardServer.RegisterNodeManager(IAsyncNodeManagerFactory). IAsyncNodeManager.SyncNodeManager is required for compatibility; pass the node manager to SyncNodeManagerAdapter to provide it.

Async method calls

CustomNodeManager2 supports asynchronous method callbacks. Implement IAsyncNodeManager on your node manager to enable them. Generated method state classes expose asynchronous callbacks such as UpdateCertificateMethodState.OnCallAsync; the server uses these callbacks when the node manager implements the interface. For a generic method handler, use MethodState.OnCallMethod2Async.

AsyncCustomNodeManager

AsyncCustomNodeManager is the recommended base class for building fully async, TAP-native node managers. Unlike the older CustomNodeManager2, it implements IAsyncNodeManager directly rather than INodeManager3. This has two practical consequences:

• All virtual methods are async ValueTask-returning from the start, so there is no boilerplate wrapping of synchronous code inside Task.Run or similar helpers.
• The SyncNodeManager property (required by IAsyncNodeManager) is satisfied automatically: the constructor calls this.ToSyncNodeManager() and stores the resulting INodeManager3 adapter. Callers that still require an INodeManager3 reference (e.g. legacy subscription code) use that adapter; the node manager itself never needs to implement the synchronous interface.

Registering an AsyncCustomNodeManager

Use the IAsyncNodeManagerFactory overload of StandardServer.RegisterNodeManager:

server.RegisterNodeManager(context =>
    new MyAsyncNodeManager(server, configuration));

Async browse iteration

Every hook a custom node manager overrides is awaitable, including browse operations. AsyncCustomNodeManager.BrowseAsync and TranslateBrowsePathAsync iterate an INodeBrowser with NextAsync(CancellationToken) instead of Next(). A browser can therefore fetch data from an underlying system asynchronously. For example, it can retrieve references from another server without occupying a request worker with a blocking call. The default NextAsync wraps Next(), so the browsers provided by the stack and existing custom browsers continue to work. See NodeManagers.md for the browser contract.

Locking strategy vs CustomNodeManager2

The synchronous CustomNodeManager2 service paths use coarse-grained manager synchronization. AsyncCustomNodeManager instead coordinates writes and monitored-item management with awaitable semaphores while leaving node-state synchronization inside NodeState.

The following describes the implementation, not locks that application callers should acquire. Use the manager's service, lifecycle, and fluent APIs so operation admission, cancellation, and disposal remain coordinated.

1. Global write semaphore — m_writeSemaphore

The manager serializes its Write service operations through an awaitable semaphore. Read operations do not acquire it. The semaphore does not turn external updates or several attribute accesses into a transaction; use the node APIs for state access.

2. Monitored-item semaphore — m_monitoredItemSemaphore

A second SemaphoreSlim(1, 1) serializes monitored-item management operations. It keeps subscription state consistent without blocking reads or writes. The semaphore protects:

• create, modify, and delete operations
• monitoring-mode changes
• event subscriptions and condition refresh
• monitored-item transfers

3. Per-node locking for read and attribute access

Reads do not acquire a manager-wide lock. NodeState synchronizes attribute and collection access internally; the async manager awaits ReadAttributeAsync so that asynchronous value handlers can complete without blocking a thread.

Do not use lock (node) or lock (handle.Node). Those monitors do not coordinate with the node's private locks and cannot protect its state. Use the node's attribute, child, and reference APIs instead. Individually synchronized operations do not form an atomic multi-attribute transaction.

See the threading contract for nodes and browsers for supported operations, snapshot boundaries, and browser ownership.

Concern	CustomNodeManager2	AsyncCustomNodeManager
Address-space reads	Manager synchronization	Internally synchronized node APIs
Write service operations	Manager synchronization	Awaitable write serialization
Monitored-item management	Manager synchronization	Awaitable monitored-item serialization
Awaiting asynchronous handlers	Use the asynchronous path	Supported by asynchronous operations
Implemented interface	INodeManager3	IAsyncNodeManager

Monitored-item manager selection

The constructor accepts an optional useSamplingGroups flag:

// Default: change-triggered (MonitoredNodeMonitoredItemManager)
public MyNodeManager(IServerInternal server, ApplicationConfiguration config)
    : base(server, config) { }

// Opt-in: timer-based sampling (SamplingGroupMonitoredItemManager)
public MyNodeManager(IServerInternal server, ApplicationConfiguration config)
    : base(server, config, useSamplingGroups: true) { }

• MonitoredNodeMonitoredItemManager (default): node value changes are propagated to subscribers immediately by awaiting NodeState.ClearChangeMasksAsync after every successful write (see Fully asynchronous change notifications). No background threads are created per subscription.
• SamplingGroupMonitoredItemManager: a background timer thread samples the current node value at the negotiated SamplingInterval. Write changes are not pushed immediately; instead the next scheduled sample detects and delivers them. Choose this mode when the data source produces values independently of OPC UA write requests (e.g. hardware polling).

Fully asynchronous change notifications

AsyncCustomNodeManager sends value changes and events to monitored items through an asynchronous push path. This path does not block a thread when a node uses an asynchronous value-read handler or when the per-node notification channel applies back-pressure.

The per-node channel admits two pending notifications behind the active consumer. Each notification retains its enqueue-time attribute values, including large structures and subscriber-specific copies. Producers asynchronously wait when that bound is reached; accepted data changes and events are preserved in order rather than discarded. Await the asynchronous reporting APIs so a slow consumer cannot accumulate thousands of retained snapshots.

Subscriber-specific access checks use values captured for that subscriber at enqueue time. A subscriber joining behind an already queued change does not inherit the reporter's denied value when no value was captured for the new subscriber. It receives its initial value and subsequent changes instead. The dispatcher does not reread the node for that notification, because a reread could return a later value. Subscribers denied access receive the corresponding error. Captured subscriber-specific values also retain their session and identity attribution. Attaching or transferring an item before dispatch cannot make it inherit an older owner's captured value or unauthenticated access-denied result.

NodeState exposes asynchronous counterparts of its change-notification API alongside the existing synchronous members:

Synchronous	Asynchronous
ClearChangeMasks(context, includeChildren)	ClearChangeMasksAsync(context, includeChildren, ct)
OnStateChanged / StateChanged	OnStateChangedAsync / StateChangedAsync
ReportEvent(context, e)	ReportEventAsync(context, e, ct)
OnReportEvent	OnReportEventAsync

These additions do not break existing synchronous callers or sinks. MonitoredNodeMonitoredItemManager wires the asynchronous sinks. After a successful write, AsyncCustomNodeManager.WriteAsync flushes changes by awaiting handle.Node.ClearChangeMasksAsync(...).

The asynchronous sink reads each monitored attribute through NodeState.ReadAttributeAsync. When registered, an asynchronous OnReadValueAsync or OnSimpleReadValueAsync handler supplies the value. The sink then enqueues that snapshot through the bounded per-node channel and awaits completion. It reads the value before enqueueing the change, so each notification captures the node value at the time of the change. Awaiting both operations keeps the producing thread from blocking.

The synchronous ClearChangeMasks and ReportEvent methods also drive the asynchronous sinks. They complete inline when the node is synchronously readable and the channel has capacity. They block the calling thread only while an asynchronous read is in flight or the channel is full. Synchronous node managers continue to work without changes, but may block in those two cases.

Each monitored item's queue controls overflow and discard behavior, including FIFO/LIFO DiscardOldest and the Overflow status bit. The shared per-node channel does not drop notifications. As a result, the configured queue policy applies to the full stream of changes.

Creating a custom node manager

Derive from AsyncCustomNodeManager and override only the virtual methods you need:

public class MyNodeManager : AsyncCustomNodeManager
{
    public MyNodeManager(IServerInternal server, ApplicationConfiguration config)
        : base(server, config, "http://my.org/UA/Data/")
    {
    }

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

        // build your nodes here
        var myVar = new BaseDataVariableState(null);
        myVar.NodeId  = new NodeId("MyVar", NamespaceIndex);
        myVar.Value   = 42;
        await AddNodeAsync(SystemContext, default, myVar, cancellationToken)
              .ConfigureAwait(false);
    }
}