mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-21 09:06:37 +08:00
Marc Schier
c4e0721a29
## Summary
### Documentation
- Stage the documentation index as a learning path: a first application,
independent client, server, and PubSub paths, then data and services,
companion models, production, advanced integration, and draft or
experimental capabilities.
- Add Getting started (repository samples or NuGet packages), OPC UA
concepts, Your first information model, and a production readiness
checklist.
- Add Native AOT application publishing, a first PubSub publisher and
subscriber exchange, and the UDP transport options.
- Add or expand contents navigation throughout `docs/`, and keep
contributor documentation separate.
- Correct outdated SDK examples and capability guidance, consolidate
repeated explanations into canonical guides, and repair local links and
heading structure.
- Rewrite What's New in 2.0 as a concise feature overview with short
linked details; keep migration instructions in the Migration Guide.
- Expand the feature catalogue with specification IDs, GDS, LDS, the OPC
10000-21 onboarding registrar, ISA-95, xRegistry, OpenUSD, and
sample-local models; distinguish draft status, explain crypto
pluggability, and bring performance guidance forward.
- Address review feedback on wording, active monitored items during
shadow reload, and the `Samples.md` filename and references.
- Regenerate the `opcua-v20-migration` plugin's bundled copy of the
migration guides so it matches the edited `docs/migrate/2.0.x` guides.
- Merge the latest `master`, preserving upstream resource-isolation
guidance within the task-based documentation index.
- Retain deferred Lingity findings where appropriate; this PR does not
claim that every document meets the Lingity score thresholds.
### Fixes found while verifying the guides
Each fix has regression tests that fail without it.
- **Client:** V2 subscriptions compared their lifetime with the
operation timeout instead of the session timeout, and logged a spurious
warning. `ISubscriptionEngineContext`, which is new in 2.0, gains a
`SessionTimeout` property; implementations must add it.
- **PubSub:** a subscriber now registers the `DataSetMetaData`
configured on its readers (OPC 10000-14 6.2.9.4), and the UADP decoder
decodes DataSetMessages that carry no ConfigurationVersion. Before, a
secured subscriber of the reference sample received no DataSets.
- **Source generator:** a ModelDesign method that declares its arguments
inline, without a method type, produced code that did not compile; it
now uses `MethodState`. The generated code of existing models is
unchanged.
- **MinimalClient sample:** waits for its first data-change notification
before it disconnects.
### Known issues, not addressed here
- UDP multicast: the publisher does not send on the interface that the
subscriber joins, and `MulticastLoopback` defaults to false. The PubSub
guide uses unicast for the exchange on one computer.
- The UDP metadata announcement is sent unsecured on secured writer
groups; a secured subscriber drops it with a warning.
- A server does not start in globalization-invariant mode, because
`ResourceManager` creates `CultureInfo("en-US")`. The Native AOT guide
cautions against the mode.
## Validation
- `git diff --check` and
`./.azurepipelines/validate-migration-plugin.ps1` (15 bundled migration
docs validated, plugin manifests synchronized).
- Local Markdown links, anchors, file-link casing, and contents lists
checked across all 87 documents under `docs/`. The index links every
top-level guide and every target of the previous index.
- Both Getting started routes, Your first information model, the PubSub
exchange, and the Native AOT publish of the Getting started client and
server were run as documented. The NuGet route and the tutorial use the
public `2.0.0-preview.5` packages.
- The changed libraries build for all target frameworks in Release
without warnings.
- Tests on .NET 10: Opc.Ua.SourceGeneration.Tests 199 passed;
Opc.Ua.SourceGeneration.Core.Tests 3,977 passed, 8 skipped;
Opc.Ua.Server.Tests `Fluent` category 621 passed; Opc.Ua.Client.Tests
subscription-engine tests 70 passed; Opc.Ua.PubSub.Tests 1,374 passed, 2
skipped; PubSub fuzz replay 145 passed. The new and affected tests also
pass on .NET Framework 4.8.
- Earlier merge validation: 174 resource-isolation tests passed on .NET
10.
- The full solution suite was not run locally.
Review and validation artifacts are maintained outside the repository.
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
114 lines
4.6 KiB
Markdown
114 lines
4.6 KiB
Markdown
# 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`
|
|
|
|
```bash
|
|
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`
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](../../../docs/PubSub.md#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).
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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`: change `ExternalPublisher:ReadMode` from `Cyclic` to
|
|
`Subscription`, or change `ExternalPublisher:Affinity` to `DataSetWriter`, to
|
|
rewire the external-server publisher options.
|
|
- `pubsub-config.xml`: add or remove a `DataSetWriter` to 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 use `SignAndEncrypt` with a provisioned
|
|
> application instance certificate. See
|
|
> [docs/PubSub.md external-server adapter section](../../../docs/PubSub.md#binding-pubsub-to-an-external-opc-ua-server-client-session-adapters).
|
|
|
|
## Build / publish
|
|
|
|
```bash
|
|
dotnet build samples/PubSub/ConsoleReferencePubSubClient/ConsoleReferencePubSubClient.csproj
|
|
dotnet publish samples/PubSub/ConsoleReferencePubSubClient/ConsoleReferencePubSubClient.csproj -r win-x64
|
|
```
|
|
|
|
See [docs/PubSub.md](../../../docs/PubSub.md) for the full PubSub guide.
|