UA-.NETStandard/docs/NodeSetExport.md

Client-based NodeSet Export

The OPC UA .NET Standard client library can export a server's address space to a NodeSet2 XML file. Use the export to document or analyze an address space, or to import it into another system.

Contents

• Overview
• Usage
  • Basic Example
  • Using the Console Reference Client
• Supported Node Types
• Features
  • Node Attributes Exported
  • Namespace Handling
  • References
• Limitations
  • MCP server export paths
• API Reference
  • CoreClientUtils.ExportNodesToNodeSet2
  • ClientSamples.ExportNodesToNodeSet2
• Related Topics
• Examples
• See Also

Overview

The client-based NodeSet export feature enables:

• Browsing and collecting nodes from an OPC UA server
• Converting client-side node representations (INode) to server-side representations (NodeState)
• Exporting nodes to standard NodeSet2 XML format
• Round-tripping: exported NodeSets can be imported using existing import functionality

Usage

Basic Example

The following helper exports the direct children of the Server node from an existing session. The caller owns the session and output stream. For connection and trust setup, see Getting started; for recursive export, see Using the Console Reference Client.

using System;
using System.Collections.Generic;
using System.IO;
using System.Threading;
using System.Threading.Tasks;
using Opc.Ua;
using Opc.Ua.Client;

/// <summary>
/// Exports nodes browsed through an existing client session.
/// </summary>
public static class NodeSetExportExample
{
    /// <summary>
    /// Exports the Server node's direct hierarchical children to NodeSet2 XML.
    /// </summary>
    public static async Task ExportServerChildrenAsync(
        ISession session,
        ITelemetryContext telemetry,
        Stream output,
        CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(session);
        ArgumentNullException.ThrowIfNull(telemetry);
        ArgumentNullException.ThrowIfNull(output);

        var browser = new Browser(session)
        {
            BrowseDirection = BrowseDirection.Forward,
            ReferenceTypeId = ReferenceTypeIds.HierarchicalReferences,
            IncludeSubtypes = true,
            NodeClassMask = 0
        };

        ArrayOf<ReferenceDescription> references =
            await browser.BrowseAsync(ObjectIds.Server, ct).ConfigureAwait(false);
        var nodes = new List<INode>();
        for (int i = 0; i < references.Count; i++)
        {
            INode? node = await session.NodeCache.FindAsync(references[i].NodeId, ct)
                .ConfigureAwait(false);
            if (node is not null)
            {
                nodes.Add(node);
            }
        }

        ct.ThrowIfCancellationRequested();
        var systemContext = new SystemContext(telemetry)
        {
            NamespaceUris = session.NamespaceUris,
            ServerUris = session.ServerUris
        };
        CoreClientUtils.ExportNodesToNodeSet2(systemContext, nodes, output);
    }
}

Browsing and node reads are asynchronous; the existing export helper writes the collected nodes to XML synchronously.

Using the Console Reference Client

The console reference client (ClientSamples class) includes a helper method for exporting nodes:

// Browse and collect nodes using the existing helper
IList<INode> nodes = await clientSamples.FetchAllNodesNodeCacheAsync(
    uaClient,
    ObjectIds.ObjectsFolder,  // Starting node
    fetchTree: true,           // Recursively browse the tree
    addRootNode: true,         // Include the root node
    filterUATypes: true,       // Filter out namespace 0 nodes
    clearNodeCache: true
);

// Export to NodeSet2 file
clientSamples.ExportNodesToNodeSet2(session, nodes, "address-space.xml");

Supported Node Types

The export functionality supports all standard OPC UA node types:

• Object nodes - Objects and their properties
• Variable nodes - Variables with their values and data types
• Method nodes - Methods with their executable status
• ObjectType nodes - Object type definitions
• VariableType nodes - Variable type definitions
• DataType nodes - Data type definitions
• ReferenceType nodes - Reference type definitions
• View nodes - View definitions

Features

Node Attributes Exported

For each node, the following attributes are exported (where applicable):

• NodeId
• BrowseName
• DisplayName
• Description
• WriteMask and UserWriteMask
• References to other nodes
• Type-specific attributes (e.g., DataType for variables, EventNotifier for objects)

Namespace Handling

The export functionality handles:

• Multiple namespaces
• Namespace URIs are included in the exported NodeSet
• NodeIds are mapped to namespace indices

References

All references between nodes are preserved in the export, including:

• Hierarchical references (e.g., HasComponent, HasProperty)
• Type definition references (e.g., HasTypeDefinition)
• Organizing references
• Custom reference types

Limitations

• The export creates a snapshot of the address space at the time of browsing
• Dynamic values are captured as they exist at export time
• Not all server-specific internal state may be preserved
• Complex type definitions require the complex types system to be loaded

MCP server export paths

The MCP server's ExportNodeSet tools use a separate, per-user export root. OpcUaMcpOptions.NodeSetExportRoot takes precedence over the OPCUA_MCP_EXPORT_ROOT environment variable, followed by the per-user default. Both relative and absolute output paths must remain inside that root. The MCP writer rejects existing files, filesystem reparse points and unsafe Unix directory permissions, and creates new output files exclusively rather than truncating an existing destination.

Configure the root so no untrusted local account can replace its path components. The managed path checks do not pin directory handles across the entire operation, so a concurrently writable shared directory is not a supported export root. Existing destinations must be moved or removed explicitly before exporting again.

API Reference

CoreClientUtils.ExportNodesToNodeSet2

public static void ExportNodesToNodeSet2(
    ISystemContext context,
    IList<INode> nodes,
    Stream outputStream)

Parameters:

• context - System context containing namespace and server URI information
• nodes - List of nodes to export
• outputStream - Stream to write the NodeSet2 XML to

Exceptions:

• ArgumentNullException - If any parameter is null

ClientSamples.ExportNodesToNodeSet2

public void ExportNodesToNodeSet2(
    ISession session,
    IList<INode> nodes,
    string filePath)

Parameters:

• session - Active session to use for namespace information
• nodes - List of nodes to export
• filePath - Path where the NodeSet2 XML file will be saved

Related Topics

• Working with ComplexTypes
• Console Reference Client
• OPC UA NodeSet2 XML Schema specification

Examples

For complete examples of using the NodeSet export functionality, see:

• tests/Opc.Ua.Client.Tests/NodeSetExportTest.cs - Unit tests demonstrating various export scenarios
• samples/Reference/ConsoleReferenceClient/ClientSamples.cs - Integration in the reference client

See Also

• OPC UA Specification Part 6 - Mappings
• NodeSet2 XML Schema: src/Opc.Ua.Core/Schema/UANodeSet.xsd