Add structure-backed OptionSet DataType support in ComplexTypeSystem (#3672)

marcschier · Copilot · web-flow · commit 34ed5716c040 · 2026-04-17T21:16:55.000+02:00
Concrete sub-types of the abstract OptionSet DataType (i=12755, e.g. AccessRights, CarExtras, OptionSetBase) were silently skipped by ComplexTypeSystem.LoadBaseStructureDataTypesAsync when only an EnumDefinition or OptionSetValues property was available. This change registers them with a new runtime class Opc.Ua.Encoders.OptionSet that reuses the generated Opc.Ua.OptionSet wire format (Value/ValidBits ByteStrings) and self-registers via IEncodeableType.

Key changes:

- New Stack/Opc.Ua/Types/OptionSet.cs with EnumDefinition-driven bit accessors (by name and index), GetSetFieldNames helper, and a fixed ByteLength derived from the highest declared bit per OPC UA Part 3 paragraph 8.40 / 3.2.8. SetBit throws ArgumentOutOfRangeException outside that range and always materializes Value/ValidBits to the fixed length.

- New AddOptionSetType entry point on IComplexTypeBuilder (source-breaking addition for custom implementations); DefaultComplexTypeBuilder implements it. The Reflection.Emit ComplexTypeBuilder throws NotSupportedException.

- ComplexTypeSystem detects OptionSet descendants via a HasSubtype walk and resolves the EnumDefinition from DataTypeDefinition or the OptionSetValues property fallback before the old skip path.

- Removed stale V1.04 OptionSet limitation remark from ComplexTypeSystem.

- 10 unit tests in Tests/Opc.Ua.Client.Tests/ComplexTypes/DefaultOptionSetTests.cs covering factory registration, bit accessors, binary round-trip via ExtensionObject, hand-crafted Part 6 wire format, Clone/CreateInstance semantics, and the ByteLength invariant.

- Live-verified against opc.tcp://DESKTOP-BGFJS91:48010 (UA C++ SDK demo): AccessRights/CarExtras/OptionSetBase now appear in the registered custom-type list; no skip-log entries; LoadAsync(throwOnError:true) returns true.

- Docs/ComplexTypes.md Known Limitations reworded; Docs/MigrationGuide.md gains an OptionSet DataType support subsection.

UInteger-backed OptionSet DataTypes remain intentionally opaque (carried as their unsigned integer in a Variant).

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -145,6 +145,7 @@ DocProject/Help/html
 
 # Click-Once directory
 publish/
+publish-aot/
 
 # Publish Web Output
 *.[Pp]ublish.xml
diff --git a/Applications/ConsoleReferenceClient/ClientSamples.cs b/Applications/ConsoleReferenceClient/ClientSamples.cs
@@ -31,7 +31,6 @@
 using System.Collections;
 using System.Collections.Generic;
 using System.Diagnostics;
-using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Linq;
 using System.Text;
@@ -1109,7 +1108,7 @@ public async Task LoadTypeSystemAsync(ComplexTypeSystem complexTypeSystem, Cance
             var stopWatch = new Stopwatch();
             stopWatch.Start();
 
-            await complexTypeSystem.LoadAsync(throwOnError: true, ct: ct).ConfigureAwait(false);
+            bool loaded = await complexTypeSystem.LoadAsync(throwOnError: true, ct: ct).ConfigureAwait(false);
 
             stopWatch.Stop();
 
@@ -1118,6 +1117,13 @@ public async Task LoadTypeSystemAsync(ComplexTypeSystem complexTypeSystem, Cance
                 complexTypeSystem.GetDefinedTypes().Count,
                 stopWatch.ElapsedMilliseconds);
 
+            if (!loaded)
+            {
+                throw new ServiceResultException(
+                    StatusCodes.BadTypeMismatch,
+                    "ComplexTypeSystem.LoadAsync did not load all custom types.");
+            }
+
             if (m_verbose)
             {
                 m_logger.LogInformation("Custom types defined for this session:");
@@ -1566,10 +1572,6 @@ private static ArrayOf<BrowseDescription> CreateBrowseDescriptionCollectionFromN
         /// <param name="session">The session to use for exporting.</param>
         /// <param name="nodes">The list of nodes to export.</param>
         /// <param name="filePath">The path where the NodeSet2 XML file will be saved.</param>
-        [RequiresUnreferencedCode(
-            "Uses XmlSerializer which requires unreferenced code.")]
-        [RequiresDynamicCode(
-            "Uses XmlSerializer which requires unreferenced code.")]
         public void ExportNodesToNodeSet2(ISession session, IList<INode> nodes, string filePath)
         {
             m_logger.LogInformation("Exporting {Count} nodes to {FilePath}...", nodes.Count, filePath);
@@ -1606,10 +1608,6 @@ public void ExportNodesToNodeSet2(ISession session, IList<INode> nodes, string f
         /// <returns>A dictionary mapping namespace URI to the file path of the exported NodeSet2 file.</returns>
         /// <exception cref="ArgumentNullException">Thrown when session, nodes, or outputDirectory is null.</exception>
         /// <exception cref="ArgumentException">Thrown when outputDirectory is empty or whitespace.</exception>
-        [RequiresUnreferencedCode(
-            "Uses XmlSerializer which requires unreferenced code.")]
-        [RequiresDynamicCode(
-            "Uses XmlSerializer which requires unreferenced code.")]
         public async Task<IReadOnlyDictionary<string, string>> ExportNodesToNodeSet2PerNamespaceAsync(
             ISession session,
             IList<INode> nodes,
diff --git a/Applications/ConsoleReferenceClient/ConsoleReferenceClient.csproj b/Applications/ConsoleReferenceClient/ConsoleReferenceClient.csproj
@@ -20,7 +20,6 @@
     <PackageReference Include="System.CommandLine" />
     <PackageReference Include="Serilog" />
     <PackageReference Include="Serilog.Extensions.Logging" />
-    <PackageReference Include="Serilog.Expressions" />
     <PackageReference Include="Serilog.Sinks.Console" />
     <PackageReference Include="Serilog.Sinks.File" />
     <PackageReference Include="Serilog.Sinks.Debug" />
diff --git a/Applications/ConsoleReferenceClient/Program.cs b/Applications/ConsoleReferenceClient/Program.cs
@@ -526,8 +526,11 @@ r is VariableNode v &&
 
                                     if (exportNodes)
                                     {
-                                        await samples
-                                            .ExportNodesToNodeSet2PerNamespaceAsync(uaClient.Session, allNodes, Environment.CurrentDirectory, cancellationToken)
+                                        await samples.ExportNodesToNodeSet2PerNamespaceAsync(
+                                                uaClient.Session,
+                                                allNodes,
+                                                Environment.CurrentDirectory,
+                                                cancellationToken)
                                             .ConfigureAwait(false);
                                     }
                                 }
diff --git a/Applications/ConsoleReferencePublisher/ConsoleReferencePublisher.csproj b/Applications/ConsoleReferencePublisher/ConsoleReferencePublisher.csproj
@@ -23,7 +23,6 @@
     <PackageReference Include="System.Private.Uri" />
     <PackageReference Include="Serilog" />
     <PackageReference Include="Serilog.Extensions.Logging" />
-    <PackageReference Include="Serilog.Expressions" />
     <PackageReference Include="Serilog.Sinks.Console" />
     <PackageReference Include="Serilog.Sinks.File" />
     <PackageReference Include="Serilog.Sinks.Debug" />
diff --git a/Applications/ConsoleReferenceServer/ConsoleReferenceServer.csproj b/Applications/ConsoleReferenceServer/ConsoleReferenceServer.csproj
@@ -29,7 +29,6 @@
     <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
     <PackageReference Include="System.CommandLine" />
     <PackageReference Include="Serilog" />
-    <PackageReference Include="Serilog.Expressions" />
     <PackageReference Include="Serilog.Sinks.Console" />
     <PackageReference Include="Serilog.Extensions.Logging" />
     <PackageReference Include="Serilog.Sinks.File" />
diff --git a/Applications/ConsoleReferenceServer/ConsoleUtils.cs b/Applications/ConsoleReferenceServer/ConsoleUtils.cs
@@ -40,7 +40,6 @@
 using Opc.Ua;
 using Serilog;
 using Serilog.Events;
-using Serilog.Templates;
 #if NET5_0_OR_GREATER
 using Microsoft.Extensions.Configuration;
 #endif
@@ -176,9 +175,8 @@ public void ConfigureLogging(
                 if (!string.IsNullOrWhiteSpace(outputFilePath))
                 {
                     loggerConfiguration.WriteTo.File(
-                        new ExpressionTemplate(
-                            "{UtcDateTime(@t):yyyy-MM-dd HH:mm:ss.fff} [{@l:u3}] {@m}\n{@x}"),
                         Utils.ReplaceSpecialFolderNames(outputFilePath),
+                        outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff} [{Level:u3}] {Message:lj}{NewLine}{Exception}",
                         restrictedToMinimumLevel: (LogEventLevel)fileLevel,
                         rollOnFileSizeLimit: true
                     );
diff --git a/Applications/ConsoleReferenceSubscriber/ConsoleReferenceSubscriber.csproj b/Applications/ConsoleReferenceSubscriber/ConsoleReferenceSubscriber.csproj
@@ -23,7 +23,6 @@
     <PackageReference Include="System.Private.Uri" />
     <PackageReference Include="Serilog" />
     <PackageReference Include="Serilog.Extensions.Logging" />
-    <PackageReference Include="Serilog.Expressions" />
     <PackageReference Include="Serilog.Sinks.Console" />
     <PackageReference Include="Serilog.Sinks.File" />
     <PackageReference Include="Serilog.Sinks.Debug" />
diff --git a/Docs/ComplexTypes.md b/Docs/ComplexTypes.md
@@ -837,7 +837,9 @@ TypeInfo TypeInfo { get; }                // Type info of the field
 
 ## Known Limitations
 
-1. **OptionSet Support**: OPC UA 1.04 OptionSet types do not automatically create enumeration flags
+1. **OptionSet Support**: Concrete Structure-backed sub-types of the abstract `OptionSet` DataType (`i=12755`, e.g. `AccessRights`, `CarExtras`) are automatically registered by the default `ComplexTypeSystem` builder as `Opc.Ua.Encoders.OptionSet` runtime instances, driven by either the `EnumDefinition` carried in `DataTypeDefinition` or a fallback synthesized from the `OptionSetValues` property. The runtime class exposes the two canonical `Value` / `ValidBits` ByteStrings plus bit accessors keyed by field name or bit index. Per Part 3 §8.40 / §3.2.8, the overall ByteString length is fixed by the sub-type's declared bits (exposed as `ByteLength`); setting a bit outside that range throws `ArgumentOutOfRangeException`. Remaining limitations:
+   - UInteger-backed OptionSet DataTypes (DataTypes deriving from an unsigned integer with `IsOptionSet=true`) continue to be represented as their underlying unsigned integer in a `Variant` — no per-bit metadata is surfaced.
+   - The legacy Reflection.Emit builder in `Opc.Ua.Client.ComplexTypes` throws `NotSupportedException` for OptionSet sub-types; switch to the default builder (`new ComplexTypeSystem(session)`) for OptionSet support.
 2. **Legacy Dictionary Support**: Some OPC UA 1.03 structured types that cannot be mapped to OPC UA 1.04 definitions are ignored
 3. **Type Modifications**: Once loaded, types cannot be dynamically updated during a session. Reconnect to reload modified types.
 
diff --git a/Docs/MigrationGuide.md b/Docs/MigrationGuide.md
@@ -43,6 +43,7 @@
       - [ExtensionObject array helpers changed](#extensionobject-array-helpers-changed)
     - [Complex Types](#complex-types)
       - [ComplexTypes moved to Opc.Ua.Client assembly](#complextypes-moved-to-opcuaclient-assembly)
+      - [OptionSet DataType support](#optionset-datatype-support)
     - [Other Breaking Changes](#other-breaking-changes)
   - [Migrating from 1.05.377 to 1.05.378](#migrating-from-105377-to-105378)
     - [Asynchronous as default](#asynchronous-as-default)
@@ -616,6 +617,17 @@ Core complex type interfaces and default (non-reflection-emit) implementations m
 Namespace remains `Opc.Ua.Client.ComplexTypes`. If you used the default constructors without specifying the builder, and want to use the Reflection.Emit based type builders,
 you need to change your code to call `ComplexTypeSystem.Create(...)` instead of `new ComplexTypeSystem(...)` which now uses the new default builder not supporting Reflection.Emit.
 
+#### OptionSet DataType support
+
+Concrete Structure-backed sub-types of the abstract `OptionSet` DataType (`i=12755`) are now automatically registered by the default `ComplexTypeSystem` builder with a new runtime class `Opc.Ua.Encoders.OptionSet` (in `Stack/Opc.Ua.Types`). Bit-field metadata is resolved from `DataTypeDefinition` (`EnumDefinition`) or, as a fallback, synthesized from the `OptionSetValues` property (`LocalizedText[]`).
+
+Impact on existing code:
+
+- **Source-breaking for custom `IComplexTypeBuilder` implementations**: a new member `AddOptionSetType(QualifiedName, ExpandedNodeId, ExpandedNodeId, ExpandedNodeId, ExpandedNodeId, EnumDefinition)` was added to `IComplexTypeBuilder`. Custom implementations must provide it.
+- The Reflection.Emit builder in `Opc.Ua.Client.ComplexTypes` throws `NotSupportedException` from `AddOptionSetType`; callers relying on the Reflection.Emit path for OptionSet sub-types should switch to the default builder (`new ComplexTypeSystem(session)`).
+- No wire-format changes: encoders/decoders continue to route through `IEncodeableFactory` → `IEncodeableType.CreateInstance`, which now yields `Opc.Ua.Encoders.OptionSet` for registered sub-types.
+- UInteger-backed OptionSet DataTypes remain treated as their underlying unsigned integer in a `Variant` (unchanged).
+
 ### Other Breaking Changes
 
 - **Session/Browser state format**: Persistence switched from `DataContractSerializer` XML to `BinaryEncoder`. Delete old persisted files and re-establish sessions.
diff --git a/Libraries/Opc.Ua.Client.ComplexTypes/TypeBuilder/ComplexTypeBuilder.cs b/Libraries/Opc.Ua.Client.ComplexTypes/TypeBuilder/ComplexTypeBuilder.cs
@@ -149,6 +149,25 @@ public IComplexTypeFieldBuilder AddStructuredType(
             return new ComplexTypeFieldBuilder(structureBuilder, structureDefinition.StructureType);
         }
 
+        /// <summary>
+        /// OptionSet sub-types are not supported by the Reflection.Emit
+        /// complex type builder. Use the default (source-generated)
+        /// complex type builder instead for OptionSet support.
+        /// </summary>
+        /// <exception cref="NotSupportedException">Always thrown.</exception>
+        public IEncodeableType AddOptionSetType(
+            QualifiedName typeName,
+            ExpandedNodeId typeId,
+            ExpandedNodeId binaryEncodingId,
+            ExpandedNodeId xmlEncodingId,
+            ExpandedNodeId jsonEncodingId,
+            EnumDefinition enumDefinition)
+        {
+            throw new NotSupportedException(
+                "OptionSet DataTypes are not supported by the Reflection.Emit " +
+                "complex type builder. Use the default complex type builder.");
+        }
+
         /// <summary>
         /// Create a unique namespace module name for the type.
         /// </summary>
diff --git a/Libraries/Opc.Ua.Client/ComplexTypes/ComplexTypeSystem.cs b/Libraries/Opc.Ua.Client/ComplexTypes/ComplexTypeSystem.cs
@@ -49,7 +49,9 @@ namespace Opc.Ua.Client.ComplexTypes
     /// with the following known restrictions:
     /// - Support only for V1.03 structured types which can be mapped to the V1.04
     /// structured type definition. Unsupported V1.03 types are ignored.
-    /// - V1.04 OptionSet does not create the enumeration flags.
+    /// - Concrete Structure-backed sub-types of the abstract <c>OptionSet</c>
+    /// DataType are supported. UInteger-backed <c>IsOptionSet</c> DataTypes
+    /// are left opaque (their wire form is the plain unsigned integer).
     /// </remarks>
     public class ComplexTypeSystem
     {
@@ -987,11 +989,66 @@ var missingTypeIdsFromWorkList
 
                             if (newType == null)
                             {
-                                structTypesToDoList.Add(structType);
                                 if (structureDefinition != null)
                                 {
+                                    structTypesToDoList.Add(structType);
                                     retryAddStructType = true;
                                 }
+                                else if (await IsOptionSetSubtypeAsync(structType.NodeId, ct)
+                                    .ConfigureAwait(false))
+                                {
+                                    // Concrete Structure-backed sub-type of the
+                                    // abstract OptionSet DataType. The wire
+                                    // format is the inherited Value/ValidBits
+                                    // ByteStrings; field semantics come from an
+                                    // EnumDefinition or the OptionSetValues
+                                    // property.
+                                    (
+                                        ArrayOf<NodeId> encodingIds,
+                                        ExpandedNodeId binaryEncodingId,
+                                        ExpandedNodeId xmlEncodingId
+                                    ) = await m_complexTypeResolver
+                                        .BrowseForEncodingsAsync(
+                                            structType.NodeId,
+                                            s_supportedEncodings,
+                                            ct)
+                                        .ConfigureAwait(false);
+                                    ExpandedNodeId typeId = NormalizeExpandedNodeId(
+                                        structType.NodeId);
+                                    newType = await AddOptionSetTypeAsync(
+                                            complexTypeBuilder,
+                                            dataTypeNode,
+                                            typeId,
+                                            binaryEncodingId,
+                                            xmlEncodingId,
+                                            ExpandedNodeId.Null,
+                                            ct)
+                                        .ConfigureAwait(false);
+                                    if (newType != null)
+                                    {
+                                        foreach (NodeId encodingId in encodingIds)
+                                        {
+                                            AddEncodeableType(encodingId, newType);
+                                        }
+                                        AddEncodeableType(structType.NodeId, newType);
+                                    }
+                                    else
+                                    {
+                                        m_logger.LogInformation(
+                                            "Skipped OptionSet sub-type {DataType} because no EnumDefinition or OptionSetValues property was found.",
+                                            dataTypeNode.BrowseName.Name);
+                                    }
+                                }
+                                else
+                                {
+                                    // A non-abstract Structure subtype without a valid
+                                    // DataTypeDefinition cannot be materialized by this path.
+                                    // Skip silently so the overall load is not marked as failed
+                                    // when the server exposes such unresolvable types.
+                                    m_logger.LogInformation(
+                                        "Skipped the type definition of {DataType} because no DataTypeDefinition is available.",
+                                        dataTypeNode.BrowseName.Name);
+                                }
                             }
                         }
                     }
@@ -1290,6 +1347,91 @@ private void AddEncodeableType(ExpandedNodeId nodeId, IType type)
             return newType;
         }
 
+        /// <summary>
+        /// Add an OptionSet type defined in a DataType node whose wire
+        /// format is the inherited <c>Value</c>/<c>ValidBits</c>
+        /// ByteStrings of the abstract <c>OptionSet</c> DataType.
+        /// </summary>
+        private async Task<IEncodeableType?> AddOptionSetTypeAsync(
+            IComplexTypeBuilder complexTypeBuilder,
+            DataTypeNode dataTypeNode,
+            ExpandedNodeId typeId,
+            ExpandedNodeId binaryEncodingId,
+            ExpandedNodeId xmlEncodingId,
+            ExpandedNodeId jsonEncodingId,
+            CancellationToken ct = default)
+        {
+            QualifiedName name = dataTypeNode.BrowseName;
+
+            // 1. use DataTypeDefinition
+            if (DisableDataTypeDefinition ||
+                !dataTypeNode.DataTypeDefinition.TryGetEncodeable(
+                    out EnumDefinition? enumDefinition))
+            {
+                // 2. fall back to OptionSetValues property (LocalizedText[])
+                Variant enumTypeArray = await m_complexTypeResolver
+                    .GetEnumTypeArrayAsync(dataTypeNode.NodeId, ct)
+                    .ConfigureAwait(false);
+                if (enumTypeArray.TryGet(out ArrayOf<LocalizedText> localizedText))
+                {
+                    enumDefinition = localizedText.ToEnumDefinition(name.Name);
+                }
+                else
+                {
+                    enumDefinition = null;
+                }
+            }
+
+            if (enumDefinition == null)
+            {
+                return null;
+            }
+
+            // Mark as OptionSet (bit positions rather than ordinal values).
+            enumDefinition.IsOptionSet = true;
+
+            // Add EnumDefinition to cache
+            m_dataTypeDefinitionCache[dataTypeNode.NodeId] = enumDefinition;
+
+            return complexTypeBuilder.AddOptionSetType(
+                name,
+                typeId,
+                binaryEncodingId,
+                xmlEncodingId,
+                jsonEncodingId,
+                enumDefinition);
+        }
+
+        /// <summary>
+        /// Returns <c>true</c> if <paramref name="dataTypeId"/> is a
+        /// concrete sub-type of the abstract <c>OptionSet</c> DataType.
+        /// </summary>
+        private async Task<bool> IsOptionSetSubtypeAsync(
+            ExpandedNodeId dataTypeId,
+            CancellationToken ct)
+        {
+            NodeId superType = ExpandedNodeId.ToNodeId(
+                dataTypeId,
+                m_complexTypeResolver.NamespaceUris);
+            while (!superType.IsNull)
+            {
+                superType = await m_complexTypeResolver
+                    .FindSuperTypeAsync(superType, ct)
+                    .ConfigureAwait(false);
+                if (superType == DataTypeIds.OptionSet)
+                {
+                    return true;
+                }
+                if (superType == DataTypeIds.Structure ||
+                    superType == DataTypeIds.Enumeration ||
+                    TypeInfo.GetBuiltInType(superType) != BuiltInType.Null)
+                {
+                    return false;
+                }
+            }
+            return false;
+        }
+
         /// <summary>
         /// Add structured type to assembly with StructureDefinition.
         /// </summary>
diff --git a/Libraries/Opc.Ua.Client/ComplexTypes/DefaultComplexTypeBuilder.cs b/Libraries/Opc.Ua.Client/ComplexTypes/DefaultComplexTypeBuilder.cs
diff --git a/Libraries/Opc.Ua.Client/ComplexTypes/IComplexTypeFactory.cs b/Libraries/Opc.Ua.Client/ComplexTypes/IComplexTypeFactory.cs
diff --git a/Stack/Opc.Ua/Types/OptionSet.cs b/Stack/Opc.Ua/Types/OptionSet.cs
diff --git a/Tests/Opc.Ua.Client.Tests/ComplexTypes/DefaultOptionSetTests.cs b/Tests/Opc.Ua.Client.Tests/ComplexTypes/DefaultOptionSetTests.cs

Original file line number	Diff line number	Diff line change
`@@ -526,8 +526,11 @@ r is VariableNode v &&`
`526`	`526`
`527`	`527`	`if (exportNodes)`
`528`	`528`	`{`
`529`		`- await samples`
`530`		`- .ExportNodesToNodeSet2PerNamespaceAsync(uaClient.Session, allNodes, Environment.CurrentDirectory, cancellationToken)`
	`529`	`+ await samples.ExportNodesToNodeSet2PerNamespaceAsync(`
	`530`	`+ uaClient.Session,`
	`531`	`+ allNodes,`
	`532`	`+ Environment.CurrentDirectory,`
	`533`	`+ cancellationToken)`
`531`	`534`	`.ConfigureAwait(false);`
`532`	`535`	`}`
`533`	`536`	`}`