mirror of
https://github.com/OPCFoundation/UA-.NETStandard.git
synced 2026-10-18 22:55:08 +08:00
Marc Schier
0f710adc8e
# Description This PR is a documentation overhaul for OPC UA .NET Standard 2.0. It splits the monolithic `Docs/MigrationGuide.md` into per-version sub-docs (so a coding agent can load only the relevant section), adds a new "What's New in 2.0" landing doc, rewrites `Docs/Profiles.md` and the repo-root `README.md` to reflect what master actually implements, and renames the misnamed `Docs/ALiasNames.md` to `Docs/AliasNames.md`. The branch is `docupdates` and contains **6 commits** stacked on top of `master`. All changes are doc-only except for `HelpLinkUri` string updates in `Opc.Ua.MigrationAnalyzer` (all 119 analyzer tests still pass × 5 TFMs). ## What changed ### `Docs/MigrationGuide.md` is now a thin landing page Before: a single ~144 KB / 1,549-line document covering 22 distinct migration topics in one file. After: a small 3.8 KB / 64-line landing page that introduces general principles, lists a per-version table, and keeps the tiny `1.05.377 → 1.05.378` and `1.04 → 1.05` legacy sections inline. The 1.5.378 → 2.0 content moves to a new **`Docs/migrate/2.0.x/`** folder with a README index plus 12 thematic sub-docs, mapped 1-to-1 to the existing H3 sections: | Sub-doc | Folded H3 sections | | --- | --- | | `telemetry.md` | Telemetry and Logging | | `packages.md` | Package, Target Framework and Dependency Changes | | `source-generation.md` | Source Generation | | `types.md` | Improved Type safety | | `encoders.md` | Encodeable Factory + Encoders/Decoders + Complex Types | | `node-states.md` | Node States + INodeCache changes | | `identity.md` | User Identity Token Handlers + User Identity Providers + Secrets | | `certificates.md` | Certificate Management + ICertificateProvider | | `configuration.md` | Configuration + Session/Browser State Persistence | | `sessions-subscriptions.md` | GDS Client API modernisation + ManagedSession + Subscriptions/Transports | | `alarms-model-change.md` | Alarms and Conditions + Address-space model change tracking | | `timeprovider.md` | Time and Timer abstraction (TimeProvider) | Each sub-doc starts with a **"When to read this"** lead paragraph (analyzer rules / symptoms / API areas it covers) and ends with a sibling-links footer. `Docs/migrate/2.0.x/README.md` has a symptom → sub-doc index table reused as-is in the agent skill. ### `opcua-v20-migration` agent skill is now context-efficient `.agents/skills/opcua-v20-migration/SKILL.md` gains a "Migration sub-doc index — load only what you need" section near the top with an explicit *"Do not load `Docs/MigrationGuide.md` into context"* instruction and a table keyed by symptom / API area / analyzer rule ID, so an agent loads at most one sub-doc per migration scenario. Path references in `README.md`, `references/analyzer-rules.md`, `references/migration-patterns.md`, and `references/source-generator.md` are updated to point at the new sub-doc locations. ### New `Docs/WhatsNewIn2.0.md` Developer-facing narrative tour of the 1.5.378 → 2.0 delta (~320 lines, hybrid grouping: cross-cutting themes first — type system & immutability, async/cancellation/TimeProvider, DI & hosting, Native AOT, source generators, companion specs Part 9/11/13/16/17/18/20/100 + WoT + LDS, performance, security — then by layer: Server, Client/Sessions/Subscriptions, PubSub, GDS, Tooling, CI). Paragraph per feature, no PR/commit references, links to the deeper per-feature docs. Linked from `Docs/README.md` between `Profiles.md` and `MigrationGuide.md`. ### `Docs/Profiles.md` rewritten to reflect master Adds Functional Facets for newly-implemented features (Part 9 Alarms, Part 11 Historical Access, Part 13 Aggregates, Part 16 State Machines, Part 17 Alias Names, Part 18 Role Management, Part 20 FileSystem server, Part 100 Device Integration / Software Update, OPC 10100-1 WoT, Node Management, Local Discovery Server, Auditing, Model Change Tracking). Expands Client Profiles (classic `Session` vs `ManagedSession`, V2 subscription engine, `FileSystemClient`, `HistoryClient`, `AlarmClient`, NodeSet export, source-generated typed `ObjectType` proxies). Adds a Reference Applications section listing all of `Applications/*` (Quickstarts/Ctt/Mono configs, Reference Client, LDS, MCP, Minimal* / Pump* samples). Security policies and transport profiles confirmed against `Stack/Opc.Ua.Core/Security/Constants/*` — no changes needed there. For new facets whose canonical URI could not be confidently verified against `profiles.opcfoundation.org` (the registry is fully SPA-rendered), the doc describes the facet by name and points readers at the OPC Foundation registry rather than fabricating URIs. The `ServerProfileArray` in the reference-server configs is intentionally left unchanged to avoid CTT-compliance regressions from advertising an unverified URI. ### Repo-root `README.md` cleaned up Front page now makes the 2.0 / `master378` context explicit. New 5-section structure with one emoji per heading: 🆕 version callout → 📦 What it is → 🚀 Getting started (grouped sample list linking to each sample's own README) → 🔧 Migrating from 1.5.378 → 🤝 Contributing & license → 📚 Further reading. Removes the "New in 1.04.368 / 1.05.373 / .374 / .375 / .376 / .378 / 2.0" laundry list, the dated "Key Features and Updates in OPC UA 1.05" section, inline VS / `dotnet run` build instructions, the "Start the server" walkthrough, the "Remarks" (self-signed certs + LDS) notes, and the inaccurate `.NET Standard 2.1` overview claim. Trims the 11 status badges down to 5 essentials (release, NuGet downloads, build, tests, codecov). ### File rename — `Docs/ALiasNames.md` → `Docs/AliasNames.md` The on-disk filename had a stray capital `L` while every link in `Docs/README.md`, `Docs/Profiles.md`, etc. used the lowercase spelling. Renamed via case-only `git mv` (Windows two-step). Existing links across the docs now resolve on GitHub's case-sensitive filesystem. ### `Opc.Ua.MigrationAnalyzer` `HelpLinkUri` updates - `Tools/Opc.Ua.MigrationAnalyzer/Diagnostics/DiagnosticIds.cs` — `HelpLinkUriBase` repointed from `Docs/MigrationGuide.md#` to `Docs/migrate/2.0.x/README.md#` so the rule-ID help links land on the symptom → sub-doc index instead of a generic landing page. - `Tools/Opc.Ua.MigrationAnalyzer/Diagnostics/DiagnosticDescriptors.cs` — UA0021 / UA0022 message strings reference the new `Docs/migrate/2.0.x/certificates.md`. - `Tools/Opc.Ua.MigrationAnalyzer/Analyzers/UA0021CertificateValidatorRenameAnalyzer.cs` — XML-doc path updated. - `Tools/Opc.Ua.MigrationAnalyzer/NugetREADME.md` and `AnalyzerReleases.Unshipped.md` — references repointed. ## Verification - `Opc.Ua.MigrationAnalyzer` builds with **0 Warning(s), 0 Error(s)** in Release. - `Opc.Ua.MigrationAnalyzer.Tests`: **119/119 tests pass × 5 TFMs** (net48, net472, net8.0, net9.0, net10.0). - `ConsoleReferenceServer` builds with **0 Warning(s), 0 Error(s)** in Release on net10.0 (verifies the reference-server config XML still parses cleanly after our doc-touching). - **Every relative markdown link** in the new / changed docs (the new `Docs/migrate/2.0.x/*`, `Docs/MigrationGuide.md`, `Docs/WhatsNewIn2.0.md`, `Docs/Profiles.md`, `Docs/Sessions.md`, `Docs/IdentityProviders.md`, the agent skill files, and the new `README.md`) was walked programmatically — **0 broken links**. - Deep heading anchors verified to match GitHub-generated slugs (`MigrationGuide.md#encoders-and-decoders`, `Sessions.md#1-session--the-opc-ua-session-primitive`, `Sessions.md#3-managedsession--the-connection-state-machine-facade`, `migrate/2.0.x/identity.md#user-identity-providers`, `migrate/2.0.x/identity.md#user-identity-token-handlers`, `migrate/2.0.x/encoders.md#encoders-and-decoders`, `migrate/2.0.x/node-states.md#inodecache-changes`, `migrate/2.0.x/certificates.md#certificatemanager-and-segregated-interfaces`, `migrate/2.0.x/sessions-subscriptions.md#managedsession-and-automatic-reconnection`). - No `ALiasNames` (capital L) references remain anywhere in the repo (case-sensitive search). ## Commit history (6 commits) 1. `548d0b5ed` — Docs: rename `ALiasNames.md` to `AliasNames.md` 2. `8a8db8c30` — Docs: add `WhatsNewIn2.0.md` (1.5.378 → 2.0 highlights) 3. `e69b2169e` — Docs: rewrite `Profiles.md` to reflect master implementation 4. `5fb8a282b` — Merge remote-tracking branch `origin/master` into `docupdates` (resolves overlap with #3854's `Docs/Subscriptions.md` rename of `StreamingSubscription.md`) 5. `d853fbc74` — Docs: split `MigrationGuide.md` into per-version sub-docs (#3745) 6. `65d6e6851` — Docs: rewrite repo-root `README.md` for 2.0 ## Related Issues - Fixes #3745 (MigrationGuide.md document structure) ## Checklist - [x] 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. *(N/A — documentation change; existing `Opc.Ua.MigrationAnalyzer.Tests` (119 tests × 5 TFMs) still pass after the `DiagnosticDescriptors` / `DiagnosticIds` text updates.)* - [x] I have added all necessary documentation. *(this PR is the documentation; all internal links verified)* - [x] I have verified that my changes do not introduce (new) build or analyzer warnings. *(both `Opc.Ua.MigrationAnalyzer` and `ConsoleReferenceServer` build with 0 warnings / 0 errors)* - [ ] I ran **all** tests locally using the **UA.slnx** solution against at least .net **framework** and .net **10**, and all passed. *(only the migration-analyzer test suite was rerun, since this PR is doc + a few `HelpLinkUri` strings; full UA.slnx run pending CI)* - [ ] I fixed **all** failing and flaky tests in the CI pipelines and **all** CodeQL warnings. *(pending CI)* - [ ] I have addressed **all** PR feedback received.
OPC UA .NET Standard stack documentation
Here is a list of available documentation for different topics:
UA Core stack related
- OPC UA Profiles and Facets - Overview of supported OPC UA profiles, facets, security policies, and transport protocols.
- What's New in 2.0 - Developer-facing tour of the 1.5.378 → 2.0 changes, grouped by theme and layer, with links to deeper feature docs.
- Migration Guide - How to migrate from a previous version.
- Sessions, Reconnection, and Subscription Engines - Architectural overview of
Session,ManagedSession,SessionReconnectHandler, and the classic / V2 subscription engines, including guidance on which to use. - About .NET platform support, Nuget packages and versioning.
- How X.509 Certificates are used in the certificate stores.
- Using the Reverse Connect for the UA-TCP transport.
- Support for the TransferSubscriptions service set.
- Observability support in the stack.
- Support for WellKnownRoles & RoleBasedUserManagement.
- Pluggable Identity Providers — interfaces (
IClientIdentityProvider,IUserTokenAuthenticator,IAccessTokenProvider,ITokenIssuer,IIdentityClaims) plus the OPC 10000-6 §6.5.2.2IssuerEndpointUrlJSON parser for OAuth2 / OIDC / Entra / JWT flows. - Support for ECC Certificates.
- Working with ComplexTypes - Custom structures and enumerations.
- Client-based NodeSet Export - Export server address space to NodeSet2 XML.
- Source generated [DataTypes] - How to annotate POCO classes and let the source generator generate the
IEncodeableimplementation. - Source generated NodeManagers - Emit an
AsyncCustomNodeManagerfrom a model design XML and wire callbacks via the fluentINodeManagerBuilderAPI; supports NativeAOT single-file servers (samples: MinimalBoilerServer, PumpDeviceIntegrationServer). Covers engineering units, property initialisation, alarms, simulation timers, instance creation, NAMUR-style supervision, multi-model composition, and the fluent state-machine builder on top of anyFiniteStateMachineStatesubclass. Cross-assembly model references are tracked via the ModelDependencyAttribute. Companion-spec packaging — model + server + client library trios — is covered end-to-end by the Device Integration developer guide using theOpc.Ua.Di/Opc.Ua.Di.Server/Opc.Ua.Di.Clienttrio as the worked example. - Device Integration (DI) developer guide - End-to-end documentation for the
Opc.Ua.Di*library trio: fluentIDeviceBuilder, device sub-type extensions (AddSoftware,AddBlock,AddConfigurableObject,AddLifetimeIndication,WithSupportInfo), hosting integration (AddOpcUaDi/ConfigureDevicesFor), lock service, software-update package store, and client helpers (DiLockClient,DiTopologyClient,SoftwareUpdateClient). Includes a section enumerating supported OPC 10000-100 features against the spec. - Alias Names - Full server + client support for the OPC UA Part 17 alias-name model (
AliasNameType,AliasNameCategoryType,FindAlias,FindAliasVerbose,AddAliasesToCategory,DeleteAliasesFromCategory,LastChange). - Alarms and Conditions - Full server + client support for OPC UA Part 9. Server-side state types for latched/silenced/out-of-service alarms, alarm groups and suppression engine, alarm rate metrics. Client-side
AlarmClient, typed alarm event records, fluentAlarmEventFilterBuilder,IAsyncEnumerablealarm streaming viaAlarmStreamExtensions. - Historical Access (Part 11) - Server provider model (
IHistorianProviderfamily) andInMemoryHistorianProvider, plus the clientHistoryClient(session.Historian()) for raw/modified/at-time/processed reads, annotations, and updates. - Aggregates (Part 13) - All 37 standard Part 13 v1.05.07 aggregate functions over historical data: server
AggregateManager/ calculators, native push-down vs framework fallback,AnnotationCountvia the annotation provider,AggregateConfigurationdefaults, and the clientReadProcessedAsynchelper. - Subscriptions and Monitored Items Service Set - V2 subscription engine API. Covers
ISubscriptionManagerfor long-lived callback-based subscriptions, the declarative+imperativeSetTriggeringAPI with N:M support and automatic replay on recreate/reconnect, andIStreamingSubscription(IAsyncEnumerable-based) for state-machine waits and short-lived monitoring (ManagedSession.DefaultStreaming,TakeUntilAsync/WithTimeoutAsynchelpers). - Unbounded Monitored Items - V2 logical-subscription wrapper that transparently splits monitored items across multiple server-side partitions when the per-subscription cap is exceeded (
IPartitionedSubscription,MonitoredItemOptions.Affinity, reactiveBad_TooManyMonitoredItemsfallback, secondary-partition idle-delete). - State Machines - Generic, extensible Part 16 state-machine API. Client side: streaming + read helpers on the source-generated
*TypeClientproxies (GetCurrentFiniteStateAsync,ObserveFiniteTransitionsAsync,WaitForStateAsync). Server side: unified fluentStateMachineBuilderwith two complementary modes — definition (Create(...)+AddState/AddTransition/OnCausefor ad-hoc machines viaFluentFiniteStateMachineState) and lifecycle (For(...)/INodeBuilder.AsStateMachine()+OnEnterState/WithCause/WithTimedTransitionto attach behavior to stack-shipped or generator-emitted FSMs). Vendor state machines inherit both ends of the API automatically. - Model Change Tracking - Client-side address-space change tracking with per-node
INodeCacheinvalidation; server-sideModelChangeAggregatorand auto-emittedGeneralModelChangeEventfromCustomNodeManager.CreateNode/DeleteNode. - NodeManagement Service Set - Server-side AddNodes / DeleteNodes / AddReferences / DeleteReferences, including the
INodeManagementAsyncNodeManageropt-in pattern and per-NodeManagerAllowNodeManagementgate. - Dependency Injection - The unified
services.AddOpcUa()/IOpcUaBuildersurface for hosting OPC UA components inMicrosoft.Extensions.DependencyInjection/ the .NET Generic Host (servers asIHostedService, options viaAction<T>orIConfiguration, AOT-friendly). - AuthorizationService - Modern Part 12
StartRequestToken/FinishRequestToken,ITokenIssuer, and GDS token issuance. - Fuzz testing - SharpFuzz + afl-fuzz + libFuzzer integration. Three areas:
Encoders(Binary/JSON/XML decoders, built-in type readers, parser entry points),Certificates(X509CRL, X509 extension parsers,PEMReader,Pkcs10CertificationRequest, ASN.1 helpers), andNetwork(UA-SC framing viaOpc.Ua.Bindings.Pcap+ internalTcpMessageParsersseam onOpc.Ua.Core). Thefuzz-testercustom agent drives the whole toolchain autonomously: it detects OS-available engines, runs them in parallel, fixes novel findings per repo guidelines, adds the failing input as a regression asset, and pushes one commit per fix until the user says stop. - KeyCredentialService - Pull, Push, and experimental bridge guidance for Part 12 KeyCredential flows.
Reference application related
- Reference Client documentation for configuration of the console reference client using parameters.
- Reference Server documentation for running against CTT.
- Provisioning Mode for secure certificate provisioning and initial server configuration.
- Using the Container support of the Reference Server in Visual Studio 2026 and for local testing.
Starting with version 1.5.375.XX the Windows Forms reference client & reference server were moved to the OPC UA .NET Standard Samples repository.
For the PubSub support library
- The PubSub library with samples.
- The ConsoleReferencePublisher documentation.
- The ConsoleReferenceSubscriber documentation.
Global Discovery Server (GDS)
- GDS Developer Guide — Application registration, certificate management (pull & push models), roles and authorization, provider implementation, end-to-end examples.
- KeyCredentialService — Credential issuance for non-OPC UA services (MQTT, REST), IKeyCredentialRequestStore provider guide, ISecretStore integration.
- AuthorizationService — OAuth2-style access token issuance, IAccessTokenProvider implementation guide.
- Role-Based Security — Part 18 roles and claim-based identity-mapping rules.
- Identity Providers — server and client identity-provider architecture.
- Dependency Injection — dependency injection hosting and identity registration extensions.