mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-22 01:26:20 +08:00
Marc Schier
a7c776e8d4
# Description Aligns the WoT implementation with the normative changes in the OPC UA WoT specification drafts that the stack had not picked up, and fixes the defects that alignment surfaced. The driving artifact is [OPCF-Members/spec-drafts#19](https://github.com/OPCF-Members/spec-drafts/pull/19), *"bind a projected node to an already-loaded type, by name or by NodeId"*, which landed on the spec `main` after this repository last tracked it. ## 1. Bind a projected node to an existing type (Binding §5.2.1) §5.2.1 lets a document state that the node it projects is an instance of a type that **already exists** — one a companion model defines and the Server has loaded, or one a sibling document of the same conversion defines — so a converter binds to that type instead of defining a second type of the same shape. The converter hardcoded `HasTypeDefinition` to `BaseObjectType`, so a document that named its type projected an **untyped** node: a client browsing for the companion type would not find it, and nothing said why. Both forms are now implemented, resolved against the §5.1.5 **local context** — the other documents being converted together first, a loaded AddressSpace as the fallback. `IWotNodeResolver` supplies that context (is a namespace held; what does a qualified BrowseName match; what does an ExpandedNodeId identify), `WotCompositeNodeResolver` composes implementations in the specified order, and `NullWotNodeResolver` is the default that holds nothing. The converter needed no new async surface: the binding is resolved in a pre-resolve pass, exactly as Thing references already are, and the synchronous core consumes the result. The §5.2.1 table is honoured: a unique name binds; the link settles an ambiguous name; a name that resolves to nothing while the link resolves is **invalid** (that is a mistake in the name, not a shorthand for the identifier); two forms resolving to different Nodes are invalid; a resolved type of the wrong NodeClass is invalid. A binding naming a type the local context does not hold **fails** rather than falling back to `BaseObjectType` — a silently mistyped node is worse than a reported failure. A compact name is told from ordinary `@type` annotation **by namespace**, not by whether the lookup succeeds, so `saref:TemperatureSensor` on a Server that has never heard of SAREF stays the annotation it always was. The definitive form — a `ua:HasTypeDefinition` link whose `href` is the ExpandedNodeId of the type. An ExpandedNodeId matches exactly one Node or none, so it needs no lookup. A Node has exactly one `HasTypeDefinition`, so: - two such links → `AmbiguousTypeBinding` (6019), and the root keeps the default rather than being bound to a guess; - a link with no usable identifier → `InvalidTypeBinding` (6020); - no binding at all → the `BaseObjectType` default is unchanged. ## 2. Drop the six vocabulary terms `#19` removed `#19` deleted `uav:capability`, `uav:componentModel`, `uav:reference`, `uav:congruentType`, `uav:congruentTypeName` and `uav:nameNamespace` from the context, the JSON Schema and the ontology. A link now names its ReferenceType directly in `rel`, so the three link relations become `ua:HasInterface`, `ua:HasComponent` and `ua:NonHierarchicalReferences`, and the congruent-type pair is superseded by the §5.2.1 type binding. Their validation and mapping are removed; they are now ordinary residue like any other unrecognised term. ### A real gap this uncovered The converter knew **eight** ReferenceTypes by name and had neither `NonHierarchicalReferences` (`i=32`) nor `HasInterface` (`i=17603`) — so the two relations that *replace* `uav:reference` and `uav:capability` could not resolve at all. That includes example 02, which this repository vendors as a golden asset and which `#19` rewrote to use them. Both are now in the map. `uav:congruentType` was also the only term that redirected one reference to another while resolving a link target, so `ResolveTargetNodeIdAsync` no longer needs a loop. It resolves once and reports an unresolved target; the resolution context is still entered and the bytes still counted, so the per-conversion document, depth and byte bounds are unchanged. ## 3. Reject an out-of-range event severity instead of clamping it `uav:severity` had grown in this implementation without being a specification term. Rather than drop it, it is proposed upstream in [OPCF-Members/spec-drafts#21](https://github.com/OPCF-Members/spec-drafts/pull/21), which defines it with an explicit rule: the value **shall** be in the OPC 10000-5 range 1..1000, and a consumer **shall not** silently clamp it. The implementation clamped, so a document asking for severity 5000 was accepted and published as 1000 — the mistake was hidden while what the author asked for was changed. An affordance carrying an out-of-range severity is now skipped, with the reason logged, and its half-built event type and `GeneratesEvent` reference are removed. ### Defect found while making that change The occurrence-time path read `ValidateSeverity(severity) ?? tag.Severity`. Because `ValidateSeverity(null)` returns the 500 default, it **never** fell back to the affordance's authored severity: an occurrence reported without a severity published 500 rather than the authored 900. Build-time validation and the occurrence-time choice are now separate methods. ## 4. Vendored examples and honest coverage claims Examples 21 and 22 were missing from the vendored golden assets. Converting example 22 is now the end-to-end check for §5.2.1 — the specification's own example rather than a fixture written to match the implementation. `docs/WotBindings.md` claimed ten of the eleven conformance units and silently omitted **WoT-ConditionMapping**, and said "twenty worked examples". The count is corrected, and WoT-ConditionMapping is now **covered** — see §5 below. ## 5. Alarms and Conditions (Binding §13) The last unclaimed conformance unit. A projected Condition event now derives from the ConditionType it names rather than from `BaseEventType`; falling back would lose the Condition state model entirely, leaving a Client unable to tell an alarm from an ordinary event. The two forms follow the hint-plus-pin pattern of §5.3: `uav:conditionTypeId` is definitive and wins, `uav:conditionType` is a readable hint resolved for the four ConditionTypes §13.1 scopes. An unpinned name outside that set is reported rather than guessed. Four conformance rules are enforced, each because breaking it yields a document a consumer can read but cannot act on: | Rule | Section | Diagnostic | | --- | --- | --- | | A Condition event declares `EventId` in its `data` | 13.3 | `ConditionEventIdMissing` | | `uav:conditionAction` is inside its closed set | 13.2 | `InvalidConditionAction` | | `uav:actsOn` names a Condition event in the same document | 13.4 | `InvalidConditionTarget` | | `Acknowledge`/`Confirm`/`AddComment` declare an `EventId` input | 13.4 | `ConditionActionInputMissing` | `Enable` and `Disable` act on the Condition instance rather than one occurrence and are deliberately exempt from the last rule, pinned by a negative test. Shelving, suppression, dialog conditions and `ConditionRefresh` stay out of scope, as §13.1 scopes the mapping. ## 6. The sibling half of the §5.1.5 local context `SnapshotWotNodeResolver` indexes the registry snapshot a conversion runs over and is wired into `WotNodeSetDocumentConverter`, so a document naming a type another document in the same registry projects resolves with no AddressSpace at all. Only Thing Models are indexed: a Thing Model projects a `UAObjectType` and is a valid target, a Thing Description projects an instance and never is. Identity comes from the new public `WotNodeSetConverter.TryDescribeProjectedType`, which applies exactly the rules the conversion uses, so an index entry and the projected node cannot drift apart. Ambiguity is preserved rather than resolved: two siblings sharing a qualified name yield both matches so the caller can report it. ## Deliberately not in this PR - **The AddressSpace-backed `IWotNodeResolver`.** The abstraction, the composite, the null default and the sibling-document implementation ship here; the AddressSpace-backed half needs a cached type-hierarchy walk behind a server `OperationContext` and follows separately. Until it exists a host gets the sibling context plus the null fallback, which reports a binding as unresolved rather than mistyping it. - **Two §5.2.1 obligations that need the address space**: not duplicating a mandatory instance declaration of the resolved type, and rejecting disagreement with an instantiated Thing Model. - **Connectivity §7.3 parent resolution.** Each is tracked; none is faked here. ## Related Issues There is no tracking issue: this came out of a spec-versus-implementation audit rather than a reported defect, and the driving artifacts are the two upstream spec PRs linked above. Happy to open one if maintainers prefer — the §5.2.1 follow-up in particular is worth an ADR, since the local-context resolver is a new injectable provider spanning two assemblies. ## Checklist - [x] 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. - [x] 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. ### Verification detail | | net10.0 | net48 | |---|---|---| | `Opc.Ua.Types.Tests` | 8573 / 8573 | 8555 / 8555 | | `Opc.Ua.WotCon.Tests` | 1075 / 1075 | 1075 / 1075 | Full `UA.slnx` build: **0 errors, 0 warnings** across all target frameworks, re-verified after `master` was merged into the branch. Every new test was mutation-verified: the type-binding tests against three mutations (revert to the hardcoded default, drop the ambiguity check, accept an empty `href`), the severity tests against reinstating the clamp, and the ReferenceType additions against removing them from the map. Each mutation failed the suite before the change was kept. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9e6a5abf-3299-4cd1-9855-010fedbf0ad8
OPC Foundation UA .NET Standard Reference Server
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/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