OPC UA Device Integration (DI)

August 4, 2026 · View on GitHub

Glossary: In this document, DI refers to OPC UA Device Integration (companion specification OPC 10000-100), not to .NET Dependency Injection (covered in DependencyInjection.md). Wherever this document uses the unqualified initialism "DI" it always means the companion spec; .NET-DI mentions are spelled out as "Dependency Injection (.NET DI)" or appear with Microsoft.Extensions.DependencyInjection in context.

End-to-end developer guide for the Opc.Ua.Di* library trio shipped with this repository and the services.AddOpcUa() hosting model that plugs it together.

Contents

Library layout

LibraryRole
Opc.Ua.DiModel assembly: source-generated NodeId tables, DataTypes, ObjectType client proxies, AddOpcUaDi(NodeStateCollection) extension.
Opc.Ua.Di.ServerServer: DiNodeManager, fluent topology/device builders, locking service, software-update package store, hosting integration.
Opc.Ua.Di.ClientClient: DiDeviceClient, DiDiscoveryClient, DiTopologyClient, DiLockClient, SoftwareUpdateClient, hosting integration.

The running example is samples/PumpDeviceIntegrationServer, a companion-spec server that exposes a configurable number of fully simulated PumpType instances. The sample uses the hand-written fluent node-manager style for the common pump model and simulation wiring, then uses ConfigureDevicesFor with the topology-element builder to add an ad-hoc Diagnostics functional group to each pump. The simulated asset is specified by its own product datasheet, samples/PumpDeviceIntegrationServer/DATASHEET.md, which maps every nameplate field, engineering range and alarm trip point to its OPC UA browse path.

Quick start

Plain Device Integration (DI) server

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Services
    .AddOpcUa()
    .AddServer(o =>
    {
        o.ApplicationName = "MyDiServer";
        o.EndpointUrls.Add("opc.tcp://localhost:48010/MyDiServer");
    })
    .AddOpcUaDi()
    .ConfigureDevicesFor<DiNodeManager>(async ctx =>
    {
        var device = await ctx.CreateDeviceAsync(
            new QualifiedName("Sensor_1", ctx.Manager.InstanceNamespaceIndex));
        device.WithIdentification(id =>
        {
            id.Manufacturer = new LocalizedText("Acme");
            id.SerialNumber = "SN-001";
            id.DeviceClass = "Sensor";
        });
    });

await builder.Build().RunAsync();

Companion-spec server (Pumps + Device Integration)

builder.Services
    .AddOpcUa()
    .AddServer(o => { ... })
    .AddNodeManager<Pumps.PumpNodeManagerFactory>()
    // Pump factory already loads OPC UA Device Integration via its LoadPredefinedNodesAsync
    // direct chain; do NOT call AddOpcUaDi() — that would
    // double-register the OPC UA Device Integration namespace.
    .ConfigureDevicesFor<Pumps.PumpNodeManager>(ctx =>
    {
        var manager = (Pumps.PumpNodeManager)ctx.Manager;
        foreach (NodeId pumpNodeId in manager.PumpNodeIds)
        {
            ITopologyElementBuilder<PumpState> pump =
                ctx.TopologyElement<PumpState>(pumpNodeId);
            pump.WithFunctionalGroup(
                new QualifiedName("Diagnostics", manager.InstanceNamespaceIndex),
                group => group.Configure(node =>
                    node.WithProperty("LastError", Variant.From(string.Empty))));
        }

        return ValueTask.CompletedTask;
    });

Client

builder.Services
    .AddOpcUa()
    .AddClient(o => { o.Configuration = ...; o.Session.Endpoint = ...; })
    .AddOpcUaDi();

public sealed class MyAppService(
    IDiDiscoveryService discovery,
    Func<NodeId, CancellationToken, ValueTask<DiDeviceClient>> deviceFactory,
    Func<CancellationToken, ValueTask<DiTopologyClient>> topologyFactory)
{
    public async Task PrintAsync(CancellationToken ct)
    {
        DiTopologyClient topology = await topologyFactory(ct);
        await foreach (TopologyEntry entry in topology.EnumerateDevicesAsync(ct))
        {
            DiDeviceClient device = await deviceFactory(entry.NodeId, ct);
            DeviceIdentification id = await device.ReadIdentificationAsync(ct);
            Console.WriteLine($"{id.Manufacturer} {id.Model} ({id.SerialNumber})");
        }
    }
}

Device builder

The IDeviceBuilder<TDevice> fluent surface is the recommended way to create and configure Device Integration device instances programmatically. It lives in Opc.Ua.Di.Server.Builders and integrates with the broader fluent API for node managers.

Runtime-created NodeIds use the server namespace. DiNodeManager now mints NodeIds for device and topology instances in InstanceNamespaceIndex, the server application's namespace derived from ApplicationConfiguration.ApplicationUri, rather than in the DI or companion-spec namespace of the parent. This follows the companion-spec boilerplate rule (for example OPC 10000-100 §13.4 and OPC 40223) that nodes not defined by a specification do not use the standard namespace; the Local Server URI namespace is the namespace for nodes defined by the local server. BrowseNames defined by DI or a companion specification keep their specification namespace, while application-defined instance names, functional groups, and properties should use InstanceNamespaceIndex.

Entry points

All entry points live on DiNodeManager:

// Default DeviceState organized by the Device Integration DeviceSet (or attached
// below whatever ResolveDefaultDeviceParent() returns).
ValueTask<IDeviceBuilder<DeviceState>> CreateDeviceAsync(
    QualifiedName browseName,
    NodeState? parent = null,
    CancellationToken ct = default);

// Typed factory for ComponentType-derived companion-spec devices.
ValueTask<IDeviceBuilder<TDevice>> CreateDeviceAsync<TDevice>(
    QualifiedName browseName,
    NodeId typeDefinitionId,
    Func<NodeState, TDevice> factory,
    NodeState? parent = null,
    CancellationToken ct = default)
    where TDevice : ComponentState;

// Wrap an existing device.
IDeviceBuilder<TDevice> Device<TDevice>(TDevice device)
    where TDevice : ComponentState;
IDeviceBuilder<TDevice> Device<TDevice>(NodeId nodeId)
    where TDevice : ComponentState;
IDeviceBuilder<TDevice> DeviceByBrowseName<TDevice>(
    QualifiedName browseName,
    NodeState? parent = null)
    where TDevice : ComponentState;

// Wrap an existing TopologyElementType-derived companion instance.
ITopologyElementBuilder<TElement> TopologyElement<TElement>(TElement element)
    where TElement : TopologyElementState;
ITopologyElementBuilder<TElement> TopologyElement<TElement>(NodeId nodeId)
    where TElement : TopologyElementState;
ITopologyElementBuilder<TElement> TopologyElementByBrowseName<TElement>(
    QualifiedName browseName,
    NodeState? parent = null)
    where TElement : TopologyElementState;

CreateDeviceAsync performs four steps:

  1. Resolves the parent (default: Device Integration DeviceSet; subclasses override ResolveDefaultDeviceParent() — e.g. machinery managers can return the Machines folder).
  2. Uses Organizes for the well-known DI DeviceSet; explicit custom parents retain HasComponent.
  3. Fails fast if a child with the same browse name already exists (StatusCodes.BadBrowseNameDuplicated).
  4. Materialises the instance through the source-generated CreateInstanceOf<Type> factory (e.g. CreateInstanceOfDeviceType) so the device carries the type's mandatory children — for DeviceType the eight nameplate variables (Manufacturer, Model, HardwareRevision, SoftwareRevision, DeviceRevision, DeviceManual, SerialNumber, RevisionCounter) with correct DI-namespace BrowseNames — plus the type's HasInterface references. Because a browse name is supplied, the factory also rebases the whole subtree onto per-instance NodeIds in the server's application namespace (DiNodeManager.InstanceNamespaceIndex, the Local Server URI namespace), so multiple instances of the same type never collide on the TYPE NodeIds emitted by the generator and never mint application nodes in DI or other companion-spec namespaces. It then sets BrowseName/SymbolicName/DisplayName and stamps the TypeDefinitionId.
  5. Calls the real AsyncCustomNodeManager.AddPredefinedNodeAsync so subscription wiring, type-tree registration, and root-notifier propagation all happen exactly as for nodes loaded from a NodeSet2.

Machinery-aware subclasses can additionally reference managed machines from the OPC 40001 Machines entry point. DiNodeManager's helper adds an Organizes reference to the existing instance instead of re-parenting it, so the same machine remains organized by DeviceSet while also being browsable from Machines.

Fluent surface

IDeviceBuilder<TDevice>
    .WithIdentification(action<DeviceIdentificationData>)
    .WithIdentificationGroup(action<IFunctionalGroupBuilder>)
    .WithConfigurationGroup(action<IFunctionalGroupBuilder>)
    .WithMaintenanceGroup(action<IFunctionalGroupBuilder>)
    .WithDiagnosticsGroup(action<IFunctionalGroupBuilder>)
    .WithStatusGroup(action<IFunctionalGroupBuilder>)
    .WithOperationalGroup(action<IFunctionalGroupBuilder>)
    .WithStatisticsGroup(action<IFunctionalGroupBuilder>)
    .WithOperationCountersGroup(action<IFunctionalGroupBuilder>)
    .WithFunctionalGroup(QualifiedName name, action<IFunctionalGroupBuilder>)
    .ConnectsTo(NodeId other)
    .ConnectsToParent(NodeId parent)
    .Configure(action<TDevice, ISystemContext>)
    .WithDeviceHealth(DeviceHealthEnumeration)   // extension; requires TDevice : DeviceState

ITopologyElementBuilder<TElement> is the parallel surface for generated companion types that derive directly from TopologyElementType. It exposes only common topology operations: functional groups, ConnectsTo references, typed node access, and raw state configuration. The internal device-builder implementation reuses the same behavior without changing the existing public IDeviceBuilder<TDevice> contract. Component nameplates, support information, software update, lifetime indications, and DeviceHealth remain on their narrower component/device builders.

Identification properties

WithIdentification(action) populates the standard Device Integration nameplate properties on the device. The mutable DeviceIdentificationData record holds:

  • Manufacturer (LocalizedText, IsNull = unset)
  • ManufacturerUri (string?)
  • Model (LocalizedText, IsNull = unset)
  • HardwareRevision, SoftwareRevision, DeviceRevision, ProductCode, DeviceManual, DeviceClass, SerialNumber, ProductInstanceUri (string?)
  • RevisionCounter (int?)

Properties that exist as typed children on the device are updated in place. The eight mandatory nameplate properties are always present (materialised by CreateInstanceOfDeviceType), so setting them takes the in-place path. Optional nameplate properties (ManufacturerUri, ProductCode, ProductInstanceUri, DeviceClass) are created on demand via NodeState.AddProperty<T, VariantBuilder>, re-qualified into the DI namespace (never namespace 0), and registered with the manager.

DI companion-spec compliance

Devices created through CreateDeviceAsync are modelled to the DI companion spec: mandatory DeviceType children are present with DI-namespace BrowseNames, the type's HasInterface references are carried, and the software-update state-machine method children point at their in-type MethodDeclarationIds. The model is intentionally lean — OPC UA does not require optional interface members (IVendorNameplateType/ITagNameplateType/ISupportInfoType members such as AssetId, ProductCode, DeviceTypeImage, Documentation, ImageSet, ProtocolSupport) to be instantiated, so they are omitted unless the application adds them. A strict external compliance checker may still flag those optional members or report placeholder warnings for application-added HasComponent children (e.g. a custom Diagnostics functional group or the SoftwareUpdate facet); these are permitted omissions/extensions rather than modelling errors.

Functional groups

Common Device Integration functional groups have typed builder methods. Spec-defined groups keep their standard BrowseName namespace, for example Identification, Maintenance, and Operational in the DI namespace and Events in the Pumps namespace. Application-defined groups use the server instance namespace; the diagnostics helper follows that rule because the diagnostics group it creates is vendor-defined. Arbitrary group names go through WithFunctionalGroup(qualifiedName, action). Each call is idempotent: invoking the same accessor twice reuses the existing group. The order of operations inside the builder is:

  1. Create the FunctionalGroupState child (via TopologyElementState.AddIdentification or AddGroupIdentifier).
  2. Normalise BrowseName, SymbolicName, DisplayName, NodeId (via Context.NodeIdFactory) and TypeDefinitionId.
  3. Register the group with the manager via AddPredefinedNodeAsync.
  4. Hand the IFunctionalGroupBuilder to the configure delegate.
device.WithMaintenanceGroup(fg =>
{
    fg.Organizes(device.Manufacturer!.NodeId);
    fg.Node.WithProperty("LastMaintenanceDate", DateTime.UtcNow);
});

For vendor-specific groups, use the non-typed WithFunctionalGroup(QualifiedName, action) overload. The browse name's namespace index controls where the group lives; pass DiNodeManager.InstanceNamespaceIndex for application-defined groups. Reserve DI, Pumps, Machinery, or other companion-spec BrowseName namespaces for nodes that are defined by those specifications. The PumpDeviceIntegrationServer sample demonstrates this on Pump #2 to surface a custom Diagnostics folder:

pump.WithFunctionalGroup(
    new QualifiedName("Diagnostics", ctx.Manager.InstanceNamespaceIndex),
    fg => fg.Configure(node =>
        node.WithProperty("LastError", string.Empty)
            .WithProperty("ErrorCount", 0)
            .WithProperty("LastSelfTest", DateTime.UtcNow)));

Topology references

ConnectsTo(NodeId) adds a forward Opc.Ua.Di.ReferenceTypes.ConnectsTo reference; ConnectsToParent(NodeId) adds the inverse. Useful for declaring physical / logical topology relationships outside the hierarchical address-space tree.

Device health

WithDeviceHealth(DeviceHealthEnumeration) is an extension method constrained to TDevice : DeviceState (where the typed DeviceHealth child variable exists). Throws StatusCodes.BadInvalidState if the device was constructed without the DeviceHealth child — typically because the factory was p => new DeviceState(p) rather than the generator-produced CreateDeviceType factory. Callers can pre-populate the child via Configure((dev, ctx) => ...) to avoid the error.

Subclass support

Companion-spec managers (PumpNodeManager, machinery managers) inherit from DiNodeManager and gain the entire builder surface for free. They typically override ResolveDefaultDeviceParent() to return the companion-spec-specific container (Machines folder, etc.) and supply their own typed factories to CreateDeviceAsync<TPumpType>(...).

Device sub-type extensions

Three extension surfaces on top of IDeviceBuilder<TDevice> cover optional OPC 10000-100 features:

Software / Block / ConfigurableObject (§5.4 advanced sub-types)

DeviceBuilderTypeExtensions adds typed materialisation helpers for the §5.4 sub-types that are not provided by WithDeviceType itself:

SoftwareState           sw    = builder.AddSoftware(qn("Firmware"));
BlockState              blk   = builder.AddBlock(qn("InputBlock"));
ConfigurableObjectState cfg   = builder.AddConfigurableObject(qn("DriverFolder"));

Each helper creates a typed child under the device, stamps a manager-assigned NodeId via INodeIdFactory, sets the HasComponent reference, registers the child via AddPredefinedNodeAsync, and invokes an optional configure callback. The returned typed state is ready for further configuration through the standard NodeState APIs.

Lifetime indication (§10.6)

DeviceBuilderLifetimeExtensions.AddLifetimeIndication creates a LifetimeVariableState under the device with a LifetimeIndicationKind classifier covering all six §10.6 indication sub-types:

device.AddLifetimeIndication(
    qn("OperatingHours"),
    LifetimeIndicationKind.Time,
    startValue: 0.0);

device.AddLifetimeIndication(
    qn("PartsProduced"),
    LifetimeIndicationKind.NumberOfParts,
    startValue: 0.0);

The classifier enum maps directly to OPC 10000-100 ObjectType ids:

LifetimeIndicationKindOPC UA ObjectType
TimeTimeIndicationType
NumberOfPartsNumberOfPartsIndicationType
NumberOfUsagesNumberOfUsagesIndicationType
LengthLengthIndicationType
DiameterDiameterIndicationType
SubstanceVolumeSubstanceVolumeIndicationType

DeviceBuilderLifetimeExtensions.ResolveIndicationTypeId(kind, namespaceUris) resolves the matching NodeId at runtime when applications need to materialise the indication classifier object themselves.

Support info (§5.15)

DeviceBuilderSupportInfoExtensions.WithSupportInfo creates an ISupportInfoState child on the device (idempotent — re-uses the existing instance on subsequent calls) and yields it through a configure callback. The interface exposes DocumentationFiles / ImageSet / ProtocolSupport folder properties; consumers populate them by attaching FileState or BaseObjectState children through the standard NodeState API. File-backed children commonly use FileState wired to an IFileSystemProvider from src/Opc.Ua.Server/FileSystem.

device.WithSupportInfo(info =>
{
    info.Description = new LocalizedText("Support information for device 1");
    // attach FileState children for DocumentationFiles / ImageSet
    // / ProtocolSupport folders here, using IFileSystemProvider
    // for content backing.
});

Hosting integration

AddOpcUaDi() and ConfigureDevicesFor<TNodeManager>() plug the Device Integration (DI) library into the unified AddOpcUa() Microsoft.Extensions.DependencyInjection hosting pattern.

Server-side surface

Microsoft.Extensions.DependencyInjection.OpcUaServerDiBuilderExtensions adds three methods on IOpcUaServerBuilder:

IOpcUaServerBuilder AddOpcUaDi();

IOpcUaServerBuilder ConfigureDevicesFor<TNodeManager>(
    Action<IDiPostSetupContext> configure)
    where TNodeManager : DiNodeManager;

IOpcUaServerBuilder ConfigureDevicesFor<TNodeManager>(
    Func<IDiPostSetupContext, ValueTask> configure)
    where TNodeManager : DiNodeManager;

When to use AddOpcUaDi()

Call this when you want a plain Device Integration (DI) server without any companion-spec subclass. It registers the DiNodeManagerFactory so the hosted service stands up a pure DiNodeManager.

services.AddOpcUa()
    .AddServer(o => { ... })
    .AddOpcUaDi();

Do NOT call AddOpcUaDi() alongside a companion-spec factory that already loads OPC UA Device Integration (e.g. PumpNodeManagerFactory which loads Device Integration + Machinery + Pumps). The Device Integration namespace would be registered twice and the OPC UA server may reject the duplicate. AddOpcUaDi() throws on its second invocation to surface the misuse early.

ConfigureDevicesFor<TNodeManager>(action)

Registers a post-setup configurator targeted at a specific manager type. The runner invokes each matching delegate after:

  • the manager's LoadPredefinedNodesAsync has populated PredefinedNodes;
  • the manager's CreateAddressSpaceAsync base has wired up the type tree and root notifiers;
  • (for FluentNodeManagerBase subclasses) the user's Configure(builder) + builder.Seal() is complete.

Configurator-type matching follows Type.IsAssignableFrom. A delegate targeting DiNodeManager runs against every Device Integration-derived manager (including PumpNodeManager); a delegate targeting PumpNodeManager will NOT run against a plain DiNodeManager.

Multiple ConfigureDevicesFor<T> calls accumulate and run in registration order. Exception semantics are fail-fast: any exception thrown by a configurator aborts hosted-server startup with a diagnostic that identifies the failing index and target type.

Context surface

The configurator receives an IDiPostSetupContext:

public interface IDiPostSetupContext
{
    DiNodeManager Manager { get; }
    CancellationToken CancellationToken { get; }
    T GetRequiredService<T>() where T : notnull;

    ValueTask<IDeviceBuilder<DeviceState>> CreateDeviceAsync(...);
    ValueTask<IDeviceBuilder<TDevice>> CreateDeviceAsync<TDevice>(...) where TDevice : ComponentState;
    IDeviceBuilder<TDevice> Device<TDevice>(NodeId nodeId) where TDevice : ComponentState;
    IDeviceBuilder<TDevice> DeviceByBrowseName<TDevice>(QualifiedName name, NodeState? parent = null)
        where TDevice : ComponentState;
    ITopologyElementBuilder<TElement> TopologyElement<TElement>(NodeId nodeId)
        where TElement : TopologyElementState;
    ITopologyElementBuilder<TElement> TopologyElementByBrowseName<TElement>(
        QualifiedName name,
        NodeState? parent = null)
        where TElement : TopologyElementState;
}

The context does not expose a raw IServiceProvider. Use GetRequiredService<T>() to resolve application services (intentionally narrow to discourage service-locator anti-patterns and lifetime traps).

Architecture

ComponentLifetimeWhere
IDiPostSetupRunnerSingleton (registered by AddOpcUaDi/ConfigureDevicesFor)Opc.Ua.Di.Server.Hosting
IDiPostSetupConfiguratorSingleton (one per ConfigureDevicesFor call)Opc.Ua.Di.Server.Hosting
DiNodeManagerFactory / PumpNodeManagerFactorySingleton (.NET-DI-aware ctor injects runner)server / app
DiNodeManager / PumpNodeManagerPer-server startup (factory passes runner)app

The runner is injected into the manager via the factory. The base DiNodeManager auto-invokes it at the end of its own CreateAddressSpaceAsync for every concrete subclass:

  • The base DiNodeManager.CreateAddressSpaceAsync calls base.CreateAddressSpaceAsync → OnAddressSpaceReadyAsync → PostSetupRunner.RunAsync(this, ct) in that order.
  • Subclasses (e.g. PumpNodeManager) override the protected virtual ValueTask OnAddressSpaceReadyAsync(...) hook to materialise instances + drive the fluent INodeManagerBuilder. The runner fires automatically once OnAddressSpaceReadyAsync returns — subclasses do not need to call PostSetupRunner.RunAsync themselves.

Runtime conformance advertisement

DiNodeManager implements IConformanceContributor, so the hosted server publishes the DI facets and conformance units that are actually wired at startup. The server merges these contributions into Server/ServerCapabilities/ServerProfileArray and Server/ServerCapabilities/ConformanceUnits alongside the base server profiles.

The current gating is implementation-derived:

Runtime conditionServer profile URIConformance units
DI DeviceSet existshttp://opcfoundation.org/UA-Profile/DI/Server/DeviceIntegrationHostDI DeviceTopology, DI Offline
A LockingServicesState has InitLock, RenewLock, or ExitLock wiredhttp://opcfoundation.org/UA-Profile/DI/Server/LockingDI Locking
The same lock service also wires BreakLocksame Locking profileDI BreakLocking
Any software-update loading mode is recordedhttp://opcfoundation.org/UA-Profile/DI/Server/SoftwareUpdateBaseDI SU Software Update, DI SU PrepareForUpdate, DI SU Resume Update
SoftwareLoadingMode.Packagehttp://opcfoundation.org/UA-Profile/DI/Server/FileSystemLoadingDI SU FileSystem Loading, DI SU Installation for File System
SoftwareLoadingMode.Directhttp://opcfoundation.org/UA-Profile/DI/Server/DirectLoadingDI SU DirectLoading, DI SU UpdateStatus
SoftwareLoadingMode.Cachedhttp://opcfoundation.org/UA-Profile/DI/Server/CachedLoadingDI SU CachedLoading, DI SU Installation for Cached Loading, DI SU UpdateStatus

Client-side surface

Microsoft.Extensions.DependencyInjection.OpcUaClientDiBuilderExtensions adds a single extension method on IOpcUaClientBuilder:

IOpcUaClientBuilder AddOpcUaDi();

This registers four .NET-DI-friendly services that wrap the lazy ManagedSession accessor produced by AddClient(...):

  • IDiDiscoveryService — recursive device discovery from the Objects folder; streams DeviceEntry records as IAsyncEnumerable<DeviceEntry> so callers can begin processing before the browse completes.
  • Func<NodeId, CancellationToken, ValueTask<DiDeviceClient>> — validates a device NodeId and returns a typed client.
  • Func<NodeId, CancellationToken, ValueTask<DiLockClient>> — client wrapper for LockingServicesType.InitLock / RenewLock / ExitLock / BreakLock.
  • Func<CancellationToken, ValueTask<DiTopologyClient>> — topology browser for the Device Integration well-known folders.
  • Func<NodeId, CancellationToken, ValueTask<SoftwareUpdateClient>> — software-version reader for a SoftwareUpdate instance.

Requires AddClient(...) to be called first — the extension throws InvalidOperationException if the managed-session accessor is missing when one of the factories is resolved.

Lock service

The lock service implements the OPC 10000-100 §10.5 locking facet. It tracks ownership of every TopologyElementType.Lock instance in the address space, enforces configurable timeouts, releases locks automatically when the owning session closes, and exposes the four spec-defined methods through the typed LockingServicesState proxy.

Components

TypePurpose
ILockServiceApplication-facing facade: InitLock, RenewLock, ExitLock, BreakLock, GetState. Thread-safe.
LockStateSnapshot record (Locked, LockingClient, LockingUser, RemainingLockTimeSeconds).
LockStatusOPC 10000-100 status-code constants.
DefaultLockServiceDefault in-memory implementation backed by a ConcurrentDictionary.
LockingServicesExtensions.BindToLockServiceWires the four generated *MethodState.OnCall handlers on a LockingServicesState instance through an ILockService.

Namespaces: Opc.Ua.Di.Server.Locking.

Status codes

Following OPC 10000-100 §10.5:

ConstantValueReturned from
LockStatus.Ok0All methods (success)
LockStatus.AlreadyLocked1InitLock only
LockStatus.CouldNotLock2InitLock only
LockStatus.NotLocked1RenewLock / ExitLock / BreakLock
LockStatus.WrongClient2RenewLock / ExitLock

Default lock service

var lockService = new DefaultLockService(
    lockDuration: TimeSpan.FromMinutes(5),   // optional, defaults to 5 min
    timeProvider: TimeProvider.System);       // optional, for tests

// Hook session-close so locks held by a disconnecting session are
// released automatically.
lockService.AttachToSessionManager(server.SessionManager);

Lock ownership is keyed by ServerSystemContext.SessionId. When the service is invoked from a test (SystemContext rather than ServerSystemContext), it falls back to a synthetic session id derived from ISystemContext.UserId so unit tests can still distinguish callers.

Binding to a LockingServicesState

The Device Integration spec defines a Lock child on every TopologyElementType that implements four method invocations. Wire them through your service:

LockingServicesState lockNode = device.Lock!;
lockNode.BindToLockService(elementId: device.NodeId, service: lockService);

BindToLockService reads lockNode.InitLock, RenewLock, ExitLock, BreakLock and replaces their OnCall handlers with delegates that route into the ILockService. The elementId argument keys the service's internal dictionary — typically the topology element's own NodeId so two different devices can hold independent locks.

End-to-end flow

  1. Client calls InitLock(context: "tag") on a device's Lock.
  2. The method's OnCall runs the bound ILockService.InitLock, which checks the per-device record:
    • If unlocked / expired → record (SessionId, "tag", UserId, now + duration), return Ok (0).
    • If already locked by another session → return AlreadyLocked (1).
  3. RenewLock (same session) extends the expiry timestamp; from a different session it returns WrongClient (2).
  4. ExitLock removes the record (subject to ownership check).
  5. BreakLock removes the record regardless of ownership; intended for administrative recovery.
  6. If the owning session closes (server-emitted SessionClosing event), the DefaultLockService walks its records and releases anything that was held by that session.

Hosting

Register the service as a singleton through standard Microsoft.Extensions.DependencyInjection:

services.AddSingleton<ILockService, DefaultLockService>();

Then attach the session-close hook from inside a ConfigureDevicesFor<TNodeManager> configurator once the server's SessionManager is available:

.ConfigureDevicesFor<DiNodeManager>(ctx =>
{
    ILockService svc = ctx.GetRequiredService<ILockService>();
    if (svc is DefaultLockService defaultSvc)
    {
        defaultSvc.AttachToSessionManager(ctx.Manager.Server.SessionManager);
    }
    foreach (DeviceState device in ctx.Manager.PredefinedNodes
        .Values.OfType<DeviceState>())
    {
        device.Lock?.BindToLockService(device.NodeId, svc);
    }
});

Software update

The software-update facet exposes a package-storage layer plus a minimal client helper for OPC 10000-100 §10.3. The full state-machine wiring (PrepareForUpdate / Installation / PowerCycle / Confirmation) remains application-specific — the source generator emits typed *StateMachineState proxies that applications drive directly when needed.

Server-side: package store

The store is an application-facing abstraction over the binary artifacts that the Device Integration software-update facet exposes. Two implementations ship in Opc.Ua.Di.Server.SoftwareUpdate:

TypeBackingUse case
MemoryPackageStoreConcurrentDictionary<string, byte[]>Unit tests; small fixtures.
FileSystemPackageStoreOpc.Ua.Server.FileSystem.IFileSystemProviderProduction — reuses the same provider model used by the server's FileSystem mount.

Surface

public interface ISoftwarePackageStore
{
    IAsyncEnumerable<SoftwarePackage> ListAsync(CancellationToken ct = default);
    ValueTask<SoftwarePackage?> GetAsync(string packageId, CancellationToken ct = default);
    ValueTask<bool> ExistsAsync(string packageId, CancellationToken ct = default);
    ValueTask<Stream> OpenReadAsync(string packageId, CancellationToken ct = default);
    ValueTask<SoftwarePackage> AddAsync(SoftwarePackage metadata, Stream payload, CancellationToken ct = default);
    ValueTask<bool> DeleteAsync(string packageId, CancellationToken ct = default);
}

SoftwarePackage is a record carrying Id, Version, Vendor, Description, SizeBytes, CreatedAt, Hash. Both stores recompute SizeBytes and CreatedAt during AddAsync so callers can pass zeros / default in the input metadata.

FileSystemPackageStore layout

Each package is stored as a directory containing two files:

{root}/
    {package-id}/
        payload.bin       ← the binary firmware/installer
        metadata.json     ← the SoftwarePackage record as JSON

JSON serialization uses a source-generated System.Text.Json context (SoftwarePackageJsonContext) so the store is AOT-friendly.

Package IDs must NOT contain / or \ — the store validates and throws ArgumentException to prevent path traversal.

Composing with IFileSystemProvider

IFileSystemProvider fs = new PhysicalFileSystemProvider(
    rootDirectory: "/var/lib/myserver/packages",
    mountName: "Packages",
    isWritable: true);

ISoftwarePackageStore store = new FileSystemPackageStore(
    provider: fs,
    rootPath: "/SoftwarePackages");

The same IFileSystemProvider instance can also be mounted into the server's address space via FileSystemNodeManager — both paths share the on-disk layout.

Hosting

Register the store as a singleton and seed it from a ConfigureDevicesFor configurator:

builder.Services.AddSingleton<ISoftwarePackageStore, MemoryPackageStore>();
builder.Services
    .AddOpcUa()
    .AddServer(o => { ... })
    .AddNodeManager<MyNodeManagerFactory>()
    .ConfigureDevicesFor<MyNodeManager>(async ctx =>
    {
        ISoftwarePackageStore store = ctx.GetRequiredService<ISoftwarePackageStore>();
        await store.AddAsync(
            new SoftwarePackage(
                Id: "firmware-1.0.0",
                Version: "1.0.0",
                Vendor: "Acme",
                Description: "Initial firmware",
                SizeBytes: 0,
                CreatedAt: default,
                Hash: string.Empty),
            new FileStream("/path/to/firmware.bin", FileMode.Open));
    });

Client-side software update

SoftwareUpdateClient exposes a minimal read-only surface:

public sealed class SoftwareUpdateClient
{
    public SoftwareUpdateClient(ISession session, NodeId softwareUpdateNodeId, ITelemetryContext telemetry);
    public ValueTask<string> ReadSoftwareVersionAsync(CancellationToken ct = default);
}

Method-level invocation (Loading, Installation, ...) is performed through the typed *MethodStateClient proxies emitted by the source generator for the Device Integration model. The client integration registers the factory Func<NodeId, CancellationToken, ValueTask<SoftwareUpdateClient>> via services.AddOpcUa().AddClient(...).AddOpcUaDi().

Client helpers

Beyond DiDeviceClient and DiDiscoveryClient, the Opc.Ua.Di.Client library ships three typed client wrappers that compose the standard OPC UA Session surface.

HelperPurpose
DiLockClientWraps the four LockingServicesType methods.
DiTopologyClientBrowses DeviceSet, NetworkSet, DeviceTopology.
SoftwareUpdateClientReads the software-version property of a SoftwareUpdateType instance.

All three live in Opc.Ua.Di.Client and are registered automatically when applications call services.AddOpcUa().AddClient(...).AddOpcUaDi() on the client-side builder.

DiLockClient

public sealed class DiLockClient
{
    public DiLockClient(ISession session, NodeId lockNodeId, ITelemetryContext telemetry);
    public ValueTask<int> InitLockAsync(string context, CancellationToken ct = default);
    public ValueTask<int> RenewLockAsync(CancellationToken ct = default);
    public ValueTask<int> ExitLockAsync(CancellationToken ct = default);
    public ValueTask<int> BreakLockAsync(CancellationToken ct = default);
}

Each method invokes the corresponding LockingServicesType.{Method} generated NodeId on the server and returns the integer status code (see the LockStatus table for the OPC spec values).

The constructor takes the NodeId of the Lock instance — typically the device.Lock child, not the device itself. Resolve it via Session.TranslateBrowsePathsToNodeIdsAsync or by browsing the device's HasComponent references for a child named "Lock".

DiLockClient lockClient = new(session, lockNodeId, telemetry);
int status = await lockClient.InitLockAsync("client-tag");
if (status == LockStatus.Ok)
{
    try
    {
        // Do work that requires exclusive access.
    }
    finally
    {
        await lockClient.ExitLockAsync();
    }
}

DiTopologyClient

public sealed class DiTopologyClient
{
    public DiTopologyClient(ISession session, ITelemetryContext telemetry);
    public NodeId DeviceSetId { get; }
    public NodeId NetworkSetId { get; }
    public NodeId DeviceTopologyId { get; }

    public IAsyncEnumerable<TopologyEntry> EnumerateDevicesAsync(CancellationToken ct = default);
    public IAsyncEnumerable<TopologyEntry> EnumerateNetworksAsync(CancellationToken ct = default);
    public IAsyncEnumerable<TopologyEntry> EnumerateChildrenAsync(NodeId parentNodeId, CancellationToken ct = default);
}

public sealed record TopologyEntry(
    NodeId NodeId,
    string DisplayName,
    NodeId TypeDefinitionId,
    QualifiedName BrowseName);

EnumerateDevicesAsync and EnumerateNetworksAsync browse the hierarchical references of DeviceSet and NetworkSet and return the direct children that are Objects. EnumerateChildrenAsync provides the same surface for arbitrary nodes — useful when walking the DeviceTopology tree.

DiTopologyClient topology = new(session, telemetry);
await foreach (TopologyEntry device in topology.EnumerateDevicesAsync())
{
    Console.WriteLine($"{device.BrowseName}: {device.DisplayName}");
}

Hosting registration

When services.AddOpcUa().AddClient(o => { ... }).AddOpcUaDi() is called, the following factories are registered as singletons:

Func<NodeId, CancellationToken, ValueTask<DiDeviceClient>>
Func<NodeId, CancellationToken, ValueTask<DiLockClient>>
Func<CancellationToken, ValueTask<DiTopologyClient>>
Func<NodeId, CancellationToken, ValueTask<SoftwareUpdateClient>>
IDiDiscoveryService

Inject the factory you need into your application services; the factory opens (or reuses) the lazy ManagedSession on first call.

public sealed class MyMonitor(
    Func<CancellationToken, ValueTask<DiTopologyClient>> topologyFactory,
    Func<NodeId, CancellationToken, ValueTask<DiDeviceClient>> deviceFactory,
    Func<NodeId, CancellationToken, ValueTask<DiLockClient>> lockFactory)
{
    public async Task ScanAsync(CancellationToken ct)
    {
        DiTopologyClient topo = await topologyFactory(ct);
        await foreach (TopologyEntry e in topo.EnumerateDevicesAsync(ct))
        {
            DiDeviceClient dev = await deviceFactory(e.NodeId, ct);
            DeviceIdentification id = await dev.ReadIdentificationAsync(ct);
            // ...
        }
    }
}

What is supported (OPC 10000-100)

References are to the OPC 10000-100 (DI v1.05) specification sections.

Foundation — nameplates and topology elements

  • TopologyElementType (§5.2) — abstract base exposed through ITopologyElementBuilder<TElement>.
  • IVendorNameplateType (§5.10) — Manufacturer, Model, SerialNumber, HardwareRevision, SoftwareRevision, DeviceRevision, DeviceManual, DeviceClass, ProductInstanceUri, ProductCode. Populated by IDeviceBuilder.WithIdentification(...).
  • ITagNameplateType (§5.11) — AssetId, ComponentName, DeviceRevision. Populated by the same builder.
  • IDeviceHealthType (§5.12) — DeviceHealth enum plus the four NAMUR alarm references.
  • IAssetLocationIndicationType (§5.13) — StartLocationIndication / StopLocationIndication methods.
  • IOperationCounterType (§5.14) — PowerOnDuration, OperationDuration, EstimatedReturnedOperationDuration, EstimatedReturnedPowerOnDuration.

Device tree

  • ComponentType (§5.3) — abstract; materialised via IDeviceBuilder.
  • DeviceType (§5.4) — IDeviceBuilder.WithDeviceType<TDeviceState>(factory).
  • SoftwareType, BlockType, ConfigurableObjectType (§5.4 advanced sub-types) — IDeviceBuilder.AddSoftware, AddBlock, AddConfigurableObject.

Topology references

  • ConnectsTo (§5.6.2) — ITopologyElementBuilder.ConnectsTo(other).
  • ConnectsToParent (§5.6.3) — ITopologyElementBuilder.ConnectsToParent(other).
  • IsOnline (§5.6.4) — exposed for online-component wiring.
  • UpdateParent, CanUpdate (§5.6.5–§5.6.6) — used by software update.

Topology containers

  • DeviceSet (§6.2) — well-known instance, auto-created by DiNodeManager under ObjectsFolder; IDeviceBuilder parents devices here by default.
  • NetworkSet (§6.3) — well-known instance.
  • DeviceTopology (§6.4) — well-known instance; topology references attach here.
  • NetworkType, ConnectionPointType, ProtocolType (§6.5–§6.7).

Functional groups (§5.7)

All eight well-known Device Integration functional groups are exposed through typed methods on ITopologyElementBuilder; device builders inherit the same surface:

  • Identification, Configuration, Maintenance, Diagnostics, Statistics, Status, Operational, OperationCounters.

Custom groups go through WithFunctionalGroup(qualifiedName, action).

Lock service (§10.5)

  • LockingServicesType and the four method types (InitLockMethodType, RenewLockMethodType, ExitLockMethodType, BreakLockMethodType) — wired through ILockService and DefaultLockService (session ownership, configurable timeout, automatic cleanup on session close).

Software update (§10.3)

  • SoftwareUpdateType — orchestrates the loading + state-machine wiring.
  • SoftwareLoadingType, PackageLoadingType (§10.3.4) — abstract bases.
  • DirectLoadingType, CachedLoadingType, FileSystemLoadingType (§10.3.4) — the three loading variants.
  • SoftwareVersionType (§10.3.6) — Manufacturer, ProductInstanceUri, SoftwareRevision, PatchIdentifiers, ReleaseDate, ChangeLog, Hash.
  • PrepareForUpdateStateMachineType (§10.3.7), InstallationStateMachineType (§10.3.8), PowerCycleStateMachineType (§10.3.9), ConfirmationStateMachineType (§10.3.10) — generated proxies driven by the application.
  • Storage abstraction: ISoftwarePackageStore with MemoryPackageStore and FileSystemPackageStore implementations.

Support info & lifetime indication

  • ISupportInfoType (§5.15) — IDeviceBuilder.WithSupportInfo(configure). Backing folders DocumentationFiles / ImageSet / ProtocolSupport accept FileState / BaseObjectState children; file content commonly backed by IFileSystemProvider.
  • LifetimeVariableType + 6 indication sub-types (§10.6) — IDeviceBuilder.AddLifetimeIndication(kind, …). Classifier kinds: Time, NumberOfParts, NumberOfUsages, Length, Diameter, SubstanceVolume.

NAMUR alarms (§10.2)

  • DeviceHealthDiagnosticAlarmType (abstract) and the four concrete alarm types (FailureAlarmType, CheckFunctionAlarmType, OffSpecAlarmType, MaintenanceRequiredAlarmType) — generated proxies wired via the fluent IAlarmBuilder<TState> + ActivatesAlarm patterns from src/Opc.Ua.Server/Fluent.

DataTypes & VariableTypes

All Device Integration DataTypes (DeviceHealthEnumeration, SoftwareClass, LocationIndicationType, SoftwareVersionFileType, UpdateBehavior, FetchResultDataType, TransferResultErrorDataType, TransferResultDataDataType, ParameterResultDataType) ship as source-generated types in the Opc.Ua.Di model library.

Not yet implemented

  • SoftwareFolderType (§10.3.5) — multi-version repository.
  • TransferServicesType (§10.4) — parameter set transfer.

See also