mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-25 20:00:31 +08:00
Marc Schier
2836da7ec8
# Description Correct ownership, endpoint validation, policy propagation, subscription delivery, file handling and generated-model behavior across the stack, tools and samples. Add focused regression tests and update the corresponding guides and sample documentation. ### Previously included corrections - Require an active, matching session to generate or access transient ResultTransfer file handles. Cover both sessionless generation and reads against a handle owned by an active session, using live session owners in the Machinery tests. - Keep physical filesystem operations within their configured mount and apply the same confinement checks throughout file operations. - Validate LDS semaphore paths consistently during server registration and registration-store maintenance. ### Individual issues addressed | # | Component | Issue and correction | |---|---|---| | 1 | AI jobs and transfers | Jobs and transfers did not consistently retain their creator's identity and session. Apply ownership checks to descendants, file handles, subscriptions and execution, and recheck deployment permissions before dispatch. | | 2 | Password-management client | Password-bearing calls could use signing-only channels or follow a replacement connection. Capture an encrypted transport generation and keep dispatch bound to it; preserve ordinary non-password edits. | | 3 | GDS and certificate-push clients | Connections omitted hostname verification. Validate the original configured DNS name or IP address before session activation. | | 4 | Certificate push | Private-key uploads could use signing-only calls. Require an encrypted, generation-bound dispatch while preserving certificate-only updates and restoring the caller's identity afterward. | | 5 | MQTT client | The .NET Framework custom-trust callback could discard TLS hostname, certificate-availability and usage errors. Retain those checks while supporting configured issuer trust. | | 6 | DTLS handshake | Certificate trust was not tied to the configured peer address. Match the certificate's DNS or IP identity to the intended endpoint. | | 7 | Replicated address spaces | Serialized nodes lost per-node and descendant permission metadata. Preserve role permissions, user-role permissions and access restrictions, including updates to existing replica nodes. | | 8 | MCP PubSub imports | Imports without groups skipped checks on the effective broker destination. Check the actual endpoint before resolving credentials or activating the connection. | | 9 | Reference-server accounts | A disabled username account could authenticate again with its previous roles. Reject disabled accounts during fresh authentication. | | 10 | Console reference client | The sample disabled hostname checks when connecting to an otherwise trusted peer. Retain the original requested host and validate it before activation. | | 11 | Capture replay and export | Replay and raw export could accept non-capture files or include key material. Require complete PCAP/PCAPNG containers and exclude key sidecars and decryption-secret blocks. | | 12 | PubSub adapter fallback | The fallback client configuration automatically accepted peer certificates. Apply normal trust and hostname validation before activation or reads. | | 13 | Kafka transport | Explicit TLS enablement was checked but did not reach both final Confluent configurations. Use the same effective protocol for validation, producers and consumers. | | 14 | PubSub actions | Configuration rebuilds could widen a connection-local action handler's scope. Preserve its original connection association and reject mismatched dispatch. | | 15 | PubSub readers | Reader-level message-protection settings were accepted but ignored. Apply the effective group and reader settings before accepting and publishing received values. | | 16 | PubSub key groups | Different `SecurityGroupId` values could share one connection-wide key context. Reject mixed groups on a connection and require separate connections for distinct groups. | | 17 | MCP session registrations | Session-name replacement or reuse could retain another registration's credential bindings. Bind access to the registration, caller and authenticated endpoint, and preserve that identity when borrowing sessions. | | 18 | Viewer HTTP host | Requests reached the viewer's OPC UA session without consistent Host, Origin and port checks. Validate the request destination and browser origin before using the session, while retaining supported local MCP clients. | | 19 | Vision file operations | File operations did not consistently apply protected-file checks, and remote handles lacked caller and connection context. Apply the shared checks and use host-side opaque handles bound to caller, target and generation. | | 20 | DTLS record integrity | The integrity-only MAC used a truncated sequence number. Authenticate the full reconstructed sequence number and epoch so records remain distinct across rollover. | | 21 | AMB client sample | Connection setup omitted hostname validation. Preserve the originally requested host and verify the peer identity before activation. | | 22 | Robot sample writes | The R2 `SpeedOverride` callback could target R1 state. Bind each callback to its own robot and apply that robot's write policy. | | 23 | AI result properties | Optional result children inherited remotely writable defaults. Preserve their declaration restrictions and keep server-produced results read-only. | | 24 | WSS peer-trust updates | Existing channels did not consistently respond to peer-trust changes. Revalidate complete chains for forward and reverse WSS channels and close only those that no longer validate. | | 25 | GDS revocation checks | Caller-provided certificates could cause issuer retrieval from embedded URLs. Resolve validation from configured local trust, issuers and CRLs without fetching caller-provided locations. | | 26 | GMS observations | Published correction observations retained writable model defaults. Reject remote writes while preserving publisher-side updates. | | 27 | Production-dataset monitoring | Subscription admission and delivery could use the reporter's context instead of each subscriber's permissions. Evaluate the subscriber at admission and on every delivery, including cancellation and disposal paths. | | 28 | WoT MQTT destinations | Hostless MQTT forms could imply a localhost destination before loopback checks. Reject them before credential lookup or connection attempts and validate the effective endpoint. | | 29 | XRegistry opaque reads | Content-ID reads and notifications did not consistently honor encrypted-read requirements or the currently accepted transport. Recheck the bound endpoint and reject transport downgrades before rebinding, including when protected values are already queued. | | 30 | PubSub capture dissection | Key loading did not consistently check the configured capture-root boundary. Check each actual key path immediately before opening it. | | 31 | PubSub publication queues | Imported WriterGroup queues were not fully checked against publish-topic grants. Check the destination actually used by each group. | | 32 | MCP PubSub mutations | A caller-supplied mode could select subscribe grants for an operation that publishes. Derive the required direction and parent context from the actual mutation. | | 33 | Generated write masks | Model import and generation could widen an explicit `UserWriteMask`. Preserve it through import, copy, merge, inheritance and dependency metadata. | | 34 | Generated method flags | An explicit `UserExecutable=false` could be lost. Preserve its specified state and resulting method behavior through the same model paths. | | 35 | Generated role identifiers | Unresolved role identifiers could cause permission entries to be omitted. Preserve namespace-qualified role IDs and report a diagnostic when a policy cannot be represented. | | 36 | Aggregation-server defaults | The `localhost` default did not reliably constrain listener binding. Use numeric loopback for the default endpoint and command-line fallback. | | 37 | Certificate-validation cache | Cached results could skip current leaf or issuer validity checks. Recheck validity windows on cache hits and keep hostname validation independent of cached chain trust. | | 38 | Software-update folders | Revision names and marker contents containing dot segments could select paths outside the software root. Normalize and check every derived path against that root. | | 39 | USDA arrays | Array elements were not encoded for their string or asset context. Escape them as data and preserve valid composition and round-trip behavior. | | 40 | Adapter hot reload | A changed dataset definition with the same name could keep old fields, subscriptions or cached values active. Compare complete immutable definitions and retire old state before replacement. | | 41 | Adapter index ranges | Subscription publication could ignore `IndexRange` and return the complete value. Preserve the requested projection and its status and timestamps; reject unsupported range providers. | | 42 | PubSub metadata and targets | Metadata from one connection could change another connection's target mapping. Scope metadata to its connection and provenance, and resolve targets using actual typed field IDs rather than field names or unintended positional fallback. | | 43 | Scales product locks | Product locks were not applied across every remote mutation path. Apply them consistently to value writes, filling calculations and related recipe/controller operations while retaining permitted updates. | | 44 | Event permission caching | Cached event decisions could outlive identity, role or node-policy changes. Revalidate the current subscriber, event type and source permissions instead of reusing a stale decision. | | 45 | WoT Modbus destinations | Hostless Modbus forms could imply localhost before loopback checks. Reject them before connecting and validate the effective endpoint. | | 46 | MCP local PKI tools | Peer-trust mutations did not consistently require the caller's `CertificateAdministration` grant. Check the capability before trust and untrust operations. | | 47 | Robot-control HTTP bridge | The bridge lacked consistent Host, Origin and port validation and caller-specific session grants. Apply those checks before borrowing the OPC UA session and retain supported local clients. | | 48 | Subscription transfers | Transferred subscriptions could retain cached notifications after the destination's permissions changed. Require authorization continuity between source and destination identities and roles, invalidate stale retransmission data when continuity fails, and preserve retransmission behavior for compatible transfers. | ### Compatibility notes - Replication uses the versioned NSRP v1 policy envelope. Upgrade peers together and re-encode or reseed legacy topology from the authoritative model; missing permission metadata is not inferred from old records. - Integrity-only DTLS peers must be upgraded together for the full sequence/epoch MAC. AEAD behavior is unchanged. - Distinct PubSub key groups require separate connections. - Custom sessions that cannot capture the actual encrypted transport, and subscription providers that cannot honor a requested range, are rejected rather than silently changing the requested behavior. - Subscription transfers retain retransmission data only when the destination authorization remains compatible with the source snapshot; otherwise the old sequence numbers and cached data are invalidated. ## Related Issues No separate tracking issue is linked. The individual corrections are listed above. ## Checklist _Put an `x` in the boxes that apply. You can complete these step by step after opening the PR._ - [ ] 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. - [ ] 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.
OPC UA .NET Standard stack documentation
These guides lead from a first working application to advanced and experimental capabilities. Follow the numbered stages when you are learning. Choose only the paths that match your application, or use the contents list to find a feature.
- New to the SDK? Start with Getting started, read OPC UA concepts, then build your first information model.
- Upgrading from 1.5.x? Read What's New in 2.0, then follow the Migration Guide.
- Contributing to this repository? See Contributing and maintaining the SDK.
Contents
- How to use this index
- 1. Get started
- 2. Build your application
- 3. Add data types and application services
- 4. Use companion models
- 5. Prepare for production
- 6. Advanced integration, reliability, and scale
- 7. Draft and experimental capabilities
- Reference and upgrade
- Contributing and maintaining the SDK
How to use this index
Each stage builds on the earlier ones, but you do not need to read every guide. After stage 1, choose the client, server, or PubSub path. Stages 3 to 7 are optional; use the guides your application needs. A stage or group names the knowledge it assumes.
Labels describe the maturity of a package or model:
- Preview package: the package family keeps a
-previewversion, even when the core packages are stable. See Versioning. - Draft model: the guide implements a working-group draft specification. Its namespace URIs and NodeIds are provisional.
- Experimental: the guide marks the feature as experimental.
These labels are independent of difficulty. An advanced guide can describe a stable feature, and a released specification can ship in a preview package.
1. Get started
Run a client and server, then learn the terms that the other guides use.
- Getting started — run the minimal samples, or build a client and server from NuGet packages.
- OPC UA concepts — applications, endpoints, sessions, the address space, values, subscriptions, and PubSub.
- Your first information model — add a model to the Getting started server, then read, write, and call it from the client.
- Sample catalogue — minimal, reference, PubSub, and companion-model applications.
- Packages and supported platforms — choose packages and target frameworks.
2. Build your application
Choose the path for your application. The paths are independent: for example, a PubSub application needs neither a client nor a server.
Client path
Assumes Getting started.
- Dependency injection: client feature — configure a client in the .NET Generic Host.
- Managed sessions — connect, recover from connection loss, and close. To compare the managed and classic session APIs, see choosing a session API.
- Read, write, and call methods — resolve namespace URIs and browse paths, check the status of each operation, and call methods through a client generated from the model.
- Subscriptions — callback subscriptions for long-lived monitoring and streams for short observations.
- Generation-bound requests — retain remote file handles, history cursors and target classifications without following a replacement connection.
Server path
Assumes Getting started.
- Dependency injection: server feature — host a server and configure its endpoints, security, and node managers.
- Node managers: start with a model — generate a node manager from your model and attach callbacks. Complete method invocation results covers ordered output values and resolved operation/input diagnostics. Your first information model is a complete example.
- Runtime NodeSets — load NodeSet2 models without generated code when models change independently of your application.
- Asynchronous server support — implement service and node-manager callbacks asynchronously.
PubSub path
A PubSub application needs neither a client nor a server, so the Getting started exercise and the other two paths are optional here.
- Concepts: client/server and PubSub — publishers, subscribers, and datasets.
- Run a first publisher and subscriber — exchange signed and encrypted messages on one computer with the reference PubSub sample.
- PubSub guide — the fluent builder, hosting, configuration, encodings, and security.
- Transport selection — UDP, Ethernet, MQTT, and Kafka.
3. Add data types and application services
Assumes the client or server path. Choose the capabilities your application needs.
Data types and models
- Source-generated data types — generate encodeable implementations for your own structures.
- Complex types — decode server-defined structures and enumerations at run time.
- Model dependencies — compose models that depend on other models.
- NodeId assignment — control the identifiers of nodes created at run time.
- Schema generation — produce XSD, BSD, and JSON schemas for data types.
Application services
- State machines — define, drive, and observe state transitions.
- Programs — host and control Part 10 invocations, monitor captured transition results, and manage diagnostics and lifetime.
- Alarms and conditions — raise, acknowledge, and stream alarms. Alarm conditions use state machines, for example for shelving.
- Historical access — store and read value and event history.
- Aggregates — calculate processed history; read historical access first.
- File system client — transfer files through the standard file objects.
- Alias names — find nodes through named aliases.
- Node management — let clients add and delete nodes and references.
- Final-value publication — await terminal Value notifications in real Publish responses before removing dynamic subtrees.
- Model change tracking — keep client caches current when the address space changes.
- NodeSet export — export a server's address space to NodeSet2 XML.
4. Use companion models
Companion specifications define models for particular industries and device types; Concepts explains how they relate to the base model. These libraries assume the server path and, for typed client access, the client path. The packages load the models that each model depends on.
- Device Integration (OPC 10000-100) — devices, topology, and locking.
- Asset Management Basics (OPC 10000-110) — make devices, machines, pumps or scales manageable assets: discovery, identification, health alarms, maintenance, documentation links and locations. Read Device Integration first.
- Software update (OPC 10000-100) — software package storage, installation, and confirmation. Read Device Integration first.
- ISA-95 (OPC 10030 and OPC 10031-4) — the common model and job control.
- Positioning (OPC 10000-210 and OPC 10000-211; preview package) — relative frames and geographic positions.
- Machinery (OPC 40001-1, -2, -3, -4 and -101) — machines with identification, server-driven state machines, process values, job management, energy and result transfer, based on the Industrial Automation, Device Integration, PA-DIM, ECM and ISA-95 models.
- Pumps (OPC 40223) — pumps and vacuum pumps, published both as Device Integration devices and as Machinery machines.
- AutoID Devices (OPC 30010) — RFID, OCR, optical, optical verifier and RTLS readers: model, server hosting with a provider contract for the reader hardware, typed client, MCP tools and a simulated RFID reader sample, based on the Device Integration model.
- Machine Vision (OPC 40100-1 and OPC 40100-2) — released control, recipes, configurations, results, assets, and condition monitoring, with Vision/Perception composition and Machinery hosting.
- MachineTool and wireless peripherals (OPC 40501-1 and OPC 40505) — machine monitoring, tools, production/jobs/files and independently hosted wireless measurements, configuration and records in one package family.
- Geometric Measurement Systems (OPC 40210) — native measurement equipment, qualification/calibration, production observations and results. The guide documents the upstream undefined Production-statistics CU exception.
- Cranes and Hoists (OPC 40020-1; preview packages) — Robotics-derived crane systems, equipment observations and explicitly authorized speed-limit requests.
- Scales (OPC 40200 and OPC 30050) — weighing technology with every scale kind, scale systems, recipes and PackML state machines, based on the Machinery model.
- Plastics and rubber capabilities (OPC 40083 and OPC 40082-6) — shared machine configuration, control and monitoring, with production dataset transfer and granulate drying.
- Extrusion (OPC 40084-1 through -12) — the extrusion line and its device families, optional capabilities, typed clients and composition.
- Robotics (OPC 40010-1; preview package) — motion-device systems, based on the Industrial Automation and Device Integration models. The guide's draft Robot Intent model is listed in stage 7.
- WoT connectivity (OPC 10100-1; preview package) — connect Web of Things assets. Its registry extension is listed in stage 7.
For more examples, including the Pumps and Machinery models, see the companion-model samples. The generic recycling simulation combines a causal production model with separately hosted process views; its guide identifies the remaining companion integration limits. The optional recycling operator console adds a local ASP.NET Core 10 browser schematic, strict UA trust and role-limited commands; its guide covers standalone and Compose setup, image publication and the synthetic sample's operational/security limits.
To expose these typed client interfaces to an agent, use the industrial companion MCP tools. Select one family or compose several profiles without enabling the entire tool catalog. The WoT and xRegistry profiles cover asset/registry management and document conversion; the document profile does not require a UA connection.
5. Prepare for production
Builds on the certificate trust you used in Getting started. Before you deploy a client or server, work through the production readiness checklist. It links to these guides for the details:
- Certificates — certificate stores, trust, and chain validation.
- Identity providers — authenticate users on clients and servers.
- Role-based user management — map identities to roles and permissions.
- Certificate manager — certificate lifecycle, rotation, and remote updates.
- Diagnostics — logging, metrics, tracing, auditing, and packet capture.
- Rate limiting — admission limits and busy signals during connection storms.
- Server resource isolation — per-caller limits and reserved capacity for startup and recovery.
- Profiles and facets — implemented profiles and platform boundaries.
- Container reference server — run the reference server in a container.
6. Advanced integration, reliability, and scale
Each group names the stages it assumes.
Transports and integration
Assumes the client or server path.
- Transports — UA-TCP, HTTPS, and WebSocket transports.
- REST binding — OpenAPI mapping, encoding negotiation, and HTTP authentication.
- OPC UA over OpenAPI — serve the OpenAPI document the stack generates from its REST routes and call the server from generated REST clients.
- Reverse Connect — server-initiated connections.
- Session-less invocation — let clients call Read, Browse, Call and the other §6.3 Services without a Session.
- PubSub external-server adapter — bind PubSub to an OPC UA server through a managed client session. Assumes the client and PubSub paths.
- PubSub transcoding — convert encodings, values, and metadata between PubSub messages.
- MCP server — let AI agents browse, read, write, and diagnose OPC UA servers. Stack workflow profiles add GDS/credential issuance, roles/users, files, alarms, history, schemas, policy-controlled PubSub and live WoT execution.
- WoT / NodeSet conversion and WoT protocol bindings — convert Thing Descriptions and add protocol bindings. Read WoT connectivity first.
Session recovery and performance
The subscription guides assume the client path; the sizing guides assume Diagnostics.
- TransferSubscriptions — move server subscriptions to a new session.
- Durable subscriptions — keep subscriptions and queued notifications while clients are disconnected.
- Generation-bound session clients — capture dispatch, session identity and mapping snapshots without reconnecting to a replacement peer.
- Server scalability — sizing limits and bottlenecks.
- Benchmarks — measured performance and methodology.
Security infrastructure and fleet management
Assumes stage 5.
- ECC profiles — elliptic-curve security policies and their platform requirements.
- Crypto providers — replace the platform cryptography and keep private keys in hardware.
- Provisioning mode — configure a new server securely before exposing application data.
- Global Discovery Server — application registration and central certificate management.
- GDS sample — a runnable onboarding workflow.
- AuthorizationService — issue access tokens.
- KeyCredentialService — manage credentials for services that are not OPC UA. Its issued-token bridge is listed in stage 7.
High availability and deployment
Assumes a working single server and stage 5.
- High availability (preview package) — redundancy, failover, and distributed state.
- Replica-consistent NodeIds (preview package) — keep node identifiers identical across replicas; required before replicating an address space.
- Kubernetes (preview package) — cluster deployment, discovery, readiness, and secrets. Read high availability first.
- PubSub high availability (preview package) — redundant publishers and subscribers. Assumes the PubSub path.
Native AOT publishing
Publish an application as a native executable without a JIT compiler; start with Native AOT: publish an application. Feature-specific guidance:
- Servers with generated node managers
- Applications hosted with dependency injection
- PubSub applications
7. Draft and experimental capabilities
These guides implement working-group drafts or experimental extensions. Namespace URIs, NodeIds, and APIs can change before the specifications are published, so evaluate them before you depend on them in production. Each guide describes its current limitations.
- xRegistry (draft model; preview package) — the generic registry base model, resource storage, and federation.
- AI model management (draft model; preview package) — model catalogues, deployments, inference, and learning jobs. Builds on xRegistry.
- Perception model (draft model; optional OpenUSD renderer is preview-only) — capture, media, feedback, and client workflows.
- Robot Intent (draft model; preview package) — task-level motion commands. Does not require the Robotics model.
- OpenUSD (draft models; preview package) — bind values to OpenUSD scenes and materialize scenes in the address space.
- WoT Connectivity registry (draft model; preview package) — hosting, document provisioning, and refresh.
- WoT-Con 1.02 compatibility — existing-type bindings, declarations, and original document preservation.
- WoT design and provider contracts — exact-Version dependencies and leases, prepared storage/publication, and recovery.
- KeyCredential issued-token bridge (experimental).
These samples combine several draft or preview capabilities. Read the guides for their models first:
- Bin picking cell — Robot Intent, Vision, and an OpenUSD scene.
- Visual inspection cell — Vision, AI model management, and ISA-95 job control.
- WoT aggregation sample — load Device Integration, Machinery, and Pumps models from WoT documents through the WoT Connectivity 1.1 registry, and bind them to two OPC UA source servers.
- Generator sample model (draft model) — generating-set simulation and scene composition.
Reference and upgrade
- What's New in 2.0 — a summary of new capabilities.
- Migration Guide — upgrade from 1.5.378, with topic-specific 2.0 guides and PubSub migration.
- Reference client — command-line configuration and transport profiles.
- Reference server — hosting and compliance-test setup.
- Reference PubSub client — publisher, subscriber, and external-adapter modes.
The Windows Forms reference applications are maintained in the Samples repository.
Contributing and maintaining the SDK
These documents describe building and maintaining this repository, not using the SDK in an application:
- Developer Guide — prerequisites, build, tests, and coding conventions.
- Continuous integration — pipelines and coverage gates.
- Native AOT test harness — build, run, and extend the Native AOT compatibility tests.
- Release process — release branches, versioning, backports, and recovery.
- Redundancy sample tests — process-level failover and soak validation.
- Fuzz testing — encoder, certificate, and network campaigns.