mirror of https://github.com/OPCFoundation/UA-.NETStandard.git synced 2026-10-27 04:59:55 +08:00

Files

T

Marc SchierandCopilot 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

Properties

Bound reconnect cleanup and organize samples by domain (#4276 )

2026-08-21 04:35:47 +00:00

MinimalClient.csproj

Bound reconnect cleanup and organize samples by domain (#4276 )

2026-08-21 04:35:47 +00:00

Program.cs

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

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

README.md

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

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

README.md

OPC Foundation UA .NET Standard Minimal Client

Introduction

The minimal console client demonstrates a clean, lightweight OPC UA client implementation using the modern fluent API and dependency injection with HostApplicationBuilder. It is designed as an educational reference and starting point for building OPC UA client applications.

Key Features

Fluent DI API: Uses HostApplicationBuilder with fluent .AddOpcUa(), .AddClient(), .AddSubscriptions(), and .AddAlarms() configuration
Secure by Default: Discovers a SignAndEncrypt / Basic256Sha256 endpoint unless --insecure is explicitly supplied
Managed Sessions: Leverages the modern IManagedSessionFactory for simplified session management
Fluent Subscriptions: Creates a V2 subscription and monitored item with AddSubscription() and TryAddMonitoredItem()
Dependency Injection: Fully integrated Microsoft.Extensions.DependencyInjection with host-based lifetime management
Service-Provided Telemetry: Uses the DI-integrated ITelemetryContext for logging, metrics, and activity tracking
Alarms & Conditions: Includes A&C client support via .AddAlarms()
Console Logging: Integrated console logging for visibility into client operations
Native AOT Compatible: Supports ahead-of-time compilation with .NET

Getting Started

Prerequisites

.NET 10.0 SDK or later
An OPC UA server accessible at the specified endpoint

Running the Client

To connect to the default MinimalBoilerServer:

dotnet run

The server certificate must already be trusted. For local development only, explicitly opt into automatic trust:

dotnet run -- --auto-accept

To explicitly select an endpoint without message security:

dotnet run -- --insecure

To connect to a different server:

dotnet run -- "opc.tcp://localhost:62542/MinimalCalcServer"

Example Usage

The minimal client demonstrates the following operations:

Host Setup: Creates an application host with Host.CreateApplicationBuilder()
DI Configuration: Configures the application and client services with the fluent API
Endpoint Discovery: Selects the requested secure endpoint through .AddDiscoveryAndConnect(...)
Session Connection: Connects through the DI-provided managed-session factory
Subscriptions: Monitors ServerStatus.CurrentTime with the V2 subscription API
Alarms & Conditions: Resolves AlarmClientFactory and creates an A&C client for the session
Browsing: Browses the server's address space (ObjectsFolder)
Reading: Reads the server's current time from the StandardServer
Notifications: Waits up to 10 seconds for the subscription's first data change notification
Clean Shutdown: Properly closes the subscription, session, and host

Architecture

Program.cs

The application uses top-level statements and demonstrates:

Configuring application identity and security directly inside .AddClient(...)
Setting up HostApplicationBuilder with OPC UA client services
Building and validating the ApplicationConfiguration inside the DI infrastructure
Configuring services via fluent API: .AddOpcUa().AddClient(...).AddSubscriptions().AddAlarms()
Discovering a secure endpoint and connecting through the DI-provided managed-session delegate
Creating a V2 subscription and monitored item with the fluent session extensions
Resolving AlarmClientFactory for Part 9 Alarms & Conditions operations
Performing basic OPC UA operations (Browse, Read)
Proper resource cleanup for the subscription, session, and host

DI Container Integration

The client follows the patterns described in DependencyInjection.md:

HostApplicationBuilder: Central entry point for DI and host setup
Client Options: OpcUaClientOptions exposes the application identity fields (ApplicationName, ApplicationUri, ProductUri, AutoAcceptUntrustedCertificates, etc.) directly alongside managed-session defaults, so a client-only host can configure everything inside .AddClient(...) without a separate configuration construction step
Factory Pattern: IManagedSessionFactory for runtime endpoint selection
Fluent API: Chainable .AddXxx() methods on IOpcUaBuilder

Educational Value

This minimal client serves as:

A clean reference implementation for building OPC UA clients with dependency injection and HostApplicationBuilder
A learning resource for understanding the modern OPC UA client stack and fluent DI patterns
A template matching the architecture of MinimalBoilerServer for consistency
A starting point for custom client applications

For More Information

See Sessions.md for detailed session and subscription documentation
See DependencyInjection.md for DI patterns and service composition
See MinimalBoilerServer for server-side HostApplicationBuilder patterns
See IdentityProviders.md for authentication and authorization patterns