Marc Schier
e80d0ca9ac
# Description
The first PubSub exchange in
[docs/PubSub.md](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/docs/PubSub.md#run-a-first-publisher-and-subscriber)
delivers no DataSets on master or in the 2.0.0 source. The subscriber
only logs `DataSetReader Reader 1 faulted on MessageReceiveTimeout`,
while the publisher logs `UADP security wrap failed; dropping message`
with `ArgumentException: AES-CTR nonce must be exactly 12 bytes` for
every NetworkMessage.
Cause: the reference PubSub sample's demo keys use a 12-byte KeyNonce.
Since #4573, the AES-CTR counter block follows OPC 10000-14 Table 157
(`KeyNonce[4] || MessageNonce[8] || BlockCounter[4]`). With the sample's
keys, the publisher builds a 20-byte nonce, and `AesCtrTransform`
rejects it. The 2.0.0 release (release/2.0 at bc5da1006) contains #4573
and the 12-byte sample, so it is affected too.
Fix: the sample sizes its KeyNonce with
`AesCtrNonceLayout.KeyNonceLength`. No SDK change.
Regression test:
`PubSubAotTests.SamplePublisherDeliversSecuredDataSetToSampleSubscriberAsync`
starts the sample publisher and subscriber with the sample keys over
unicast loopback and waits for a DataSet. The existing sample-based AOT
tests only built or started the applications, so nothing caught the
regression.
### Validation
| Command | Result |
| --- | --- |
| `tests\Opc.Ua.Aot.Tests\bin\Debug\net10.0\Opc.Ua.Aot.Tests.exe
--treenode-filter
"/*/*/PubSubAotTests/SamplePublisherDeliversSecuredDataSetToSampleSubscriberAsync"`
(JIT), before the fix | Failed: `TimeoutException`, no DataSet within 10
s |
| same, after the fix | Passed, 3 of 3 runs |
| `tests\Opc.Ua.Aot.Tests\bin\Debug\net10.0\Opc.Ua.Aot.Tests.exe
--treenode-filter "/*/*/PubSubAotTests/*"` | 8 of 8 passed |
| The two `dotnet run` commands of the docs/PubSub.md first exchange,
run verbatim | 15 DataSets in 15 s; the publisher logs no failures |
The release/2.0 branch has the same sample and would need a backport,
which is not part of this PR.
## Related Issues
- No tracking issue. Found while re-verifying the documented first
PubSub exchange after the 2.0.0 release.
## Checklist
- [ ] I have signed the
[CLA](https://opcfoundation.org/license/cla/ContributorLicenseAgreementv1.0.pdf)
and read the
[CONTRIBUTING](https://github.com/OPCFoundation/UA-.NETStandard/blob/master/CONTRIBUTING.md)
doc.
- [x] I have added tests that prove my fix is effective or that my
feature works and increased code coverage.
- [x] I have added all necessary documentation.
- [x] I have verified that my changes do not introduce (new) build or
analyzer warnings.
- [ ] I ran **all** tests locally using the **UA.slnx** solution against
at least .net **framework** and .net **10**, and all passed.
- [ ] I fixed **all** failing and flaky tests in the CI pipelines and
**all** CodeQL warnings.
- [ ] I have addressed **all** PR feedback received.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Console Reference PubSub
A single, self-contained OPC UA Part 14 PubSub reference application built on the
fluent PubSubApplicationBuilder + dependency injection + .NET Generic Host surface.
One executable exposes three command-line-selectable modes, and publishes as a
NativeAOT-ready single-file executable.
Modes
ConsoleReferencePubSubClient <mode> [options]
| Mode | Purpose |
|---|---|
publisher |
Publishes a built-in sample DataSet over UDP/UADP or MQTT (UADP/JSON). |
subscriber |
Receives DataSets and logs each decoded message to the console. |
external |
Bridges an external OPC UA server to PubSub via the Opc.Ua.PubSub.Adapter library (publisher / subscriber / responder direction). |
publisher
ConsoleReferencePubSubClient publisher --profile udp-uadp --interval 1000
ConsoleReferencePubSubClient publisher --profile mqtt-json --endpoint mqtt://localhost:1883
Options: --profile udp-uadp|mqtt-uadp|mqtt-json, --config-file <xml>,
--publisher-id, --writer-group-id, --data-set-writer-id, --endpoint, --interval.
subscriber
ConsoleReferencePubSubClient subscriber --profile udp-uadp
Options: --profile, --config-file <xml>, --publisher-id-filter,
--writer-group-id-filter, --data-set-writer-id-filter, --endpoint.
Publisher and subscriber on one computer
The default UDP endpoint, opc.udp://239.0.0.1:4840, is a multicast address.
Multicast loopback is disabled by default, so a subscriber on the publisher's
computer can miss the messages. To run both on one computer, give both the
unicast loopback endpoint:
ConsoleReferencePubSubClient subscriber --profile udp-uadp --endpoint opc.udp://127.0.0.1:4840
ConsoleReferencePubSubClient publisher --profile udp-uadp --endpoint opc.udp://127.0.0.1:4840
See Run a first publisher and subscriber for the expected output and the settings that must match.
external
Bridges an external OPC UA server (defaults to the repository's ConsoleReferenceServer
at opc.tcp://localhost:62541/Quickstarts/ReferenceServer; override with --endpoint or
the OPCUA_EXTERNAL_ENDPOINT environment variable).
# Read an external server and publish its values (cyclic Read each cycle)
ConsoleReferencePubSubClient external --mode publisher --read-mode cyclic
# Read via a client Subscription cache, one subscription per WriterGroup
ConsoleReferencePubSubClient external --mode publisher --read-mode subscription --affinity writergroup
# Write received PubSub values back to an external server
ConsoleReferencePubSubClient external --mode subscriber
# Map an inbound PubSub Action to an external server method call
ConsoleReferencePubSubClient external --mode responder
# Run a bidirectional bridge in one process
ConsoleReferencePubSubClient external --mode publisher,subscriber
Options: --mode publisher|subscriber|responder (comma-separated list accepted),
--read-mode cyclic|subscription, --affinity writergroup|datasetwriter,
--endpoint <external server>, --pubsub-endpoint <udp url>, --hot-reload.
Hot reload
Add --hot-reload to the external bridge to run the opt-in live reconfiguration
demo:
ConsoleReferencePubSubClient external --mode publisher,subscriber --hot-reload
The bridge writes pubsub-config.xml next to the executable before starting and
loads adapter options from the copied appsettings.json in the same directory.
Edit and save either file while the bridge is running:
appsettings.json: changeExternalPublisher:ReadModefromCyclictoSubscription, or changeExternalPublisher:AffinitytoDataSetWriter, to rewire the external-server publisher options.pubsub-config.xml: add or remove aDataSetWriterto change the PubSub topology. The watching XML store raises a configuration change and the adapter incrementally rewires the affected binding.
The samples connect to the external server unsecured (
SecurityMode.None) for zero-config interop. A production bridge must useSignAndEncryptwith a provisioned application instance certificate. See docs/PubSub.md external-server adapter section.
Build / publish
dotnet build samples/PubSub/ConsoleReferencePubSubClient/ConsoleReferencePubSubClient.csproj
dotnet publish samples/PubSub/ConsoleReferencePubSubClient/ConsoleReferencePubSubClient.csproj -r win-x64
See docs/PubSub.md for the full PubSub guide.