UA-.NETStandard/docs/SourceGeneratedDataTypes.md

Source-Generated Data Types

The OPC UA .NET Standard stack includes a C# source generator that automatically implements the IEncodeable interface for annotated POCO classes and enums. This eliminates the need to hand-write Encode, Decode, IsEqual, and Clone methods for custom OPC UA data types.

Contents

• Quick Start
• Prerequisites
  • Project Reference
  • NuGet Package
• The DataType Attribute
  • Properties
  • Namespace Resolution Order
• The DataTypeField Attribute
  • Properties
  • Field Selection Rules
• Supported Property Types
  • Collections
  • Enums and IEncodeable Types
  • Unsupported Types
• Class Variants
  • Regular Partial Class
  • Sealed Partial Class
  • Record Class
  • Derived Class
  • Internal Class
• Enum Support
• Registering Types with the Encodeable Factory
• Complete Example
• StructureHandling Enum
• DefaultValueHandling Enum
  • How It Works
  • Example: Configuration with Defaults
• Partial Init Properties
  • Example
  • How It Works
  • When to Use
• Requirements and Constraints
• Generated File Output
• MSBuild Configuration

Quick Start

1. Mark your class as partial and decorate it with [DataType].
2. Add public properties for each field — the generator does the rest.

using Opc.Ua;

namespace MyApp.Configuration
{
    [DataType(Namespace = "urn:mycompany:myapp")]
    public partial class DeviceConfiguration
    {
        public string Name { get; set; }
        public int Port { get; set; }
        public bool Enabled { get; set; }
    }
}

The source generator will produce a partial class file that implements IEncodeable, including:

• TypeId, BinaryEncodingId, XmlEncodingId properties
• Encode(IEncoder) and Decode(IDecoder) methods
• IsEqual(IEncodeable) for value comparison
• Clone() for deep copy
• An activator class (e.g. DeviceConfigurationActivator) for type registration

Prerequisites

Project Reference (internal development)

When developing within the OPC UA .NET Standard repository, reference the source generator project and import its props file:

<ItemGroup>
  <ProjectReference
    Include="..\..\tools\Opc.Ua.SourceGeneration\Opc.Ua.SourceGeneration.csproj">
    <OutputItemType>Analyzer</OutputItemType>
    <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
  </ProjectReference>
</ItemGroup>
<Import
  Project="..\..\tools\Opc.Ua.SourceGeneration\OPCFoundation.Opc.Ua.SourceGeneration.props" />

NuGet Package (external consumers)

Add the OPCFoundation.NetStandard.Opc.Ua.SourceGeneration package:

dotnet add package OPCFoundation.NetStandard.Opc.Ua.SourceGeneration

The package is a development dependency, so the command adds a reference that runs the generator at build time and does not flow to consumers of your project:

<ItemGroup>
  <PackageReference
    Include="OPCFoundation.NetStandard.Opc.Ua.SourceGeneration"
    Version="...">
    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

The [DataType] Attribute

Applied to a partial class, partial record class, or an enum to opt in to source generation.

[AttributeUsage(
    AttributeTargets.Class | AttributeTargets.Struct | AttributeTargets.Enum)]
public sealed class DataTypeAttribute : Attribute
{
    public string? Namespace { get; set; }
    public string? DataTypeId { get; set; }
    public string? BinaryEncodingId { get; set; }
    public string? XmlEncodingId { get; set; }
}

Properties

Property	Description
Namespace	The OPC UA namespace URI for this type. If omitted, falls back to [DataContract(Namespace=...)] if present, or urn:<dotnet.namespace.lowered>.
DataTypeId	Node ID string for the data type (e.g. "i=12345", "s=MyType", "g=<guid>"). Must be prefixed with i=, s=, g=, or b=. If omitted, defaults to a string identifier with the class name ("s=DeviceConfiguration").
BinaryEncodingId	Optional binary encoding Node ID. Same prefix rules.
XmlEncodingId	Optional XML encoding Node ID. Same prefix rules.

Namespace Resolution Order

The generator resolves the OPC UA namespace URI in this order:

1. [DataType(Namespace = "...")] — explicitly specified
2. [DataContract(Namespace = "...")] — from System.Runtime.Serialization
3. urn:<dotnet.namespace.lowered> — automatic fallback (e.g. urn:myapp.configuration)

An explicit Namespace expression must be resolvable from the source compilation before generators run. Use a string literal or a const string declared in ordinary source or a referenced assembly. Do not reference a Namespaces constant emitted from a model file by the same generator run; generated symbols are not available while [DataType] attributes are analyzed. An unresolved explicit expression produces MODELGEN021 instead of silently falling back to a different namespace.

The [DataTypeField] Attribute

Applied to properties to control which fields participate in encoding and in what order.

[AttributeUsage(AttributeTargets.Property)]
public sealed class DataTypeFieldAttribute : Attribute
{
    public int Order { get; set; }
    public string? Name { get; set; }
    public StructureHandling StructureHandling { get; set; }
    public DefaultValueHandling DefaultValueHandling { get; set; }
    public bool IsRequired { get; set; }
}

Properties

Property	Description
Order	The encoding/decoding order of this field. Fields are sorted by Order before code generation.
Name	The serialized field name. Defaults to the property name if not set.
StructureHandling	For IEncodeable-typed fields: controls the encoding strategy. See StructureHandling.
DefaultValueHandling	Controls how default values are handled during encode/decode. See DefaultValueHandling.
IsRequired	Indicates whether the field is required. Reserved for future use with optional-field structures.

Field Selection Rules

• If any property has [DataTypeField]: only annotated properties are included in encoding. Non-annotated properties are excluded.
• If no properties have [DataTypeField]: all public read-write properties are automatically included, ordered by declaration position.

This lets you mix serialized and non-serialized properties in the same class:

[DataType(Namespace = "urn:myapp")]
public partial class ServerSettings
{
    [DataTypeField(Order = 0)]
    public string EndpointUrl { get; set; }

    [DataTypeField(Order = 1, Name = "session_timeout")]
    public uint SessionTimeout { get; set; }

    // Not annotated — excluded from encoding
    public string InternalNote { get; set; }
}

Supported Property Types

The source generator supports the following property types:

C# Type	OPC UA Type	Encoder Method
bool	Boolean	WriteBoolean
sbyte	SByte	WriteSByte
byte	Byte	WriteByte
short / Int16	Int16	WriteInt16
ushort / UInt16	UInt16	WriteUInt16
int / Int32	Int32	WriteInt32
uint / UInt32	UInt32	WriteUInt32
long / Int64	Int64	WriteInt64
ulong / UInt64	UInt64	WriteUInt64
float / Single	Float	WriteFloat
double / Double	Double	WriteDouble
string	String	WriteString
DateTime	DateTime	WriteDateTime
Guid / Uuid	Guid	WriteGuid
ByteString	ByteString	WriteByteString
NodeId	NodeId	WriteNodeId
ExpandedNodeId	ExpandedNodeId	WriteExpandedNodeId
StatusCode	StatusCode	WriteStatusCode
QualifiedName	QualifiedName	WriteQualifiedName
LocalizedText	LocalizedText	WriteLocalizedText
ExtensionObject	ExtensionObject	WriteExtensionObject
DataValue	DataValue	WriteDataValue
Variant	Variant	WriteVariant
DiagnosticInfo	DiagnosticInfo	WriteDiagnosticInfo
XmlElement	XmlElement	WriteXmlElement

Collections

• ArrayOf<T> — use for arrays of any supported type
• MatrixOf<T> — use for multi-dimensional arrays

Enums and IEncodeable Types

• Any C# enum type (encoded with WriteEnumerated/ReadEnumerated)
• Any type implementing IEncodeable or decorated with [DataType]

Unsupported Types

Properties with types not in the above list will produce:

• A warning if the property is not annotated with [DataTypeField] (the property is silently excluded)
• An error if the property is annotated with [DataTypeField] (the type will not generate)

Class Variants

The generator handles several class shapes:

Regular Partial Class

[DataType(Namespace = "urn:myapp")]
public partial class MyConfig
{
    public string Name { get; set; }
    public int Value { get; set; }
}

Generates virtual methods for Encode, Decode, IsEqual, and Clone.

Sealed Partial Class

[DataType(Namespace = "urn:myapp")]
public sealed partial class MyConfig
{
    public string Name { get; set; }
}

Generates non-virtual methods (no virtual or override keywords).

Record Class

[DataType(Namespace = Namespaces.OpcUaXsd)]
public partial record class BrowserOptions
{
    [DataTypeField(Order = 0)]
    public RequestHeader? RequestHeader { get; set; }

    [DataTypeField(Order = 1)]
    public uint MaxReferencesReturned { get; set; }
}

For record types, Clone() uses this with { } and IsEqual delegates to the record's Equals implementation.

Derived Class (Inheritance)

When a [DataType] class derives from another IEncodeable base type, the generator uses override instead of virtual and calls base.Encode()/ base.Decode() before encoding the derived fields. Clone() delegates to a generated MemberwiseClone() that starts from a shallow copy of the whole object — carrying the inherited fields — and then deep copies the derived class's own reference-typed fields, the same shape the model-based generator emits.

Internal Class

Classes declared as internal produce internal generated members.

Enum Support

Annotate an enum with [DataType] to register it as an OPC UA enumerated type:

[DataType(Namespace = "urn:myapp")]
public enum DeviceStatus
{
    Unknown = 0,
    Online = 1,
    Offline = 2,
    Error = 3
}

The generator produces an EnumeratedType<T> registration and an EnumDefinition factory. The enum does not need to be partial.

Registering Types with the Encodeable Factory

The source generator creates an extension method to register all [DataType] types in a namespace with an IEncodeableFactoryBuilder. The method is named Add<NamespaceWithoutDots>DataTypes():

// Generated extension method name is derived from the .NET namespace:
// For namespace "MyApp.Configuration" → AddMyAppConfigurationDataTypes()
MessageContext.Factory.Builder
    .AddMyAppConfigurationDataTypes()
    .Commit();

For example, types in Opc.Ua.Gds.Server produce a method named AddOpcUaGdsServerDataTypes():

protected override void OnServerStarting(
    ApplicationConfiguration configuration)
{
    base.OnServerStarting(configuration);

    MessageContext.Factory.Builder
        .AddOpcUaGdsServerDataTypes()
        .Commit();
}

Complete Example

This example shows a node manager configuration type used in the MemoryBuffer quickstart server:

using Opc.Ua;

namespace MemoryBuffer
{
    [DataType(Namespace = Namespaces.MemoryBuffer)]
    public partial class MemoryBufferConfiguration
    {
        public MemoryBufferConfiguration()
        {
        }

        [DataTypeField(Order = 1, StructureHandling = StructureHandling.Inline)]
        public ArrayOf<MemoryBufferInstance> Buffers { get; set; }
    }

    [DataType(Namespace = Namespaces.MemoryBuffer)]
    public partial class MemoryBufferInstance
    {
        public MemoryBufferInstance()
        {
        }

        [DataTypeField(Order = 1)]
        public string Name { get; set; }

        [DataTypeField(Order = 2)]
        public int TagCount { get; set; }

        [DataTypeField(Order = 3)]
        public string DataType { get; set; }
    }
}

Key points in this example:

• Both classes are partial and have parameterless constructors
• StructureHandling = StructureHandling.Inline on Buffers forces exact-type encoding (rather than extension object wrapping) since the element type is known at compile time
• Order controls the encoding sequence

StructureHandling Enum

When a property's type implements IEncodeable, the generator must choose between two encoding strategies:

Strategy	Method	Use When
Exact type	WriteEncodeable / ReadEncodeable	The concrete type is always known (sealed, no subtypes)
Extension Object	WriteEncodeableAsExtensionObject / ReadEncodeableAsExtensionObject	Subtypes may be substituted at runtime

The StructureHandling enum controls this choice:

public enum StructureHandling
{
    Auto = 0,             // Generator decides based on type analysis
    Inline = 1,           // Force WriteEncodeable / ReadEncodeable
    ExtensionObject = 2   // Force WriteEncodeableAsExtensionObject
}

Value	Behavior
Auto (default)	If the field type is sealed and does not derive from another IEncodeable, WriteEncodeable is used. Otherwise, WriteEncodeableAsExtensionObject is used.
Inline	Forces WriteEncodeable/ReadEncodeable — the exact type is written inline. Use when the concrete type is always known at compile time.
ExtensionObject	Forces WriteEncodeableAsExtensionObject/ReadEncodeableAsExtensionObject — the value is wrapped in an ExtensionObject. Use when subtypes may be substituted at runtime.

Example:

[DataType(Namespace = "urn:myapp")]
public partial class MyConfig
{
    // Inline: always encodes as EndpointDescription directly
    [DataTypeField(Order = 0, StructureHandling = StructureHandling.Inline)]
    public EndpointDescription Endpoint { get; set; }

    // Auto (default): generator decides based on whether the type is sealed
    [DataTypeField(Order = 1)]
    public OperationLimits Limits { get; set; }
}

DefaultValueHandling Enum

Controls how default values are handled during encode and decode. This is particularly important for configuration types where constructor defaults (e.g., NonceLength = 32, RejectSHA1SignedCertificates = true) should be preserved when the field is absent from an XML configuration file.

[Flags]
public enum DefaultValueHandling
{
    Exclude = 0,                       // Omit type defaults on write, keep declared default for missing XML
    Emit = 1,                          // Always write, even if default value
    SetIfMissing = 2,                  // Always set on read, even if absent
    Include = Emit | SetIfMissing      // Always write AND read (legacy behavior)
}

OPC 10000-6 (5.3.5, 5.4.1, 5.4.2.1, 5.4.7) defines a missing field as the default value of its type (Table 1: 0, false, null, ...), not a per-field default. The generated code follows that rule for JSON and keeps a declared-default leniency only for XML decoding:

Value	Encode Behavior	Decode Behavior
Exclude (default)	Omits the field from XML/Compact JSON only if its value is the type default and the declared default (initializer) is the type default too; a field with any other declared default is always written. Binary and Verbose JSON always write.	JSON: a missing field is the type default. XML: a missing field keeps the declared (constructor/initializer) default, so configuration files that predate a field still load. Binary always reads.
Emit	Always writes the field, even if default.	Same as Exclude for decode.
SetIfMissing	Omits the field from XML/Compact JSON if its value is the type default.	A missing field is the type default in every encoding (overwrites the declared default).
Include	Always writes.	Always reads and assigns.

Note that the Compact JsonEncoder drops a type-default value by itself even when the generated code writes it; since a missing JSON field decodes to the type default, e.g. int Port = 4840 set to 0 still round trips as 0. The XmlEncoder never writes a null reference (string, ByteString, ...), so a reference field with a non-null declared default that is set to null reads back from XML as its declared default. Use SetIfMissing or Include when that matters.

How It Works

The generated code uses two IEncoder/IDecoder APIs:

• IEncoder.CanOmitFields: Returns true for XML and for the Compact JSON encoding, false for Binary and for the Verbose (and RawData) JSON encoding, which include all fields (OPC 10000-6 5.4.1). Used by the encode guard.
• IDecoder.HasField(string): Returns true if the field exists in the encoded data. Always true for Binary. Checks element/property existence for XML/JSON.

Generated encode (when Emit is NOT set and the declared default is the type default, or SetIfMissing is set):

if (!encoder.CanOmitFields || Count != 0)
    encoder.WriteInt32("Count", Count);

Generated decode (when SetIfMissing is NOT set):

if (decoder.EncodingType != EncodingType.Xml || decoder.HasField("NonceLength"))
    NonceLength = decoder.ReadInt32("NonceLength");

Example: Configuration with Defaults

[DataType(Namespace = "urn:myapp")]
public partial class SecuritySettings
{
    public SecuritySettings()
    {
        NonceLength = 32;
        RejectExpiredCertificates = true;
    }

    // Exclude (default): always written (32 is not the type default);
    // a field missing from XML keeps 32, a field missing from JSON is 0
    [DataTypeField(Order = 0)]
    public int NonceLength { get; set; } = 32;

    // Include: always write and read — use for bool fields that default
    // to true, since false (the type default) is a valid explicit value
    [DataTypeField(Order = 1, DefaultValueHandling = DefaultValueHandling.Include)]
    public bool RejectExpiredCertificates { get; set; }

    // Exclude (default): omit false from XML, preserve false when absent
    [DataTypeField(Order = 2)]
    public bool AllowAnonymous { get; set; }
}

Guideline: Use DefaultValueHandling.Include for bool properties that default to true in the constructor. Since false is the type default, Exclude would omit an explicit false on encode. Include ensures the value always round-trips correctly.

Partial Init Properties

The source generator supports partial properties with init accessors for immutable record types. This enables record classes with init-only properties to participate in OPC UA binary and XML encoding — the generator creates a private backing field for each such property and assigns to it directly during Decode(), bypassing the init-only constraint.

Example

[DataType(Namespace = "urn:mycompany:myapp")]
public partial record class DeviceConfig
{
    [DataTypeField(Order = 0)]
    public partial string Name { get; init; } = "Default";

    [DataTypeField(Order = 1)]
    public partial int Port { get; init; }
}

The generator produces:

partial record class DeviceConfig : IEncodeable
{
    private string __Name = "Default";
    public partial string Name { get => __Name; init => __Name = value; }

    private int __Port;
    public partial int Port { get => __Port; init => __Port = value; }

    public virtual void Decode(IDecoder decoder)
    {
        // Assigns to backing field, bypassing init constraint
        if (decoder.HasField("Name")) __Name = decoder.ReadString("Name");
        if (decoder.HasField("Port")) __Port = decoder.ReadInt32("Port");
    }
    // ...
}

How It Works

1. For each property declared as partial with an init accessor, the generator emits a private backing field named __<PropertyName>.
2. The partial property implementation delegates get and init to that backing field.
3. Decode() assigns to the backing field directly, which is legal because the field is a regular mutable field — only the public init accessor is restricted to object-initializer contexts.
4. Clone() for record types uses this with { }, which copies init-only properties automatically via the copy constructor.

When to Use

• Use partial + init properties when you want an immutable public API (callers can only set values at construction time) while still allowing the decoder to populate the object from a binary or XML stream.
• This is especially useful for configuration and options types modeled as record class.

Requirements and Constraints

1. Must be partial: The class must be declared partial so the generator can extend it. Non-partial classes produce a compile error.
2. Parameterless constructor: The class must have a parameterless constructor (either explicit or implicit).
3. Read-write properties: Only properties with both getter and setter are considered. Read-only properties are ignored.
4. One [DataType] per type: AllowMultiple = false — each type can have at most one [DataType] attribute.
5. Unique identifiers: DataTypeId must be unique across all data types in the same namespace. For open namespaces, using a random GUID (g=<guid>) is recommended.

Generated File Output

The generator produces one .g.cs file per .NET namespace. The file name follows the pattern <NamespaceWithoutDots>.Types.g.cs.

For example, types in Opc.Ua.Gds.Server produce a file named OpcUaGdsServer.Types.g.cs containing:

• All partial class bodies (IEncodeable implementation)
• Activator classes for each type
• A single extension class with the Add...DataTypes() registration method

MSBuild Configuration

The source generator supports the following MSBuild properties via the OPCFoundation.Opc.Ua.SourceGeneration.props file:

Property	Description
ModelSourceGeneratorPublicDataTypeExtensions	When true, the generated extension methods and their containing static class are public instead of internal.