GithubStar/UA-.NETStandard

Fork 0

mirror of https://github.com/OPCFoundation/UA-.NETStandard.git synced 2026-10-24 11:01:55 +08:00

Files

T

5899354441 Clarify documentation, migration guidance, and SDK selection (#4823 )

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

2026-10-21 10:10:55 +02:00

6.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'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.

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

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`

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:

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

6.6 KiB Raw Blame History