UA-.NETStandard/docs/migrate/2.0.x/pubsub.md

PubSub (Part 14)

When to read this: Read this if your application uses any of the Opc.Ua.PubSub.* namespaces, the legacy UaPubSubApplication factory, the JsonEncodingMode enum, or RawData field encoding. This sub-doc documents the PubSub breaking and behaviour-affecting changes in 2.0.

For the full Part 14 feature reference, including additive 2.0 capabilities, see PubSub.md. This sub-doc focuses on migration work required for existing consumers.

Contents

• 1. PubSub assemblies and NuGet packages renamed and split
• 2. UaPubSubApplication.Create* and the legacy 1.04 API are replaced
• 3. JSON encoder switched to System.Text.Json
• 4. JsonEncodingMode Reversible/Non-Reversible encodings removed
• 5. UADP RawData bounded-field wire-compatibility break
• 6. Compatibility matrix
• See also

1. PubSub assemblies and NuGet packages renamed and split

The monolithic 1.5.378 PubSub library has been refactored into one core assembly plus dedicated transport and server-integration assemblies. Each assembly ships as its own NuGet package under the OPCFoundation.NetStandard.Opc.Ua.PubSub* package prefix:

Assembly	NuGet package	Contents
Opc.Ua.PubSub	OPCFoundation.NetStandard.Opc.Ua.PubSub	Core application, encoding, scheduling, security, and DataSets.
Opc.Ua.PubSub.Udp	OPCFoundation.NetStandard.Opc.Ua.PubSub.Udp	UDP datagram transport (Part 14 §7.3.2).
Opc.Ua.PubSub.Eth	OPCFoundation.NetStandard.Opc.Ua.PubSub.Eth	Ethernet Layer 2 transport (opc.eth://, EtherType 0xB62C).
Opc.Ua.PubSub.Mqtt	OPCFoundation.NetStandard.Opc.Ua.PubSub.Mqtt	MQTT broker transport (Part 14 §7.3.4).
Opc.Ua.PubSub.Server	OPCFoundation.NetStandard.Opc.Ua.PubSub.Server	Server-side address-space integration (Part 14 §9).
Opc.Ua.PubSub.Adapter	OPCFoundation.NetStandard.Opc.Ua.PubSub.Adapter	External-server publisher/subscriber/Action binding over ManagedSession.

Consumers that previously referenced the single Opc.Ua.PubSub package must add the transport package(s) they use (...PubSub.Udp and/or ...PubSub.Mqtt) and, for address-space integration, the ...PubSub.Server package. Add ...PubSub.Adapter when a PubSub application must bind DataSets or Actions to an external OPC UA server through a managed client session. The root namespaces follow the assembly names (Opc.Ua.PubSub, Opc.Ua.PubSub.Udp, Opc.Ua.PubSub.Mqtt, Opc.Ua.PubSub.Server).

The legacy 1.04 top-level types listed in §2 are removed in 2.0. The sole bridge retained in the main PubSub assembly is the obsolete IUaPubSubDataStore interface. Existing application, connection, publisher, and configurator code must migrate to the modern fluent builder / DI surface.

2. UaPubSubApplication.Create* and the legacy 1.04 API are replaced

UaPubSubApplication.Create(...) (and its overloads) and the legacy 1.04 application, connection, publisher, and configurator types are removed in 2.0. There is no Opc.Ua.PubSub.Legacy compatibility package. Migrate those sites to the fluent builder or the DI extensions:

Removed legacy type	New replacement
UaPubSubApplication	IPubSubApplication (built via PubSubApplicationBuilder)
IUaPubSubConnection	IPubSubConnection
UaPubSubConnection	PubSubConnection (sealed runtime implementation, normally created by the builder)
IUaPublisher / UaPublisher	IPubSubScheduler + WriterGroup (engine-driven)
UaPubSubConfigurator	PubSubApplicationBuilder (fluent) + IPubSubConfigurationStore
PubSubJsonEncoder / PubSubJsonDecoder	Opc.Ua.PubSub.Encoding.Json.JsonEncoder / JsonDecoder (System.Text.Json)

IUaPubSubDataStore remains in Opc.Ua.PubSub (marked [Obsolete], UA0023) because the modern bridge still consumes it; migrate to IPublishedDataSetSource (per-DataSet provider model) when convenient.

Codemod recipe:

// Before (1.5.378)
var app = UaPubSubApplication.Create("publisher.xml");
app.Start();
// ...
app.Stop();

// After (2.0)
ITelemetryContext telemetry = DefaultTelemetry.Create(
    logging => logging.AddConsole());
var builder = new PubSubApplicationBuilder(telemetry)
    .UseConfigurationFile("publisher.xml");
await using IPubSubApplication app = await builder.BuildAndStartAsync();
// ...
await app.StopAsync();

See PubSub.md §Fluent builder for the in-code form. Cites Part 14 §6.2.

3. JSON encoder switched to System.Text.Json

The Newtonsoft-based encoder (Opc.Ua.PubSub.Encoding.JsonNetworkMessage v1) is replaced with a System.Text.Json-backed encoder under src/Opc.Ua.PubSub/Encoding/Json/. Behaviour changes that may surface in callers:

• The Newtonsoft.Json dependency is dropped. Core does not supply it either; add an explicit reference if application code still uses Newtonsoft APIs. See package dependency migration.
• Numeric round-trips honour the .NET native precision instead of the Newtonsoft default (e.g. double → 17 significant digits, not 15).
• The new encoder is Utf8JsonWriter-backed; allocations on the hot path drop ~70 % vs. the Newtonsoft pipeline.
• The decoder uses Utf8JsonReader and validates structurally; it rejects trailing junk where the old decoder silently truncated.

4. JsonEncodingMode Reversible/Non-Reversible encodings removed

Opc.Ua.PubSub.Encoding.Json.JsonEncodingMode.Reversible and Opc.Ua.PubSub.Encoding.Json.JsonEncodingMode.NonReversible are removed in favour of the Part 6 §5.4.1 / Part 14 §7.2.5 names:

Old	New
JsonEncodingMode.Reversible	JsonEncodingMode.Verbose
JsonEncodingMode.NonReversible	JsonEncodingMode.Compact
(new)	JsonEncodingMode.RawData

Verbose carries the same information as the old Reversible mode, and Compact the same as NonReversible; the rename is a public-API change. Note the encoder switch to System.Text.Json (§3) can change incidental formatting (e.g. number precision), so output is not guaranteed byte-identical to the 1.04 Newtonsoft encoder. No [Obsolete] aliases exist — consumers update enum references at upgrade time. Background: #3609.

5. UADP RawData bounded-field wire-compatibility break

This is an on-wire compatibility break for consumers of bounded RawData fields. Per Part 14 §7.2.4.5.11, String, ByteString, XmlElement, and array fields encoded via DataSetFieldContentMask.RawData are now padded to the maximum size declared in FieldMetaData.MaxStringLength or FieldMetaData.ArrayDimensions. The on-wire length prefix is suppressed for padded fields; consumers receive the exact MaxStringLength bytes with trailing NULs as the spec mandates, and decoders trim the trailing NUL fill on read.

If your configuration uses RawData but does not declare MaxStringLength or ArrayDimensions, the encoder falls back to the legacy length-prefixed form (variable size) and the configuration validator surfaces issue code PSC0025 (SpecClause = "7.2.4.5.11") so the missing bound is reported at configuration time. Closes #3566.

6. Compatibility matrix

Surface	2.0 outcome
UaPubSubApplication.Create(string) from XML config	Source break. Replace with PubSubApplicationBuilder.UseConfigurationFile(...) and BuildAndStartAsync().
UaPubSubApplication.Start() / .Stop()	Source break. Use IPubSubApplication async lifecycle methods.
Direct construction of UaPubSubConnection etc.	Source break. Configure connections through the fluent builder / DI surface.
IUaPubSubDataStore	Compiles with [Obsolete]; PubSubApplicationBuilder.WithDataStore(...) adapts it temporarily. Migrate to IPublishedDataSetSource.
Newtonsoft-based PubSub JSON formatting assumptions	Behavioural break. System.Text.Json precision and validation rules apply.
JsonEncodingMode.Reversible / NonReversible	Source break. Rename to Verbose / Compact.
DataSetFieldContentMask.RawData with bounded strings/arrays	Wire break. Fields are padded and length prefixes suppressed per spec.

See also

• Library reference (PubSub.md)
• Dependency injection
• Profiles — Datagram-v2, SKS pull/push, AES-CTR
• Native AOT
• What's New in 2.0