Pushing Dynamic ArrayList Variables into OPC UA Server Nodes

Overview

Developers building an OPC UA server with the Unified Automation .NET SDK frequently encounter a problem when the underlying control system exposes data as a System.Collections.ArrayList of indeterminate length. Unlike scalar tags, a variable backed by a dynamic list must be modeled so that an OPC UA client can read it correctly even when the number of elements grows or shrinks between notifications. The solution combines three configuration items on the variable node (ValueRank, ArrayDimensions, and the underlying DataType) with the correct override of BaseNodeManager.Write for the ExternalPush pattern.

This reference documents the array semantics defined in the OPC UA specification, the role of the IIOManager / BaseNodeManager plumbing, and the exact sequence required to push an unknown-length array from the embedded system into the address space.

Prerequisites

1. Unified Automation UaSdkNetServer bundle (C++/.NET Server SDK) installed and licensed.
2. UaModeler for address space design, or an equivalent code-first builder.
3. Visual Studio 2019 or later with .NET Framework 4.7.2 / .NET 6.0+ reference assemblies.
4. Familiarity with OPC UA Part 3 address space concepts (variable nodes, data types, value rank). See the OPC UA Part 3 – Address Space specification.
5. A working OPC UA client such as UaExpert for verification.

OPC UA Array Semantics: ValueRank and ArrayDimensions

The OPC UA Part 3 specification defines the ValueRank attribute to describe whether a variable holds a scalar or an n-dimensional array. The relevant constants for dynamic arrays are summarized below.

The ArrayDimensions attribute is a UInt32[] that declares the length of each dimension. A value of 0 for an entry signals "unknown length" to the client. For an ArrayList whose size is determined at runtime, the correct configuration is:

• ValueRank = 1 (one-dimensional array)
• ArrayDimensions = { 0 } (length unknown, dynamic)
• DataType = the underlying scalar type (e.g. Int32, Double, String), not a complex type
• Value attribute starts as null or an empty array

Understanding the BaseNodeManager.Write Signature

When the underlying system uses the ExternalPush pattern (the I/O is event-driven rather than sampled), the SDK hands every incoming client write, and every internal server-side write, to the user-defined BaseNodeManager subclass. The override signature is:

public override ServiceResult Write(
    RequestContext    context,
    NodeAttributeHandle nodeHandle,
    NumericRange      indexRange,
    DataValue         value,
    TypeInfo          typeInfo)

Identifying the Target Node via NodeAttributeHandle

The NodeAttributeHandle returned by the SDK is a generic wrapper that hides the internal NodeId mapping. To resolve it back to your application object, store the original VariableNode (or a thin wrapper) inside the handle at the time of CreateNode:

protected override NodeAttributeHandle CreateNode(
    RequestContext context,
    NodeId nodeId,
    NodeClass nodeClass,
    QualifiedName browseName,
    ExtensibleObject baseAttribute,
    NodeAttributesDataItem[] dataItems,
    out ServiceResult result)
{
    result = ServiceResult.Good;
    if (nodeClass == NodeClass.Variable &&
        _dynamicArrays.TryGetValue(nodeId, out var dyn))
    {
        return new DynamicArrayHandle(nodeId, dyn);
    }
    return base.CreateNode(context, nodeId, nodeClass,
                           browseName, baseAttribute,
                           dataItems, out result);
}

Inside Write the resolution looks like:

if (nodeHandle is DynamicArrayHandle dah)
{
    VariableNode target = dah.Variable;
    // target.DataType        -> BuiltInType.Int32
    // target.ValueRank       == ValueRanks.OneDimension
    // target.ArrayDimensions == { 0 }
}

Step-by-Step: Pushing an ArrayList with ExternalPush

The following procedure wires the embedded system event OnDataReady(ArrayList payload) to the OPC UA variable.

Step 1 – Model the variable in UaModeler

1. Add a Variable node under your ObjectType.
2. Set DataType to the scalar (e.g. Int32).
3. Set ValueRank to OneDimension (numeric value 1).
4. Set ArrayDimensions to a single-element array containing 0.
5. Compile to generate the C# boilerplate.

Step 2 – Register the node with the IIOManager

During server start-up, add the variable to your BaseNodeManager subclass so that reads and writes route through your override:

var v = new VariableNode
{
    NodeId    = new NodeId("Demo.ArrayListVar", ns),
    BrowseName= new QualifiedName("ArrayListVar", ns),
    DataType  = new NodeId(DataTypes.Int32),
    ValueRank = ValueRanks.OneDimension,
    ArrayDimensions = new uint[] { 0 },
    Value    = new DataValue(new int[0])
};
_manager.AddNode(v);
_dynamicArrays[v.NodeId] = v;

Step 3 – Override BaseNodeManager.Write

public override ServiceResult Write(
    RequestContext context,
    NodeAttributeHandle nodeHandle,
    NumericRange indexRange,
    DataValue value,
    TypeInfo typeInfo)
{
    if (!(nodeHandle is DynamicArrayHandle dah))
        return base.Write(context, nodeHandle, indexRange, value, typeInfo);

    // 1. Validate type descriptor.
    if (typeInfo == null ||
        typeInfo.ValueRank != ValueRanks.OneDimension ||
        typeInfo.BuiltInType != BuiltInType.Int32)
        return StatusCodes.BadTypeMismatch;

    // 2. Convert ArrayList to Int32[].
    ArrayList payload = value.Value as ArrayList;
    int[] native = payload == null
        ? (int[])value.Value
        : payload.Cast<int>().ToArray();

    // 3. Apply partial update if indexRange was supplied.
    int[] working = (int[])dah.Variable.Value.Value;
    if (indexRange != NumericRange.Empty)
    {
        // NumericRange.Begin..NumericRange.End is zero-based inclusive
        int dst = indexRange.Begin;
        int len = indexRange.End - indexRange.Begin + 1;
        Array.Copy(native, 0, working, dst, Math.Min(len, native.Length));
        native = working;
    }

    // 4. Commit & notify.
    dah.Variable.Value = new DataValue(new Variant(native));
    dah.Variable.ClearChangeMasks(context, true);
    ReportValueChanged(dah.Variable);

    return ServiceResult.Good;
}

Step 4 – Override BaseNodeManager.Read

The Read mirror must hand the cached array back to clients with the correct TypeInfo:

public override ServiceResult Read(
    RequestContext context,
    NodeAttributeHandle nodeHandle,
    NumericRange indexRange,
    TimestampsToReturn timestampsToReturn,
    out DataValue value,
    out TypeInfo typeInfo)
{
    value    = null;
    typeInfo = null;

    if (!(nodeHandle is DynamicArrayHandle dah))
        return base.Read(context, nodeHandle, indexRange,
                         timestampsToReturn, out value, out typeInfo);

    int[] native = (int[])dah.Variable.Value.Value;
    value = new DataValue(new Variant(native));
    typeInfo = new TypeInfo(BuiltInType.Int32, ValueRanks.OneDimension);
    return ServiceResult.Good;
}

Step 5 – Push from the underlying system

The event handler is now a one-liner. Because the value is applied directly through Write, monitored items on the node fire automatically – the hallmark of the ExternalPush pattern:

private void Plc_OnDataReady(object sender, ArrayList payload)
{
    var dv = new DataValue(new Variant(payload.ToArray(typeof(int))));
    Write(RequestContext.Internal,
          _handleForArrayListVar,
          NumericRange.Empty,
          dv,
          new TypeInfo(BuiltInType.Int32, ValueRanks.OneDimension));
}

Verification

1. Start the server, then connect UaExpert to opc.tcp://localhost:48030.
2. Drag the Demo.ArrayListVar node into the Data Access view.
3. Confirm that the ValueRank column reads 1 and ArrayDimensions reads {0} in the Attributes window.
4. Trigger a 5-element push from the embedded system; UaExpert should show 5 values.
5. Push a 12-element payload; verify the client redraws with 12 values without re-subscribing.
6. Subscribe with a MonitoredItem at sampling interval 0 (reporting on data change); confirm that every push generates exactly one notification – not one per element.

For end-to-end validation, see the array acquisition patterns described in the Rockwell Automation OPC UA white paper on data acquisition of arrays.

Troubleshooting Matrix

Notes on Alternative Implementations

If the embedded system exposes a fixed-size array but only partially populated, set ArrayDimensions to the maximum length and have the server return the populated subset. If the variable is multi-dimensional (e.g. matrix data), use ValueRank = 2 and ArrayDimensions = {0, 0}; the OPC UA Part 3 specification defines the full NumericRange grammar for higher-dimensional slices.

FAQ