mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-17 05:11:13 +08:00
romanett
36f51cb49d
# Description
The fluent builder resolves exactly **one node per call**.
`NodeFromTypeId` is exact-type-only and throws `BadBrowseNameDuplicated`
the moment two instances match, and handlers land in single-occupant
`NodeState` slots — a second handler for an occupied slot is an error by
design.
So the fluent surface cannot express four things:
- **fan-out** over the instances of a type,
- **subtype matching**, so a registration for `AnalogItemType` also
covers a user's derived type,
- **composition** of two behaviors on one node,
- **teardown** for a behavior that *owns* something — a semaphore, a
file handle, a store, a timer.
Three hand-rolled registries already work around exactly this —
`EventSourceRegistry` (730 lines), `MonitoredSourceRegistry` (998),
`SimulationRegistry` (328) — each with its own register → activate →
reconcile → deactivate → dispose loop and its own failure policy,
written three times because the slot model had no lifecycle to hang them
on.
This PR adds that lifecycle and moves the registries onto it.
## The new surface
Ten public members. A registration returns an `IAsyncDisposable` that
the node manager owns:
```csharp
builder.AttachToType<AlarmConditionState>(
ObjectTypeIds.AlarmConditionType,
async (alarm, ctx, ct) =>
{
MySubscription sub = await Source.SubscribeAsync(alarm, ctx.Lifetime).ConfigureAwait(false);
return sub; // released on teardown, in reverse order
});
```
- `AttachToType<TState>(NodeId, attach, NodeAttachOptions?)` — one
behavior per matching instance, subtypes included by default.
- `Attach<TState>(attach)` on a node builder — one behavior on an
already-resolved node.
- `Attach(attach)` on the manager builder — manager-scoped, owns no
node.
- `AcquireWhileMonitored<TValue>(acquire)` — acquire on the first
subscriber, release on the last **and at shutdown**.
- `INodeAttachContext`, `NodeAttachOptions`, and `protected
ActivateNodeBehaviorsAsync` on `FluentNodeManagerBase`.
**Guarantees.** Behaviors activate deepest node first, and on one node
from the base-registered behavior to the derived-registered one;
manager-scoped behaviors run last, so they can drive what the node
behaviors prepared. Any failure — including cancellation — unwinds every
lease recorded so far in **exact reverse order**, and aggregates cleanup
failures *with* the original rather than replacing it.
**The engine stays internal.** Its vocabulary is not worth freezing into
public API, and `INodeAttachContext` + `IAsyncDisposable` is the whole
contract a caller needs.
Two deliberate decisions worth a reviewer's attention:
- **Method nodes are excluded from type matching.** `MethodState`
aliases `MethodDeclarationId` onto `TypeDefinitionId`, so without an
explicit filter every method node would match a registration for its
declaration — a surprise nobody asked for. Method behavior stays on the
call handler. Pinned by a test.
- **A CLR type mismatch throws `BadTypeMismatch`**, naming node,
expected and actual type, rather than silently skipping the instance. A
whole set of alarms quietly getting no behavior is worse than a startup
failure.
`Dispose(bool)` is **signal-only**. Real release belongs in
`DeleteAddressSpaceAsync`, which `MasterNodeManager.ShutdownAsync`
invokes before it disposes managers on every production path — including
the synchronous one, where `StandardServer.Dispose` blocks on
`DisposeAsyncCore` → `StopAsync` → `ShutdownAsync` first. Blocking in
`Dispose(bool)` would sit under a sync-over-async dispose and
`MasterNodeManager`'s semaphore `Wait`.
## The registry migrations
**`SimulationRegistry` — release moved, plus two latent bugs.**
`Dispose` cancelled the loops then blocked up to five seconds draining
them, from a synchronous dispose. Release now runs on the async teardown
path and `Dispose` only trips the token. Loops are driven from the
server `TimeProvider` instead of `PeriodicTimer`/`Stopwatch`, so they
are testable on a fake clock rather than with sleeps. Fixed alongside:
the running loop enumerated the handler list **by reference** while a
late `OnTick` could still mutate it (handlers are now snapshotted, and a
late `OnTick` is rejected rather than silently dropped); and a handler
throwing `OperationCanceledException` for its own reasons killed the
whole loop in silence.
**`EventSourceRegistry` — ownership only; the reconcile loop stays.** It
cannot collapse: `OnSubscribeToEventsAsync` runs while the
monitored-item semaphore is held and `AddRootNotifierAsync` re-enters
`SubscribeToEventsAsync`, so awaiting anything lease-shaped from that
hook would self-deadlock. What moves is ownership of the two side
effects nothing reversed — the `EventNotifier` bit ORed into the
notifier, and the root-notifier registration. A node that *already*
carried the flag is not ours to clear, so only what registration
actually changed is recorded and undone.
**`MonitoredSourceRegistry` — ownership only, and the real leak.**
Rerouting teardown to `DisposeAsync` turned out to be necessary but
**not sufficient**: that method only clears the item map, cancels the
worker and disposes the lock, while the last-subscriber handler runs
*solely* from the reconcile path's `Deactivate` arm — which server
shutdown never reaches, because subscriptions dispose their items
locally without deleting them. Anything acquired on the first subscriber
therefore outlived the server. `ReleaseAsync` now runs those handlers
for still-active sources, and `AcquireWhileMonitored` is the demand verb
over the pair, with a test that proves release at shutdown with a live
subscription.
**Alarms.** Attaching an alarm enabled the condition, promoted the whole
notifier chain and registered a root notifier, with no inverse anywhere.
`RegisterAlarmEventSource` now reports what it changed and an
`AlarmRelease` behavior undoes it. While wiring that up: the parent's
`EventNotifier` was being promoted **twice** — once directly and once
inside `RegisterAlarmEventSource` — which left the reversible path with
nothing recorded. The redundant promotion is gone.
Alarms still work on managers that never opted into the fluent surface;
those simply get no automatic release, exactly as before, rather than a
hard failure.
## What this deliberately does not do
**Registry and alarm *setup* stays where it is.** Only release moved.
`NodeManagerBuilder.Seal()` is synchronous and is called from sites that
never call `CompleteConfigureAsync` — `Isa95NodeManager.cs:1046` seals
from inside `private void ConfigureStatusEvents()` — so making behavior
activation the sole setup path would silently disable simulations, event
sources and alarms in ISA-95, Pump, Generator and RuntimeNodeSet.
That same synchrony is what forced the `OnAddressSpaceReadyAsync` hook
in #4434 (*"`Configure` is a `partial void` and cannot await"*), which
`Opc.Ua.Di.Server/DiNodeManager.cs` had already invented privately. **A
separate PR making the fluent configure path async is planned to land
first**; after it, setup can move onto activation here and both copies
of that workaround can go.
Also out of scope: incremental attach on runtime node add and release on
node removal (the ledger needs real synchronisation first), and the
Quickstart `AlarmNodeManager` port that would give the alarm work
end-to-end coverage.
## Related Issues
No tracking issue yet — this came out of a design review of an earlier
behavior-activation prototype, which was rejected for being unreachable
from any application and hooked into a loading path rather than the node
manager. Happy to open one and link it if maintainers want the ADR on
file before review.
## 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. *(XML doc comments on
every new public member, including why method nodes are excluded and why
`Dispose` is signal-only. No `docs/` page — say the word if one is
wanted.)*
- [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. *(net10.0
only — see Validation. Not run against .NET Framework locally.)*
- [ ] I fixed **all** failing and flaky tests in the CI pipelines and
**all** CodeQL warnings.
- [ ] I have addressed **all** PR feedback received.
## Validation
net10.0:
- `UA.slnx` builds clean, 0 errors.
- `Opc.Ua.Server.Tests`: **4,984 passed, 0 failed**, 5 skipped.
- 23 new tests:
- **17 on the behavior surface** — child-first ordering,
base-before-derived on one node, exact-reverse unwind, fan-out over
three instances, subtype vs exact-type matching, zero-match diagnostics,
declined instances, mid-activation rollback, lifetime-token ordering,
second-pass unwind order, drained registrations, method-node exclusion,
alarm release, `Publish` release, `Dispose` tripping an activated
behavior's lifetime, and the two aggregation contracts (several release
failures all surface and do not stop the remaining releases; a rollback
that itself fails does not hide the activation failure that triggered
it).
- **4 on the simulation lifecycle** — fake-clock ticking, teardown
awaiting an in-flight tick, non-blocking `Dispose`, late-handler
rejection.
- **2 on `AcquireWhileMonitored`** — release on the last subscriber, and
release at shutdown with a live subscription.
- No new analyzer warnings.
Not run locally: .NET Framework targets, and suites outside
`Opc.Ua.Server.Tests`.
**On the advisory coverage gate.** The first report put patch coverage
at 47.65%, listing whole files as uncovered that these tests exercise
directly — `NodeBehaviorRegistry.cs` end to end, for instance. That
report is assembled from whichever legs published Cobertura fragments,
and the `Server` leg had not. It did point at three paths that genuinely
had no test, all now covered: `EventSourceRegistry.ReleaseAsync`,
`SignalShutdown` (reachable only via `Dispose` on a manager whose
behaviors actually activated), and the two failure-aggregation paths.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
OPC Foundation UA .NET Standard Reference Server
Additional samples
- OPC 10000-21 onboarding registrar/client — loads the generated Onboarding companion model, binds the standard registrar administration methods to an injected ticket store, and drives a secure register/unregister round trip with a PowerShell script.
Introduction
This document is referring to the CTT version 1.04.9.398.
This OPC Server is designed to be the default OPC UA Server when opening the OPC UA Compliance Test Tool and it uses an address-space that matches the design of the UACTT and the requirements for OPC UA compliance testing.
It uses the OPC Foundation UA .NET Standard Library. Therefore it supports both the opc.tcp and https transports. There is a .NET framework based server with UI and a .NET Core console version of the server which runs on any OS supporting .NET Standard 2.1 or .NET 8.0 and later.
How to build and run the Windows OPC UA Reference Server with UACTT
- Open the solution UA.slnx with Visual Studio 2026.
- Choose the project
Reference Serverin the Solution Explorer and set it with a right click asStartup Project. - Hit
F5to build and execute the sample.
How to build and run the console OPC UA Reference Server on Windows, Linux and iOS
This section describes how to run the ConsoleReferenceServer.
Please follow instructions in this article to setup the dotnet command line environment for your platform.
Start the server
- Open a command prompt.
- Navigate to the folder samples/Reference/ConsoleReferenceServer.
- To run the server sample type
dotnet run --project ConsoleReferenceServer.csproj. The server is now running and waiting for the connection of the UACTT.
UACTT test certificates
The reference server always rejects new client certificates and requires that the UACTT certificates are in appropriate folders.
- The console server certificates are stored in %LocalApplicationData%/OPC Foundation/pki.
- The Windows .NET framework server stores the certificates in %CommonApplicationData%\OPC Foundation\pki.
- %CommonApplicationData% maps to the path set by the environment variable ProgramData on Windows.
- %LocalApplicationData% maps to a hidden location in the user home folder and depends on the target platform. See Certificates for more information.
Certificate stores
Under pki, the following stores contain certificates under certs, CRLs under crl or private keys under private.
- own contains the reference server public certificate and private key.
- rejected contains the rejected client certificates. To trust a client certificate, copy the rejected certificate to the trusted/certs folder.
- trusted contains trusted client and CAs certificates and CRLs.
- issuer contains CAs certificates and CRLs needed for validation.
- trustedUser contains trusted user and user CA certificates and CRLs.
- issuerUser contains user CA certificates and CRLs needed for validation of the certificate chains.
Placing the UACTT certificates
CTT creates a PKI folder in a new project. There is a subfolder copyToServer which contains the application and user identity certificates. Copy the ApplicationInstance_PKI certificates for testing with the UACTT to the following stores:
- trusted/certs: trusted certificates
- trusted/crl: revocation lists of trusted certificates
- issuer/certs: issuer certificates
- issuer/crl: revocation lists of issuer certificates
Copy the X509UserIdentity_PKI certificates for testing with the UACTT to the following stores:
- trustedUser/certs: trusted user certificates
- trustedUser/crl: revocation lists of trusted user certificates
- issuerUser/certs: user issuer certificates
- issuerUser/crl: revocation lists of user issuer certificates
UACTT Testing
Download and install the OPC UA Compliance Test Tool.
Note: Access to the UACTT is granted to OPC Foundation Corporate Members.
UACTT sample configuration
A sample configuration for the UACTT Version 1.04.9.398 can be found in UAReferenceServer.ctt.xml. Originally the reference server was certified only against the Standard UA Server profile, the Method Server Facet and the DataAccess Server Facet, in addition to all security related profiles. During release testing all Conformance Units should be enabled / checked.
Enabling Alarms & Conditions
The address space for Alarms contains a Start method which needs to be called to produce alarms for CTT testing. The method is called from a connected client.
The ConsoleReferenceServer has also a command line option -ctt which starts the Alarms when the server is started. The following Alarm instances are available for monitoring:
AlarmConditionTypeDiscrepancyAlarmTypeLimitAlarmTypeExclusiveLimitAlarmTypeExclusiveDeviationAlarmTypeExclusiveRateOfChangeAlarmTypeNonExclusiveLimitAlarmTypeNonExclusiveDeviationAlarmTypeNonExclusiveRateOfChangeAlarmTypeDiscreteAlarmTypeSystemOffNormalAlarmTypeExclusiveLevelAlarmTypeNonExclusiveLevelAlarmTypeOffNormalAlarmType
Known missing Tests and Issues
Depending on the setup in the provided project configuration, unsupported profiles should be skipped. At the time of writing (1.4.368) the following tests, profiles or facets are not yet covered or not configured due to issues:
- no support for events, historian and only a few basic Alarms & Conditions.
- Decimal type causes crash of CTT (needs investigation)
- no Image / Enumeration scalar test cases
- Arrays may not include Variant (needs investigation)
- no ArrayItemType implemented
- multiple hierarchical references test node missing
- deprecated security profiles support for SHA1/1k RSA keys implemented not according to certification. SHA1/1k keys can only be turned on/off for all profiles, not just for the deprecated profiles.
- Monitored Items with array are failing a few test cases.
It is recommended to run the server as retail build with disabled logging, to avoid side effects due to timing artifacts when log entries are written to a disk drive.
Running the CTT against a Docker container
Please refer to the Docker container of the Reference Server documentation page. Once setup to map the certificate store and the configuration to a local folder, follow the instructions above to copy the certificates to the PKI and get started.
Finding the Address Space Configuration Code
- Project: Reference Server
- File: ReferenceNodeManager.cs
- Method: CreateAddressSpace
Finding the UA Services
- Project: Opc.Ua.Server
- File: StandardServer.cs