# Description
Migrates the entire code base (Stack, Libraries and Applications) from
direct
`ILogger.LogInformation/LogError/LogWarning/LogDebug/LogTrace/LogCritical(...)`
calls to **source-generated `[LoggerMessage]` logging**, as tracked in
#3908.
Source-generated logging avoids boxing of value-type arguments, caches
the
message formatter, and emits an efficient `IsEnabled` check so a
disabled log
level costs nothing.
This is a behavior-preserving refactor: message text, levels and
structured
placeholders are unchanged; only the call shape changes.
## What changed
- **36 projects migrated.** Every static log call now goes through a
per-file
`internal static partial class <Class>Log` holding `[LoggerMessage]`
extension methods on `ILogger`, so call sites keep the natural
`logger.SomeEvent(...)` shape. Closely-related files that emit the same
messages share one log class (e.g. the encoders/decoders in
`Opc.Ua.Types`
share `EncodingLog`) to avoid duplication and CS0121 ambiguity.
- **Per-assembly event-id classes.** Each project has one
`internal static class <AssemblyToken>EventIds` (e.g. `CoreEventIds`,
`ClientEventIds`, `PubSubEventIds`) with a reserved `public const int`
offset block per log class. The assembly-token prefix avoids CS0436
collisions across `InternalsVisibleTo` boundaries.
- **`CA1873` enabled solution-wide** in `.editorconfig` now that the
whole
code base (including test, sample and tooling projects) is migrated, so
any
regression back to a direct `ILogger.Log*` call with an expensive
argument is
flagged. Every occurrence has been guarded with an `IsEnabled` check (or
the
check merged into an existing condition where the log was the sole body
of an
`if`/`else`, preserving side effects); the only suppressions are two Moq
`Verify` expression-tree sites, which are not executed log calls.
- **Dynamic log levels stay hand-written.** A handful of calls whose
level is
only known at runtime keep the structured `logger.Log(logLevel, ...)`
form
under an `if (logger.IsEnabled(logLevel))` guard — `[LoggerMessage]`
requires
a compile-time level.
- **netstandard duplicate-generator fix.** Projects that also pull in an
R9
package (`Microsoft.Extensions.Http.Resilience`, `.Compliance`,
`.Telemetry`)
get the `Microsoft.Gen.Logging` generator in addition to the in-box one;
on
`netstandard` both implement every partial method (CS0757). A single
`Directory.Build.targets` target removes the R9 analyzer on
`netstandard`
only (no-op elsewhere and where it is not referenced).
- **Shared/linked source files** that are compiled into more than one
project
(e.g. sample files linked into test projects) use self-contained literal
event ids instead of a per-assembly class the consumer does not compile.
- **Docs.** The authoring recipe (event-id convention, log-class
convention,
parameter rules, the `IsEnabled` guard, shared/linked files, and the
netstandard generator interaction) lives in the new
[`Docs/DeveloperGuide.md`](Docs/DeveloperGuide.md#add-a-log-message-source-generated);
`Docs/Diagnostics.md` keeps the runtime/observability side and links to
it.
- **Redaction preserved.** Log calls that previously wrapped sensitive
values
with `Redact.Create(...)` keep passing the `RedactionWrapper<T>`
(instead of
an eager `.ToString()`), so format-time redaction still applies — this
also
clears the CodeQL clear-text alerts introduced during the migration.
## Validation
- Full `UA.slnx` build passes with **0 errors / 0 warnings**; the
multi-target
test projects force every referenced library to build on
net472/net48/netstandard2.1/net8.0/net9.0/net10.0.
- No unguarded static `ILogger.Log*` calls remain anywhere (only the
guarded
dynamic-level calls); `CA1873` is clean across the full solution on
net10.0.
## Related Issues
- Fixes#3908
## 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.
- [x] 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.
# Full OPC UA Part 14 (PubSub) — v1.05.06
This PR replaces the legacy PubSub stack with a modern, **OPC UA Part 14
v1.05.06**-compliant reimplementation built on current .NET: fully
`async`, dependency-injection-first with a fluent builder
(`services.AddOpcUa().AddPubSub(...)`), NativeAOT/trim-safe, and
designed for high-throughput, highly-available, distributed deployments.
The libraries — `Opc.Ua.PubSub`, `Opc.Ua.PubSub.Udp`,
`Opc.Ua.PubSub.Mqtt`, `Opc.Ua.PubSub.Server`, and
`Opc.Ua.PubSub.Adapter` — keep source compatibility with 1.5.378 where
practical (obsolete shims) and ship a complete migration path. See the
**[PubSub
guide](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md)**
and the **[2.0.x migration
guide](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/migrate/2.0.x/pubsub.md)**.
**Encodings & transports.** Both wire encodings are implemented in full
— **UADP** (key/delta/event/keepalive, RawData, chunked,
signed+encrypted) and **JSON** (verbose/compact, single-message,
metadata; migrated from `Newtonsoft.Json` to `System.Text.Json`) —
across **UDP** (uni/multi/broadcast + discovery), **MQTT** (3.1.1/5.0,
retained metadata, TLS), and a from-scratch **DTLS 1.3** secured
datagram transport (`opc.dtls://`) implemented on the .NET BCL crypto
primitives (ECDHE, HelloRetryRequest cookies, certificate auth, AEAD
record protection, HKDF key schedule), wired through
`AddUdpTransport().WithDtls(...)`. Details in
[Transports](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md#transports)
and
[Encodings](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md#encodings).
A raw **Ethernet (Layer 2)** transport (`opc.eth://`, EtherType
`0xB62C`, optional 802.1Q VLAN) carries UADP NetworkMessages directly in
Ethernet II frames with no IP/UDP, via `AddEthTransport()`
(`.WithPcap()` for cross-platform capture). See [Ethernet
transport](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md#ethernet--uadp-opceth).
**Runtime schema generation.** A new schema subsystem
(`Opc.Ua.Core.Schema`, `Opc.Ua.PubSub.Schema`) generates **XSD**, **OPC
Binary (BSD)**, and **JSON Schema** for OPC UA data types at runtime —
including PubSub NetworkMessage/DataSet message schemas — driven from
the type system and source-generated metadata (no reflection;
NativeAOT/trim-safe). It is consumable from the client, server, and
PubSub stacks. See the **[Schema generation
guide](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/SchemaGeneration.md)**.
**Security, fail-closed.** Message-level security is wired end-to-end
through `IPubSubSecurityWrapperResolver`: publishers are fail-closed (a
secured group with no key source throws rather than emitting plaintext)
and subscribers enforce per-reader inbound security. It includes AES-CTR
(128/256) policies with HMAC-SHA-256, a deterministic 96-bit nonce with
a messages-per-key cap, a monotonic sliding replay window, and a
Security Key Service (SKS) pull client + in-memory server with
SecurityGroups and key rotation. Two independent security assessments
(IEC 62443-4-2 × OPC UA Part 2/4/14, plus a Microsoft SDL/SFI delta
pass) drove remediation of all actionable findings — including orphaned
message security, chunked-frame security bypass, unauthenticated Action
invocation, pre-auth reassembly DoS, and DTLS hardening. See
[Security](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md#security)
and
[SKS](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md#security-key-service-sks).
**Server-side & high availability.** The runtime can optionally surface
through a standard in-process OPC UA address space
(`Opc.Ua.PubSub.Server`) with configuration methods, per-component
diagnostics, the full PubSubState model, KeepAlive and
MessageReceiveTimeout. Pluggable configuration/runtime-state stores, an
id allocator, and HA runtime-state providers with failover support
running publishers/subscribers in a distributed system. See [Server-side
address
space](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md#server-side-address-space)
and [High
availability](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md#high-availability-state-providers).
**External-server adapter (bridge) with hot-reload.** A new
`Opc.Ua.PubSub.Adapter` binds PubSub publishers, subscribers, and Action
responders to an **external** OPC UA server over `ManagedSession` —
cyclic Read or subscription-backed sources, browse-path node mapping,
and metadata that resolves/retries and re-emits on model-change events.
Adapter and PubSub configuration **hot-reload incrementally** (only
changed writers/readers/responders are rewired; unchanged sessions are
reused), driven by `IPubSubConfigurationStore.Changed` and
`IOptionsMonitor`, with a pluggable change-feed source (e.g. etcd). See
[Binding PubSub to an external
server](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md#binding-pubsub-to-an-external-opc-ua-server-client-session-adapters).
**Samples, packaging & quality.** One combined sample,
`ConsoleReferencePubSubClient`, demonstrates publisher, subscriber, and
external-server modes on `Host.CreateApplicationBuilder` with full
fluent/DI wiring; all libraries publish **NativeAOT with zero
IL2026/IL3050 warnings** ([Native
AOT](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/PubSub.md#native-aot),
[DI](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/DependencyInjection.md)).
The change ships comprehensive NUnit/integration suites and a libFuzzer
harness, maintains ≥80% coverage on the new libraries, and is documented
end-to-end ([What's new in
2.0](https://github.com/OPCFoundation/UA-.NETStandard/blob/part14pubsub/Docs/WhatsNewIn2.0.md)).
# 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.
Complete implementation of **OPC UA Part 9 ΓÇö Alarms & Conditions** for
both server and client, **OPC UA Part 16 ΓÇö State Machines** (generic
extensible client + server API), and the supporting infrastructure
(source-generated event records, source-generated ObjectType proxies,
`IAsyncEnumerable` streaming subscriptions, address-space model change
tracking, per-node `INodeCache` invalidation, unified DI integration).
### Server-side (Part 9 complete)
- **`AlarmConditionState`** ΓÇö every Part 9 method wired automatically
in `OnAfterCreate`: `Silence`, `Suppress`/`Suppress2`,
`Unsuppress`/`Unsuppress2`, `RemoveFromService`/`RemoveFromService2`,
`PlaceInService`/`PlaceInService2`, `Reset`/`Reset2`,
`GetGroupMemberships`. Each method generates the spec-mandated audit
event and supports an optional veto-delegate hook.
- **Latched alarms** ΓÇö `ActiveState` reflects real process state;
`LatchedState` persists until explicit `Reset` (with full precondition
validation).
- **Re-alarming** ΓÇö
`ProcessReAlarm`/`ResetReAlarmRepeatCount`/`IsReAlarmEnabled` helpers
(opt-in, no hidden timer).
- **Audible alarms** ΓÇö `UpdateAudibleState` for
`AudibleEnabled`/`AudibleSound`/`SilenceState` lifecycle.
- **Suppression + groups** ΓÇö `AlarmGroup`, `AlarmSuppressionEngine`
(with first-in-group), `AlarmRateTracker` (for `AlarmMetricsType`).
- **Spec-compliance fixes** ΓÇö `SuppressedOrShelved` now includes
`OutOfServiceState`; `GetRetainState` includes `LatchedState`;
`EffectiveDisplayName` composition includes `OutOfServiceState` +
`LatchedState`.
### Client-side Part 9 API
- **`AlarmClient`** ΓÇö typed Part 9 operations. Each method delegates
to the matching source-generated `*TypeClient` proxy
(`ConditionTypeClient`, `AcknowledgeableConditionTypeClient`,
`AlarmConditionTypeClient`, `DialogConditionTypeClient`,
`ShelvedStateMachineTypeClient`) ΓÇö one source of truth for every
method NodeId.
- **Interface hierarchy** — `IConditionOperations` →
`IAcknowledgeableConditionOperations` → `IAlarmOperations` +
`IDialogConditionOperations`.
- **Source-generated event records** ΓÇö new `EventRecordGenerator`
(alongside `ObjectTypeProxyGenerator`) emits `{Type}TypeRecord` per OPC
UA event type: `ConditionTypeRecord` →
`AcknowledgeableConditionTypeRecord` → `AlarmConditionTypeRecord` →
`LimitAlarmTypeRecord`/`ExclusiveLimitAlarmTypeRecord`/… all the way
to vendor subtypes. **Vendor alarm types get records automatically.**
- **`AlarmEventDecoder`** ΓÇö decodes `EventNotification.Fields` into
the most-specific generated record.
- **`AlarmEventFilterBuilder`** ΓÇö fluent builder for Part 9
`EventFilter`s.
- **`ISession.GetAlarmClient(telemetry)`** convenience extension.
### Part 16 state machines (generic, extensible)
- **Client**: extension methods on the source-generated
`StateMachineTypeClient` / `FiniteStateMachineTypeClient` ΓÇö
`GetCurrentStateAsync`, `ObserveFiniteTransitionsAsync`
(`IAsyncEnumerable<FiniteStateSnapshot>`), `WaitForStateAsync`,
`GetAvailableStatesAsync` / `GetAvailableTransitionsAsync`. **Vendor
proxies inherit the API automatically** through the generated
inheritance chain.
- **Server**: `StateMachineBuilder` (fluent: `AddState` /
`AddTransition` / `OnCause` / validation) +
`FluentFiniteStateMachineState` ΓÇö declare a Part 16 state machine
without subclassing the abstract base.
- **Alarms alignment**: `AlarmClient.GetShelvingStateAsync` /
`ObserveShelvingTransitionsAsync` surface the API for every alarm's
`ShelvingState` child.
### IAsyncEnumerable streaming subscription
- **`IStreamingSubscription`** with
`SubscribeDataChangesAsync`/`SubscribeEventsAsync` returning
`IAsyncEnumerable<T>` (Channel-backed).
- **`ManagedSession.DefaultStreaming`** ΓÇö lazy shared subscription;
disposed with the session.
- **Helpers** ΓÇö `TakeUntilAsync`, `WithTimeoutAsync`, `TakeAsync`,
`BufferedAsync` for state-machine waits and bounded observation windows.
- **`AlarmStreamExtensions`** ΓÇö
`SubscribeAlarmsAsync`/`SubscribeConditionsAsync`/`SubscribeDialogsAsync`
returning the source-generated record types.
### Address-space model change tracking
- **Server**: `RaiseGeneralModelChangeEvent` on both `CustomNodeManager`
and `AsyncCustomNodeManager`; `ModelChangeAggregator` (in
`Opc.Ua.Server.NodeManager`, used by every node manager) batches changes
per service call; **auto-emit** from `CreateNode`/`DeleteNode` (opt-out
via `ModelChangeEmissionEnabled = false`).
- **Client**: `IModelChangeTracker` subscribes to
`BaseModelChangeEventType` via the streaming subscription, decodes
`ModelChangeStructureDataType` payloads, invalidates the `INodeCache`
per-node.
- **`INodeCache.InvalidateNode(NodeId)`** ΓÇö new interface member (true
per-node eviction in `NodeCache`).
- **`ManagedSession.EnableModelChangeTrackingAsync()`** +
`ManagedSessionOptions.ModelChangeTracking` +
`ManagedSessionBuilder.WithModelChangeTracking()` fluent method.
### Dependency Injection integration
- **`services.AddOpcUa().AddClient(...).AddAlarms()`** ΓÇö registers
`AlarmClientFactory` so DI-hosted apps can resolve a Part 9 client per
session without `new`-ing one manually.
- Cross-link added to the unified DI surface (`AddServer` / `AddClient`
/ `AddComplexTypes` / `AddGdsServer` / `AddLdsServer` /
`AddWotConServer`).
### Quickstart server modernization
- `Quickstarts.Servers/Alarms/AlarmNodeManager.cs` ported to
`AsyncCustomNodeManager` and demonstrates the new `AlarmGroup` +
`AlarmSuppressionEngine` end-to-end via a writable `MaintenanceMode`
boolean that suppresses every member alarm.
### Documentation
- New: `Docs/AlarmsAndConditions.md`, `Docs/StreamingSubscription.md`,
`Docs/ModelChangeTracking.md`, `Docs/StateMachines.md` ΓÇö full
developer guides.
- Updated: `Docs/DependencyInjection.md` (`AddAlarms()` row + section),
`Docs/README.md` index, `Docs/MigrationGuide.md` (Part 9 / Part 16 /
model change tracking sections covering behavior changes + breaking API
surface).
- Sample: `Applications/ConsoleReferenceClient/AlarmClientSample.cs`.
Prepares the repository for a 2.0 release: bumps every version reference
from 1.6 to 2.0, and lands the migration guide describing the 1.5.378 →
2.0 upgrade path. The 1.6 line never shipped, so this is a straight
rename with no historical 1.6 migration content to preserve.
The PR is split into two commits:
1. **`Bump version to 2.0 (next release is a major version change)`** —
version metadata, NuGet metadata, the side documentation, and the
migration agent file.
2. **`[Docs] Close 19 audit gaps in 1.5.378 to 2.0 migration guide`** —
adds and reorganizes `Docs/MigrationGuide.md` to close every gap from a
rigorous code-review audit of the 1.5.378 → 2.0 breaking-change surface.
### Version bump (commit 1)
- `version.json`: `1.6-preview` → `2.0-preview`
- `common.props`: `<VersionPrefix>1.6</VersionPrefix>` →
`<VersionPrefix>2.0</VersionPrefix>`
- `nuget/Opc.Ua.nuspec` and `nuget/Opc.Ua.Symbols.nuspec`: `1.6.0` →
`2.0.0`
- `README.md`: "New in 1.6" → "New in 2.0"
- `Docs/ComplexTypes.md`, `Docs/Observability.md`, `Docs/Sessions.md`:
1.6 → 2.0 mentions
- Renames `.github/agents/opcua-v16-migration.agent.md` →
`.github/agents/opcua-v20-migration.agent.md` and updates the agent
metadata (name, description, trigger phrases, version table)
- `UA.slnx`: solution-items reference updated to the new agent filename
-
`Tools/Opc.Ua.SourceGeneration.Core/Generators/ObjectTypeProxyGenerator.cs`:
two v16 → v20 comment fixes
### Migration guide (commit 2)
Closes 19 gaps from an audit comparing `master378` (1.5.378) with
`master` (2.0). Adds a new top-level **Package, Target Framework and
Dependency Changes** section covering the new `Opc.Ua.Core.Types` and
`Opc.Ua.Security.Certificates` packages, the `LibTypesTargetFrameworks`
netstandard2.0 drop, the NuGet dependency additions/removals, and the
residual Newtonsoft.Json dependency in `Opc.Ua.PubSub`.
In-place additions:
- new H4 for `INodeManager3` under Node States
- `Session.Call` `Variant.From` worked example
- new H3 `Subscriptions and Transports` with H4 verdicts for Durable
subscriptions (source-breaking), PubSub (no source break) and Reverse
connect (no source break)
- new H3 `Telemetry and Logging` covering `ITelemetryContext`
constructor-injection patterns
- `in DataValue` async copy-to-local pattern
- UNSAFE / SAFE pair for `WithPoolNotifications` pooling
- using-alias example for classic vs V2 `SubscriptionOptions`
- "Silent regression" callout for `OnAfterCreate`
- numbered lifecycle ordering for
`ApplicationConfiguration.CertificateManager`
Corrections:
- clarifies that the `SessionReconnectHandler` `[Obsolete]` is still
present in 2.0 (not withdrawn);
- clarifies that the source-generated `ServerCapability` constants vs
the `ServerCapabilityInfo` registry type are distinct;
- disambiguates `ReconnectPolicyOptions` (DTO) from `ReconnectPolicy`
(runtime).
Adds an "Automate the migration" pointer to the forthcoming
`Opc.Ua.CodeFixers` analyzer package, which mechanizes 17 of the
patterns covered in this guide. The analyzer is published in a follow-up
PR.
Introduces a consistent `Microsoft.Extensions.DependencyInjection`
surface across the OPC UA libraries. Every consumer starts from a single
root entry point and chains feature-specific extension methods on a
unified builder. PubSub is intentionally excluded per the original
scope.
```csharp
services
.AddOpcUa() // Stack/Opc.Ua.Core
.AddServer(o => { /* … */ }) // Libraries/Opc.Ua.Server
.AddNodeManager<MyNodeManagerFactory>()
.Services
.AddOpcUa()
.AddClient(o => { /* … */ }); // Libraries/Opc.Ua.Client
```
Manual non-DI constructors (`new ApplicationInstance(...)`, `new
StandardServer(...)`, `new LdsServer(...)`, `new ManagedSession(...)`,
etc.) remain unchanged — DI is purely additive for users who want the
.NET Generic Host to own application lifetime, logging, and
configuration.
### What ships
| Feature library | Method on `IOpcUaBuilder` | Returns |
|----------------------------------------------|-------------------------------------------|--------------------------|
| `Opc.Ua.Core` (root) | `services.AddOpcUa()` | `IOpcUaBuilder` |
| `Opc.Ua.Configuration` | `builder.AddApplicationInstance()` |
`IOpcUaBuilder` |
| `Opc.Ua.Client` | `builder.AddClient(opt => …)` |
`IOpcUaClientBuilder` |
| `Opc.Ua.Client.ComplexTypes` | `builder.AddComplexTypes()` |
`IOpcUaBuilder` |
| `Opc.Ua.Server` | `builder.AddServer(opt => …)` |
`IOpcUaServerBuilder` |
| `Opc.Ua.Gds.Client.Common` | `builder.AddGdsClient(opt => …)` |
`IGdsClientBuilder` |
| `Opc.Ua.Gds.Server.Common` | `builder.AddGdsServer(opt => …)` |
`IGdsServerBuilder` |
| `Opc.Ua.Lds.Server` | `builder.AddLdsServer(opt => …)` |
`ILdsServerBuilder` |
| `Opc.Ua.WotCon.Server` | `builder.AddWotConServer(opt => …)` |
`IWotConServerBuilder` |
| `Opc.Ua.WotCon.Client` | `builder.AddWotConClient(opt => …)` |
`IOpcUaBuilder` |
### Design highlights
- **Binary-safe inheritance** — `IOpcUaBuilder :
IDependencyInjectionBuilder` so any existing `AddLogging(this
IDependencyInjectionBuilder)` callers keep compiling unchanged.
- **Three options overloads** per feature: `Action<TOptions>`
(AOT-safe), `IConfiguration`, `IConfigurationSection`. The two binding
overloads are annotated `[RequiresUnreferencedCode]` /
`[RequiresDynamicCode]`. Section names follow the `OpcUa:<Feature>`
convention (`OpcUa:Server`, `OpcUa:Client`, `OpcUa:Gds:Server`,
`OpcUa:Lds`, …).
- **Generic Host integration** — each server feature (regular, GDS, LDS)
registers its own `BackgroundService`. Marker singletons throw
`InvalidOperationException` on duplicate `.AddServer()` /
`.AddGdsServer()` / `.AddLdsServer()`. A regular server + GDS + LDS can
coexist in one host; each owns its own `IApplicationInstance` produced
by a shared `IApplicationInstanceFactory` so PKI roots, endpoints, and
certificates don't collide.
- **Registration isolation** — node managers registered under the
regular server via `.AddNodeManager<T>()` are wrapped in
`OpcUaServerNodeManagerRegistration` so they don't bleed into the GDS /
LDS hosted services.
- **WoT Connectivity server** composes on top of the regular server
feature: `.AddServer(...).AddWotConServer(...)` registers
`WotConnectivityNodeManagerFactory` as a server node-manager
registration.
- **Unified telemetry** — `services.AddOpcUa()` registers
`ITelemetryContext` via `TryAddSingleton` using a new
`ServiceProviderTelemetryContext` that resolves the host's
`ILoggerFactory` on first use. User-supplied registrations win.
### Removed pre-release DI surface
The pre-release `services.AddOpcUaServer(...)`,
`services.AddOpcUaClient(...)`, `services.AddOpcUaGdsClient(...)`
extensions are deleted. `IClientBuilder` was renamed to
`IOpcUaClientBuilder`. In-repo callers migrated:
- `Applications/MinimalCalcServer/Program.cs`
- `Applications/MinimalBoilerServer/Program.cs`
- `Tests/Opc.Ua.Client.Tests/ClientBuilder/OpcUaClientBuilderTests.cs`
(renamed from `OpcUaClientServiceCollectionExtensionsTests.cs`)
- Docs (`MigrationGuide.md`, `Sessions.md`,
`SourceGeneratedNodeManagers.md`, README, new
`Docs/DependencyInjection.md`)
### csproj audit
Pruned every redundant `Microsoft.Extensions.*` package reference.
`Opc.Ua.Core` already pulls in `Microsoft.Extensions.Diagnostics` and
`Microsoft.Extensions.Logging`, which transitively expose DI / Options /
Configuration.Abstractions / Options.ConfigurationExtensions to every
downstream library. Only `Microsoft.Extensions.Hosting.Abstractions`
stays explicit on the server libraries (it isn't transitively
available). Also pruned redundant `System.Formats.Asn1` (Bindings.Https)
and `System.Collections.Immutable` (Security.Certificates).
### Tests
50 new tests in eight projects:
| Project | Tests |
|--------------------------------------|-------|
| `Opc.Ua.Core.Tests` | 12 |
| `Opc.Ua.Client.Tests` | 4 |
| `Opc.Ua.Client.ComplexTypes.Tests` | 3 |
| `Opc.Ua.WotCon.Tests` | 6 |
| `Opc.Ua.Lds.Tests` | 5 |
| `Opc.Ua.Gds.Tests` | 6 |
| `Opc.Ua.Server.Tests` (integration) | 10 |
| `Opc.Ua.Aot.Tests` (smoke) | 4 |
| **Total** | **50** |
Combined-host integration tests cover the rubber-duck-driven scenarios:
telemetry-context override across legacy and new entry paths, server +
GDS + LDS coexistence with distinct ports and PKI roots,
duplicate-registration rejection, and node-manager isolation across
features.
### AOT
`dotnet publish Tests/Opc.Ua.Aot.Tests -c Release -r win-x64
--self-contained` reports zero `IL2026` / `IL3050` / `IL2104` warnings
from the new DI surface. All generic registrations carry
`[DynamicallyAccessedMembers(PublicConstructors)]`. AOT consumers stick
to the `Action<TOptions>` overload exclusively; the new
`Tests/Opc.Ua.Aot.Tests/HostingAotTests.cs` smoke fixture exercises this
end-to-end.
- implement RequestQueue using Channels
- add event load test
- add event integration test verifying event from server object is received
- fix Client Reconnect Test
- fix DiagnosticsNodeManager not creating RootNotifier for Server object
- add Benchmarks for MonitoredItem.QueueEvent
- add serveral UnitTest for DiagnosticsNodeManager
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: romanett <7413710+romanett@users.noreply.github.com>
Co-authored-by: Marc Schier <marcschier@users.noreply.github.com>
* Use Interfaces Introduced with 1.5.378
Refactor to use interfaces for node managers and server
Replaced concrete types with interfaces (e.g., IMasterNodeManager, ICoreNodeManager, IDiagnosticsNodeManager, IConfigurationNodeManager, IServerBase) across method signatures, properties, and internal structures to improve abstraction and flexibility.
* Refactor CoreNodeManager to be Based on CustomNodeManager2
* Add Test
* Add INodeManager3 with role permission validation
Introduce INodeManager3 interface extending INodeManager2, adding synchronous role permission validation methods. Update all node manager interfaces and classes to use INodeManager3. Extend IAsyncNodeManager with async permission validation methods and update adapters for sync/async bridging. Deprecate FindNodeInAddressSpace in favor of new async FindNodeInAddressSpaceAsync. Refactor MonitoredNode2 to use thread-safe collections and locking for monitored items. Enhance event reporting with security and permission checks. Update constructors and documentation to reflect new interfaces and best practices.
* Implement AsyncCustomNodeManager
* fix comment
* fix
* Add tests
* fix
* Implement better locking strategy
* fix
* Add more tests
* Add tests
* Add tests
* Add Tests
* cleanup
* cleanup
* Add tests that verifies for AnalogItemState the instrument range is checked brefore writing
* only assign new NodeID in default factory if NodeId isNull
* Run all tests also with sampling groups
* Add Docs
* cleanup
* Add chaos test
* fix test
* Enable Durable Subscriptions (#9)
* [Server] Durable Subscriptions (#2683)
* Implement a system test for DurableSubscriptions (#2839)
* Client Side
Co-authored-by: ALTERNATE-DEV\Archie <archie@dreamsandadventures.ca>
* make a static Method CalculateRevisedQueueSize
* Adress review feedback
* fix FilterRetainTests
* Add MonitoredItem Id to Queues
Use NodeIdDictionary where possible
* first proto
* fix reference server
* implement store
* initialize early
* fix issues
* Move to Reference Server & start implementing queue restore
* Persist queues
* Register queues in factory after restore
* Add Docs
* minor fixes
* Test Subscription Restore & Transfer
* fix Durable Subscription Test Browse
* Fix conversion of extension objects
* use CustomConverter for NumericRange
* Adress review Feedback
* Documentation improvements
* Update Readme
* update sampling group manager to work without session
* remove launch settings
* Enable Durable Subscriptions (#9)
* [Server] Durable Subscriptions (#2683)
* Implement a system test for DurableSubscriptions (#2839)
* Client Side
Co-authored-by: ALTERNATE-DEV\Archie <archie@dreamsandadventures.ca>
* make a static Method CalculateRevisedQueueSize
* Adress review feedback
* fix FilterRetainTests
* Add MonitoredItem Id to Queues
Use NodeIdDictionary where possible
* update ServerConfiguration Node to support multiple Application Certificates. Trust List Support for User Certificates & Https Certificates
* GDS ready for ECC Step1
* fix test
* fix build
* ensure hash algorithm is set
* update configurations to new format, fix minor ecc bugs
* implicitly set certificate type of certificate identifier
extend CertificateFactory to allow Revocation with ECC Issuer Certificate
* Revert "update configurations to new format, fix minor ecc bugs"
This reverts commit 9ee17f3aff.
* Allow GDS Certificate Group to have multiple CA Certificates with different Certificate Types
* fix minor bugs
* adress review feedback
* fix some issues
* fix creation of CA signed ECC Certificates
* Update configurations to new ApplicationCertificateFormat and add extra CA Certificates for ECC Certificates
* remove brainpool certs from configuration
* Generate ECC Certificates in Client Tests
* Revert "Generate ECC Certificates in Client Tests"
This reverts commit 90b395f4ff.
* fix crl tests on platforms not supporting ECC
* fix crl test
* Update READMEs for ECC
This PR extends the existing X509 CertificateStore building on top of the .NET X509Store Class to support Certificate Revocation Lists (CRLs) This is important to make the X509Store viable for use as Trust and Issuer Store.
Considerations:
- only Works on Windows, on all other OS the "SupportsCRLs"-Property of the Store still returns false
- builds on top of the Win32 API
- uses source generated P-Invoke calls to call into Win32 API (https://github.com/microsoft/CsWin32)
- makes use of Extension Methods of .NET X509Store Class to make the CRL Enumerate / Add / Delete accessible for the Store Implementation
- guards ever call with OS Support calls and throws PlatformNotSupportedException
- Behaviour of the X509CertificateStore for Linux/MacOS is unchanged
- Added unit tests for the Certificate Store testing all relvant implemented crl functions
- Extended GDS Tests for Integration Testing by utilizing Client & Server making second run on windows with only X509 Stores
The goal is to reduce the overall number of builds, stop using end of life platforms in the build pipeline and to support
build of future/deprecated build targets in a custom build step, which is also triggered weekly in the ci builds.
In addition:
- added a doc which describes the release and versioning strategy of this project
- produce the Nuget packges with .NET 8 assemblies.
- produce a Docker build based on a .NET 8 based container.
- add custom test targets to test outdated platforms. Need a manual step to enable for VS or command line.
- bug fixes: the latest move to an alternate crypto library for Bouncy Castle, which is only used for the GDS support and .NET Framework 4.6.2./netstandard2.0, revealed already a few issues which were previously not found.
- only .NET8/.NET6/.NET Framework 4.8 are tested in Pull requests. Remaining builds in weekly scheduled builds.
- Doc, docs, docs updates for new 368 support
- fix a missing null pointer check when ConditionRefresh is run
- Ref server: move NodeManager factory API to StandardServer, decoupling the NodeManager implementation from Ref server
- Ref server: add shadow mode flag, to allow to map a docker configuration in a mapped folder.
- Ref server: sample batch files how to run Github CR and local docker images
- Improve some misleading 'delete application certificate' log messages.
- support for Microsoft.Extensions.Logger.ILogger in Opc.Ua.Core as the new logging interface
- backward compatible with config and TraceEvents
- new API Utils.SetLogger allows to set ILogger
- updated Console samples to demonstrate ILogger support with Serilog
- support for EventSource logging
- see Docs/Logging.md for more info
- add encode/decode tests for all IEncodeables in Opc.Ua.Core.
- *Breaking change*: ExtensionObject now returns the proper TypeId on decode for known encodeables.
- remove Nuget.Config, it may have caused some intermittent build problems in Azure pipelines
- Code coverage now 39.5%
- Add a few badges for project info
- fix travis build, it only supports .Net Core 2 projects.
- *Breaking change*: SessionlessMessage uses the same TypeId as SessionlessInvokeRequestType which can cause problems in type factory, demoted the structure as not being IEncodeable as it is only used as a helper class in encoders/decoders.
- restructure AzPipeline builds to avoid imtermittent build issues,
Marc Schier