mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-18 22:55:08 +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>
100 lines
6.3 KiB
Markdown
100 lines
6.3 KiB
Markdown
# TransferSubscriptions
|
|
|
|
## Contents
|
|
|
|
- [Overview](#overview)
|
|
- [Porting an existing server](#porting-an-existing-server)
|
|
- [Known limitations and issues](#known-limitations-and-issues)
|
|
- [Recovering from unsolicited `Good_SubscriptionTransferred`](#recovering-from-unsolicited-good_subscriptiontransferred)
|
|
- [Caveats](#caveats)
|
|
|
|
## Overview
|
|
|
|
`TransferSubscriptions` moves existing server subscriptions to another session.
|
|
It can reduce data loss during reconnect or client restart by preserving the
|
|
server's monitored items and queued notifications. It does not guarantee zero
|
|
loss: subscription lifetime, queue capacity, retransmission availability, and
|
|
authorization still apply.
|
|
|
|
The server and client implement the
|
|
[Part 4 TransferSubscriptions service](https://reference.opcfoundation.org/Core/Part4/v105/docs/5.14.7).
|
|
The target session must have permission to transfer the subscriptions. Transfer
|
|
also relies on the server's `GetMonitoredItems` method when the client needs to
|
|
recover monitored-item handles.
|
|
|
|
For current client APIs:
|
|
|
|
- Use [ManagedSession recovery](Sessions.md#reconnect-semantics-on-managedsession)
|
|
for connection recovery; do not add `SessionReconnectHandler` around a
|
|
`ManagedSession`.
|
|
- Use [subscription persistence and transfer](Subscriptions.md#persistence-save--load)
|
|
to save client state and restore it after restart. A transfer attempts to
|
|
recover an existing server subscription; recreating one starts new queues.
|
|
- If subscriptions must survive a deliberate session close, configure
|
|
`DeleteSubscriptionsOnClose = false` before closing it. They remain subject to
|
|
their server-side lifetime; this does not make them durable across server restart.
|
|
See [durable subscriptions](DurableSubscription.md) for that separate capability.
|
|
|
|
## Porting an existing server
|
|
|
|
Servers based on `StandardServer` and the built-in node-manager bases already
|
|
participate in monitored-item transfer. A custom manager implementing the
|
|
interfaces directly must implement the transfer contract, including initial-value
|
|
queuing when requested, without retaining stale source-session ownership.
|
|
See [node managers](NodeManagers.md) and the
|
|
[2.0 session/subscription migration guide](migrate/2.0.x/sessions-subscriptions.md).
|
|
|
|
Transfer support was introduced in 1.4.368. The
|
|
[historical sample port](https://github.com/OPCFoundation/UA-.NETStandard-Samples/pull/267/commits/5d990b7f39880941a5e788d17b903fd41254a804)
|
|
is relevant only when upgrading from releases predating that support; it is not
|
|
the current SDK API reference.
|
|
|
|
## Known limitations and issues
|
|
|
|
- Transfer cannot recover samples already lost to queue overflow or expired
|
|
subscriptions.
|
|
- Server restart requires server-side durability or mirroring to retain the
|
|
subscription; saving client configuration alone is insufficient.
|
|
- Recovery from an unsolicited transfer notification is an explicit compatibility
|
|
policy, described below, not a substitute for legitimate cross-session transfer.
|
|
|
|
## Recovering from unsolicited `Good_SubscriptionTransferred`
|
|
|
|
Per [OPC UA Part 4 §5.14.7](https://reference.opcfoundation.org/Core/Part4/v105/docs/5.14.7) the server emits a `StatusChangeNotification` with `Good_SubscriptionTransferred` on the **old** Session whenever the subscription is transferred away to a **new** Session via `TransferSubscriptions`. The receiving Session is expected to treat the subscription as gone and stop dispatching for it.
|
|
|
|
Some servers have been observed to deliver this notification against a subscription the client has just **freshly created** on its current Session — for example, Kepware after a server re-initialisation can leak the pre-restart subscription's pending status notifications onto the new session (especially noticeable because subscription identifiers are re-used starting at `1`). The client then sees the per-subscription dispatch silently disabled even though, from its point of view, the subscription is alive and should keep receiving data. Tracked as issue [#3540](https://github.com/OPCFoundation/UA-.NETStandard/issues/3540).
|
|
|
|
To opt into automatic in-place recovery, set `SubscriptionRecoveryPolicy.RecreateOnUnsolicitedTransfer`:
|
|
|
|
```csharp
|
|
// Classic (V1) subscription
|
|
var subscription = new Subscription(telemetry, options)
|
|
{
|
|
RecoveryPolicy = SubscriptionRecoveryPolicy.RecreateOnUnsolicitedTransfer,
|
|
FastDataChangeCallback = OnDataChange
|
|
};
|
|
```
|
|
|
|
```csharp
|
|
// V2 subscription options
|
|
var options = new Opc.Ua.Client.Subscriptions.SubscriptionOptions
|
|
{
|
|
PublishingEnabled = true,
|
|
RecoveryPolicy = SubscriptionRecoveryPolicy.RecreateOnUnsolicitedTransfer
|
|
};
|
|
```
|
|
|
|
When the policy is `RecreateOnUnsolicitedTransfer` and a `Good_SubscriptionTransferred` arrives while the subscription is still actively owned by this Session, the SDK will:
|
|
|
|
1. Drop every queued acknowledgement targeting the dead subscription id — this prevents `BadSubscriptionIdInvalid` ack errors on servers that re-use subscription identifiers across generations.
|
|
2. Recreate the subscription on the **same** Session via `CreateSubscription`, obtaining a fresh server-side subscription identifier.
|
|
3. Re-issue the monitored items so the data flow resumes against the new identifier.
|
|
|
|
The default is `SubscriptionRecoveryPolicy.ReportOnly`, which preserves the spec-strict behaviour: the `PublishStateChangedMask.Transferred` flag is raised (V1) or `PublishState.Transferred` is dispatched (V2) so the application can react manually, and the per-subscription publish dispatch is stopped (V1) or left as a no-op (V2).
|
|
|
|
### Caveats
|
|
|
|
* Auto-recovery is **not** lossless failover. The server-side retransmission queue and any triggering relationships tied to the invalidated subscription identifier are lost; only the subscription's wire-level options and the configured monitored items are re-applied.
|
|
* The recovery path runs against the same Session. If the Session itself is reconnecting, the V1 implementation defers to the reconnect pipeline rather than racing it; the V2 implementation lets the in-place recreate run when the subscription is `Created`.
|
|
* The "unsolicited" classification is conservative — concurrent recovery dispatches collapse into one — but it does not attempt to detect every legitimate cross-session/cross-client failover. If your design relies on another Session/Client legitimately pulling subscriptions away via `TransferSubscriptions`, keep the default `ReportOnly` policy and handle the `PublishStatusChanged` event explicitly.
|