mirror of https://github.com/OPCFoundation/UA-.NETStandard.git synced 2026-10-17 05:11:13 +08:00

Files

T

Marc Schier c4e0721a29 Add a documentation learning path and fix issues found while verifying it (#4555 )

## 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>

2026-09-28 19:19:39 +00:00

5.6 KiB

Raw Blame History

Container support and remote debugging for Reference Server

Overview

Run the Reference Server in a Docker container using a published image or a local build:

Pull the latest or a release image from the GitHub Container Registry. These images support Linux targets.
The image supports amd64 and arm64. The sample builds inside a container, so you do not need to install the .NET SDK. This change was introduced in this commit.
Build locally with Docker Desktop on Linux or Windows. Docker Desktop settings select the target container OS.
Visual Studio 2019 and later include container support, but issues in the UA Reference solution currently prevent build, startup, or connection.
Visual Studio 2022 supports native debugging of a Linux distribution through WSL.

Overview
Other published sample images
Building the local containers
Run the reference server container
- Run the local build of the Docker container
- Run the prebuilt Docker container hosted on GitHub
Known limitations and issues

Other published sample images

The Images CI workflow builds and publishes the sample images below to the GitHub Container Registry (ghcr.io/opcfoundation/uanetstandard/<image>). It builds each image for linux/amd64 and linux/arm64.

Image	Sample application
`refserver`	`samples/Reference/ConsoleReferenceServer`
`ldsserver`	`samples/Lds/ConsoleLdsServer`
`boilerserver`	`samples/MinimalApi/MinimalBoilerServer`
`calcserver`	`samples/MinimalApi/MinimalCalcServer`
`mcpserver`	`tools/Opc.Ua.Mcp`
`redundantserver`	`samples/Redundancy/RedundantServer`
`redundantclient`	`samples/Redundancy/RedundantClient`
`redundantpubsub`	`samples/Redundancy/RedundantPubSub`
`pubsubclient`	`samples/PubSub/ConsoleReferencePubSubClient`
`pumpserver`	`samples/DI/PumpDeviceIntegrationServer`

Image tags follow the release-branch-only publication model:

Stable tags include <image>:latest, <image>:release, and version tags such as <major>.<minor> and <major>.<minor>.<patch>. Update them only from a stable commit on a canonical release/<major>.<minor> branch (see Release process). A preview build (-preview.N) does not move these tags.
<image>:latest-<branch> (for example refserver:latest-master) tracks the most recent development build on that branch. Images CI builds these from master and from release/* branches while they are pre-release.
<image>:<version> (for example refserver:2.0.0-preview.6 or refserver:2.0.0) identifies the exact package version used to build the image, on any branch.

For example, pull the most recently approved stable Lds server image with:

docker pull ghcr.io/opcfoundation/uanetstandard/ldsserver:latest

Pull the most recent development build with:

docker pull ghcr.io/opcfoundation/uanetstandard/ldsserver:latest-master

Each application folder contains a Dockerfile. Build it from the repository root so the build can use the repository as context, for example:

docker build -f samples/Lds/ConsoleLdsServer/Dockerfile -t opcua-lds-server .

Building the local containers

Open a command prompt which can execute docker commands.
Navigate to the folder samples/Reference/ConsoleReferenceServer.
Build the docker container by executing the command dockerbuild.cmd.

On Linux,

Open a shell which can execute docker commands.
Navigate to the folder samples/Reference/ConsoleReferenceServer.
Build the docker container by executing the command ./dockerbuild.sh.

Run the reference server container

Run the container in interactive mode with the host's hostname. The certificate store, log output, and configuration file (when you use -s) are mounted in ./OPC Foundation.

The container uses these paths by default:

Certificate store: ./OPC Foundation/pki
Log file: ./OPC Foundation/Logs
Shadow configuration: ./OPC Foundation/Quickstarts.ReferenceServer.Config.xml

With -s, the container first copies the configuration file to the mounted folder. On later restarts, the server reads this copy, so you can change the settings there.

Run the local build of the Docker container

To run the local containers, batch files are provided called dockerrun.bat for Windows and dockerrun.sh for Linux.

Run the prebuilt Docker container hosted on GitHub

On Windows, open a command prompt and execute the following commands:

docker pull ghcr.io/opcfoundation/uanetstandard/refserver:latest
docker run -it -p 62541:62541 -h %COMPUTERNAME% -v "%CD%/OPC Foundation:/root/.local/share/OPC Foundation" ghcr.io/opcfoundation/uanetstandard/refserver:latest -c -s

On Linux, execute the following commands in a shell:

sudo docker pull ghcr.io/opcfoundation/uanetstandard/refserver:latest
sudo docker run -it -p 62541:62541 -h $HOSTNAME -v "$(pwd)/OPC Foundation:/root/.local/share/OPC Foundation" ghcr.io/opcfoundation/uanetstandard/refserver:latest -c -s

Known limitations and issues

VS integrated docker build/debug support is not working with the Solution.

5.6 KiB Raw Blame History