mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-24 19:13:02 +08:00
5899354441
# Description Remove stock phrasing and correct misleading or inconsistent technical documentation. The initial two passes covered 367 Markdown files, followed by an interactive review of 169 editorial flags. The U5 interpretation originally deferred in that review has since received the upstream Mantis answer recorded by #4843; remaining server/spec follow-ups stay explicit in the CTT log. - Correct package responsibilities, migration steps, API names, ownership, protocol descriptions and links. Keep bundled migration guides synchronized. Preserve historical conclusions as historical records with separate re-check notes. - Provide at least two rendered TOC levels throughout `docs/`. Convert appropriate architecture figures to Mermaid without changing code examples, transcripts or historical quotations. - Address the October 19 feedback with concrete setup/migration instructions, corrected certificate paths and PubSub names, shorter repeated caveats, consistent XML comments, and a full review of the Concepts guide. Retain #4839's API corrections. - Integrate #4841's runtime/performance guidance and review incoming/recent prose. Preserve dated measurements rather than claiming new benchmark runs; clarify allocation ratios, startup-only processor settings, JIT warm-up and the benchmark commit's scope. Missing raw measurement artifacts and repeat ranges remain tracked by #4842. - Merge master through `e8c5d800a` in `32c6394b7`. Resolve the CTT log conflict using the updated Mantis states and OPC answers, retaining historical framing and re-checks for C28/C32/C43. - Address the latest naming/index feedback in `adb5bf693`: rename the guides to `docs/WotCon.md` and `docs/WotNodeSetConversion.md`; move the provider and DataType-declaration contracts into the conversion guide and remove `docs/WoT.md`. Rename `samples/DI` to `samples/Di` and `samples/Isa95` to `samples/ISA95`. Add content-index READMEs to Di, FluentApi, ISA95, Lds and PubSub; update solution entries, project references, Docker/CI paths, test fixture paths and documentation links with exact casing. **WoT guide scope.** This branch retains the detailed conversion guide that #4758 had replaced with an anchor stub. Conversion limits, verified document sets, preservation rules and provider ownership now live together in `WotNodeSetConversion.md`; binding/runtime guidance remains in `WotBindings.md` and `WotCon.md`. The design-rationale/test-ledger prose was shortened, the oversized argument-table cell moved into its section, and existing anchors preserved. **SDK policy is a separate, explicit user-directed change.** `global.json` sets a stable minimum of `10.0.400`, `rollForward: latestMajor`, and `allowPrerelease: false`. Newer major SDKs are permitted; CI's explicit SDK pins are unchanged. README, GettingStarted, DeveloperGuide and Recycling instructions reflect the possible analyzer differences. The image-contract regression fix accepts compatible stable SDK images instead of requiring exact equality with the floor. The latest four rename/index threads are resolved after publication. Three older threads remain open: universal obsolete-removal timing, unconditional nonce-strength wording, and a blanket Vision NativeAOT claim. Existing implementation/evidence constraints are explained in their inline replies. The two-level TOCs remain as requested. ## Validation - `git diff --check` and staged diff checks: passed. The untouched upstream AutoID NodeSet retains its provenance bytes, including two existing license-header trailing spaces. - `.\.azurepipelines\validate-migration-plugin.ps1`: passed; 15 bundled migration documents and manifests synchronized. - Documentation/path validation: **101** documents retain two rendered TOC levels (**2,228** entries), with idempotent formatting. **52** new relative links and their anchors passed exact-case checks. No tracked references to the old guide/sample paths remain. Both relocated provider-contract sections are preserved in the destination. - `dotnet sln UA.slnx list`: passed; shows the renamed Di/ISA95 projects and the existing FluentApi/Lds/PubSub projects. Updated solution and pump ProjectReference paths also passed exact-case existence checks. - Latest focused commands, run from the repository root: ```powershell # Passed: 61 channel send-order and reconnect tests. dotnet test tests\Opc.Ua.Core.Tests\Opc.Ua.Core.Tests.csproj -p:CustomTestTarget=net10.0 --filter 'FullyQualifiedName~UaSCBinaryChannelSendOrderTests|FullyQualifiedName~TcpReconnectKeyAgreementTests' --verbosity minimal # Passed: 5 pump datasheet tests; builds the renamed pump sample. dotnet test tests\Opc.Ua.Di.Tests\Opc.Ua.Di.Tests.csproj -p:CustomTestTarget=net10.0 --filter 'FullyQualifiedName~PumpDatasheetConformanceTests' --verbosity minimal # Passed: 4 repository NodeSet path/round-trip tests, including the moved pump models. dotnet test tests\Opc.Ua.Types.Tests\Opc.Ua.Types.Tests.csproj -p:CustomTestTarget=net10.0 --filter 'FullyQualifiedName~RepositorySourceSurvivesSerializedLinkedPartitionsAsync' --verbosity minimal # Passed: build, zero warnings/errors. dotnet build samples\ISA95\MinimalIsa95Server\MinimalIsa95Server.csproj -p:CustomTestTarget=net10.0 -f net10.0 --verbosity minimal # Passed: dependent sample-test project build, zero warnings/errors. dotnet build tests\Opc.Ua.WotCon.Samples.Tests\Opc.Ua.WotCon.Samples.Tests.csproj -p:CustomTestTarget=net10.0 -f net10.0 --verbosity minimal ``` Earlier focused integration checks passed 2,620 tests across AutoID, event queues/scheduling, source generation, MCP/package profiles and WoT. Both reviewed Mermaid diagrams rendered locally without network access. These checks are not a full solution run. The full solution has **not** been rerun for this review. Earlier `dotnet test UA.slnx -p:CustomTestTarget=net10.0 --verbosity quiet` did not pass: three AOT projects rejected VSTest and 20 Vision tests failed during graphics initialization with `OutOfMemoryException`. Remaining long-running tests were stopped at the user's request. A focused Vision rerun passed 558 tests and reproduced those 20 failures. The earlier `dotnet test UA.slnx -p:CustomTestTarget=net48 --verbosity quiet` was blocked by the former SDK pin and was not retried after the policy change. The user approved proceeding with those limitations documented; current remote CI is not claimed green. ## Related Issues - Follow-up #4842 tracks the requested 2.0.2+ benchmark/tuning and diagnostic-tool documentation refresh. #4841 supplies documentation and earlier results, not all newly requested measurements. - #4758 explains the conversion guide's earlier consolidation; the current provider contracts are now consolidated into `WotNodeSetConversion.md`. - #4839 supplies the reviewed API corrections; #4843 supplies the updated CTT issue record. - The original prose cleanup and SDK policy were user-requested without a source issue. No new runtime architecture is introduced by these documentation edits. ## 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. - [ ] 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. - [ ] 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. --------- Co-authored-by: Roman Ettlinger <romanett98@gmail.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
142 lines
6.6 KiB
Markdown
142 lines
6.6 KiB
Markdown
# 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](https://github.com/OPCFoundation/UA-.NETStandard/pkgs/container/uanetstandard%2Frefserver). 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](https://github.com/OPCFoundation/UA-.NETStandard/commit/61a61081f6060804b12b8f351e32a8075703263d).
|
|
- Build locally with Docker Desktop on Linux or Windows. Docker Desktop settings select the target container OS.
|
|
- Visual Studio's integrated container build/debug has reported build, startup, and connection failures with the UA Reference solution. Use the Docker CLI or repository scripts below.
|
|
- Visual Studio 2022 supports native debugging of a Linux distribution through WSL.
|
|
|
|
## Contents
|
|
|
|
- [Overview](#overview)
|
|
- [Other published sample images](#other-published-sample-images)
|
|
- [Building the local containers](#building-the-local-containers)
|
|
- [Run the reference server container](#run-the-reference-server-container)
|
|
- [Run the local build of the Docker container](#run-the-local-build-of-the-docker-container)
|
|
- [Run the prebuilt Docker container hosted on GitHub](#run-the-prebuilt-docker-container-hosted-on-github)
|
|
|
|
## Other published sample images
|
|
|
|
The [`Images CI`](../.github/workflows/docker-image.yml) 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` |
|
|
|
|
The workflow does not compile anything under emulation. Its
|
|
`publish-samples` job publishes every sample above once, natively, as
|
|
framework-dependent portable IL (no runtime identifier and no app host). The
|
|
same output then runs on both platforms. Each `build-and-push-image` leg
|
|
downloads that output and builds its Dockerfile with
|
|
`--build-arg PUBLISH_SOURCE=prebuilt --build-arg PUBLISH_DIR=<folder>`. That
|
|
build only copies files onto the platform's .NET runtime base image, so QEMU
|
|
is not needed.
|
|
|
|
All sample Dockerfiles use the .NET 10 Azure Linux 3 SDK image for building and
|
|
an Azure Linux 3 distroless-extra runtime or ASP.NET image for the final image.
|
|
The `distroless-extra` variant retains ICU and time-zone data for globalization.
|
|
Pump and ModelManagementServer prepare writable directories and the OpenSSL
|
|
configuration in a regular Azure Linux layout stage before copying them into
|
|
their distroless final images.
|
|
|
|
A local `docker build` without these arguments compiles from source in the
|
|
Dockerfile's `build` stage. That stage is pinned to `$BUILDPLATFORM`, so a
|
|
multi-platform `docker buildx build --platform linux/amd64,linux/arm64` also
|
|
compiles natively.
|
|
|
|
Image tags follow the [release-branch-only publication model](ReleaseProcess.md):
|
|
|
|
- **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](ReleaseProcess.md)). 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:
|
|
|
|
```sh
|
|
docker pull ghcr.io/opcfoundation/uanetstandard/ldsserver:latest
|
|
```
|
|
|
|
Pull the most recent development build with:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
docker build -f samples/Lds/ConsoleLdsServer/Dockerfile -t opcua-lds-server .
|
|
```
|
|
|
|
## Building the local containers
|
|
|
|
1. Open a command prompt which can execute docker commands.
|
|
2. Navigate to the folder `samples/Reference/ConsoleReferenceServer`.
|
|
3. Build the docker container by executing the command `dockerbuild.cmd`.
|
|
|
|
On Linux,
|
|
|
|
1. Open a shell which can execute docker commands.
|
|
2. Navigate to the folder `samples/Reference/ConsoleReferenceServer`.
|
|
3. 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:
|
|
|
|
```cmd
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
```
|