GithubStar/UA-.NETStandard
1
0
Fork 0
mirror of https://github.com/OPCFoundation/UA-.NETStandard.git synced 2026-10-28 14:09:56 +08:00
Code Issues Packages Projects Releases Wiki Activity
2,369 Commits 75 Branches 105 Tags
fuzzing
Commit Graph
14 Commits
Author SHA1 Message Date
Marc Schier e3e7134d56 Merge branch 'channelrefinements' into channelrefinements2 
Resolved NodeSetExportTools.cs conflict by adopting base branch's ResolveExportPath / ExportRoot abstraction (configurable via OPCUA_MCP_EXPORT_ROOT env var) and removing my redundant ResolveAndValidateExportPath helper + NodeSetExportPathValidationTests.cs. Base implementation is functionally a superset of F19's hard-coded LocalAppData approach.
 2026-06-11 13:24:59 +02:00
Marc Schier 04f3d12fa8 [security] Bound the participant metric tag to per-kind cardinality (MEDIUM-4) 
plans/security-assessment.md MEDIUM-4 (unbounded metric cardinality):

opcua.channel.participant.timeout.count and
opcua.channel.participant.recreate.count emit a "participant" tag
whose value was the full per-instance IReconnectParticipant.Id. Two
problems:
  - ClientChannelReconnectParticipant uses
    "{idPrefix}-{Guid.NewGuid():N}" — the suffix made every instance
    permanent in cardinality-retaining metric backends (Prometheus,
    OTLP, Application Insights).
  - Session.ChannelManager.cs:45 used a bare Guid with NO prefix at
    all, so the metric tag was a 32-hex-char string with no way for
    operators to bucket the data.

Fix:
  - Session.ChannelManager.cs:45 — prefix the GUID with "Session-" so
    Session participants follow the same prefix-then-suffix shape as
    ClientChannelReconnectParticipant.
  - ClientChannelManagerMetrics — add a GetParticipantKind helper
    that returns everything before the first '-' (or the full id if
    no '-'). Use it in CreateEndpointParticipantTags and
    CreateEndpointParticipantSuccessTags so the metric tag stays at
    per-kind cardinality ("Session", "Client", …).
  - Full per-instance id continues to flow through Activity tags and
    EventSource events (separate code path in
    ClientChannelManagerDiagnostics) so distributed traces remain
    correlatable.
  - Docs/Sessions.md callout updated to describe the now-bounded
    behavior (was a warning before, now describes the implemented
    semantic and the convention required of custom participants).

Build verified: Stack/Opc.Ua.Core, Libraries/Opc.Ua.Client net10.0 —
0 W, 0 E.
 2026-06-11 12:26:54 +02:00
Marc Schier 2be0f5c4d5 [docs] Document the secure-by-default DI HttpClient fallback and the channel-manager diagnostics surface contract 
Docs/Sessions.md:
  - New subsection "HTTPS factory + OPC UA cert validation:
    secure-by-default fallback" under § 4. Explains the two
    HttpsTransportChannel construction paths, why the factory is
    bypassed when a CertificateValidator is configured, the one-time
    LogWarning, and how a consumer can keep both Polly resilience AND
    OPC UA cert validation by registering the named HttpClient with
    ConfigurePrimaryHttpMessageHandler that wires OPC UA validation
    in themselves.
  - New subsection "Diagnostics surface contract — what tags and
    EventSource fields carry". Codifies what is allowed on Activity
    tags / EventSource events (StatusCode, SymbolicId, LocalizedText
    only) vs what stays in local ILogger.LogDebug (AdditionalInfo,
    inner exception data). Includes the bounded metric tag set with
    enumerated outcome / reason values, the correct
    transient-failure spelling, and a callout that the participant
    tag carries the full per-instance ID (cardinality is bounded by
    live participant count, but workloads with churn should rewrite
    the suffix at the OTel processor).

Docs/DependencyInjection.md:
  - "Channel manager" section adds a security trade-off callout
    pointing operators to the new Sessions.md HTTPS-secure-fallback
    section.
 2026-06-11 10:48:45 +02:00
Marc Schier f7366ada6f Merge branch 'channelrefinements' into channelrefinements2 2026-06-08 19:16:06 +02:00
Marc Schier 81acd947a6 Close channel-manager production gaps and eliminate Tests/.../Gaps/ 
Closes the three carry-forward gaps documented in
Tests/Opc.Ua.Stress.Tests/Channels/Gaps/ (formerly each documented via
an [Explicit] failing test). The realigned tests are relocated to
Channels/Contract/, the [Category("Gaps")] disappears, and the
Gaps/ folder is removed entirely.

G1. Faulted-entry recovery
  Already closed implicitly by Phase E SwapFaultedEntryAsync (PR #3852).
  Test realigned from "expects BadSecureChannelClosed throw" to
  "auto-resets on next ReconnectAsync and reaches Ready" and renamed
  FaultedEntryAutoResetsOnNextReconnectAsync. New file location:
  Tests/Opc.Ua.Stress.Tests/Channels/Contract/FaultedEntryRecoveryTests.cs.
  No production change required; this was a test-vs-design alignment.

G2. Bounded participant timeout
  New ParticipantTimeout on IChannelReconnectPolicy. Default
  Timeout.InfiniteTimeSpan via DIM on net8+/netstandard2.1; legacy TFMs
  opt in via IParticipantTimeoutPolicy (mirrors the existing
  IBudgetAwareChannelReconnectPolicy pattern). ExponentialBackoffChannel-
  ReconnectPolicy sets a sensible default of 30 seconds.
  ChannelEntry.ReactivateParticipantsAsync wraps the participant's
  OnReconnectAsync in WaitAsync(timeout, ct); on timeout the participant
  is reported as TransientFailure for this cycle (the channel-level
  retry policy retries normally; eventually escalates to Faulted via
  the existing MaxAttempts path). A new participant.timeout.count
  metric is emitted per timeout.
  Test realigned from "documents indefinite hang" to "times out within
  bounded wait and surfaces as TransientFailure", renamed
  HungParticipantTimesOutAfterBoundedWaitAsync, and merged into
  Tests/Opc.Ua.Stress.Tests/Channels/Contract/HungParticipantTests.cs.
  The sibling Contract/HungParticipantTests.HungParticipantBlocks-
  ReconnectIndefinitely is also realigned + renamed to
  HungParticipantTimesOutAndOtherParticipantsRecoverAsync. A new
  positive contract test (BoundedParticipantTimeoutHonorsTimeoutAsync)
  guards against false positives. A new live-server integration test
  exercises the timeout via a real ManagedSession in
  Tests/Opc.Ua.Sessions.Tests/ChannelManagerSessionLifecycleIntegration-
  Tests.cs.

G3. RequiresSessionRecreate plumbing
  New RecreateAsync(ct) on IReconnectParticipant. Default no-op via DIM
  on net8+/netstandard2.1; legacy TFMs opt in via
  IRecreateAwareReconnectParticipant. ChannelEntry's switch on
  RequiresSessionRecreate now fire-and-forgets a DispatchRecreate(participant)
  task that invokes RecreateAsync; the manager does NOT block its
  transition to Ready waiting for the recreate (matches the existing
  enum doc that says "the participant is responsible for completing
  its own recreation out of band"). New participant.recreate.count
  + participant.recreate.failure.count metrics emit per dispatch.
  Session.ChannelManager.cs (the Session's IReconnectParticipant
  adapter) overrides RecreateAsync to delegate to the existing
  Session.RecreateInPlaceAsync — this is the actual "wired-through"
  deliverable flagged as PR #3852 carry-forward.
  Test realigned from "documents that nothing is invoked" to "fire-
  and-forget invokes RecreateAsync exactly once", renamed
  RequiresSessionRecreateInvokesRecreateAsync, moved to
  Tests/Opc.Ua.Stress.Tests/Channels/Contract/RecreateDispatchTests.cs.
  The 1 remaining [Ignore]d integration test from PR #3852 is replaced
  by a positive integration test in
  Tests/Opc.Ua.Sessions.Tests/ChannelManagerSessionLifecycleIntegration-
  Tests.cs that simulates BadSessionIdInvalid on reactivation.

Cleanup
  - GapTestBase.cs deleted; unique helpers folded into ContractTestBase.
  - Tests/Opc.Ua.Stress.Tests/Channels/Gaps/ folder deleted.
  - [Category("Gaps")] removed from the codebase.
  - Tests/Opc.Ua.Stress.Tests/README.md "category overview" loses the
    [Explicit] / L5 / Channels/Gaps/ row and the "Add known production
    gaps to Channels/Gaps/" guidance bullet.
  - Docs/Sessions.md "Participant model" subsection documents the new
    RecreateAsync callback and ParticipantTimeout policy property.
  - Pre-existing build-blocker in Applications/Quickstarts.Servers/
    ReferenceServer/ReferenceServerConfigurationNodeManager.cs
    (ObjectIds.SecurityGroups / KeyPushTargets are not on the curated
    Stack/Opc.Ua.Types/Internal/ObjectIds.cs surface) is replaced with
    inline NodeId literals (i=15443 / i=25440) per the docstring above
    the array. This was a separate fix required for the merged tree
    to build end-to-end.

Verified locally on net10.0:
  - Full UA.slnx Release build (CodeQL parity): 0 errors.
  - Tests/Opc.Ua.Stress.Tests Contract filter (faulted recovery,
    recreate dispatch, hung participant, participant result
    aggregation): 9/9 passed.
  - Tests/Opc.Ua.Client.Tests ClientChannelManager filter: 29/29 passed.
  - Tests/Opc.Ua.Sessions.Tests ChannelManager filter: 9/9 passed
    (was 7/7+1 skipped before; the G3 RequiresSessionRecreate
    integration test that was carry-forward [Ignore] is now
    implemented and counted as a pass).
  - No remaining Gaps namespace / Category("Gaps") / GapTestBase
    references anywhere in the tree.
 2026-06-08 18:12:18 +02:00
Marc Schier 5010d421c6 docs: cross-reference Pcap binding integration with IClientChannelManager 
Add a dedicated 'Integration with the central channel manager' section
to Docs/PacketCapture.md spelling out the three properties of the
channel manager (sharing, transparent reconnect, faulted-entry swap)
that flow through to capture for free, plus the standard DI
registration order. Update the in-process-client quick-start to show
the channel manager registered alongside the Pcap binding.

Add a back-link from Docs/Sessions.md 'See also' so readers of the
channel-manager doc discover the capture composition.
 2026-06-08 10:03:32 +02:00
Marc SchierandCopilot 35f974996f Phase A+B: merge stress test projects + rename workflow 
Merge the channel stress suite into Tests/Opc.Ua.Stress.Tests/Channels and move subscription stress tests into Subscriptions.

Drop the standalone Opc.Ua.Channels.Stress.Tests project from UA.slnx, carry over its package needs, enable nullable analysis, and fix analyzer warnings inline.

Rename the channel-manager stress workflow to the umbrella stress-test.yml workflow and point ChaosTCP at the merged project.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
 2026-06-06 16:51:33 +02:00
Marc Schier 06fbbb571f Add channel-manager stress/chaos test suite (Tests/Opc.Ua.Channels.Stress.Tests) 
Layered pyramid (per rubber-duck plan) to exercise every meaningful combination
of the channel-manager + session reconnect machinery shipped in PR #3852:

L1 — Contract (deterministic, fake transport, runs in every PR):
  - CoalescingTests, ParticipantResultAggregationTests,
    RetryBudgetEnforcementTests, HungParticipantTests,
    LeaseLifecycleTests, GateAndBypassTests, KeyAndSharingTests,
    CertRotationContractTests, LeakAccuracyTests
  - 27 tests, all pass.

L2 — Integration (in-process server stop/start, runs in every PR):
  - ServerOutageRecoveryTests, CertRotationLiveTests, FailoverLeaseSwapTests
  - 6 tests, all pass.

L3 — Chaos (TCP proxy with drop/block-accept/stall, nightly category=ChaosTCP):
  - TransparentReconnectChaosTests, SubscriptionSurvivalChaosTests,
    AcceptButStallChaosTests, BlockAcceptChaosTests
  - Seed-driven via ChaosSchedule for reproducibility.

L4 — Soak (manual category=Soak):
  - LongSoakTests (60 min randomized chaos),
    CombinatorialMatrixTests (engine/transfer/subscribe/sessions matrix),
    MemoryStabilitySoakTests (30 min memory snapshots).

L5 — Known-failing gaps ([Explicit], document carry-forward):
  - FaultedEntryResetGapTests, SessionRecreatePlumbingGapTests,
    ParticipantTimeoutGapTests.

Infrastructure in Fakes/ and Helpers/:
  - FakeTransport, FakeChannelBindings, FakeParticipant (configurable fault modes).
  - ChaosBarrier (deterministic barrier eliminates timing flakiness in coalescing tests).
  - TcpChaosProxy (~200 lines; DropAllConnectionsAsync, BlockAcceptAsync, StallForwarding).
  - StressRunner (concurrent workload generator with latency percentiles).
  - ChaosSchedule + ChaosScheduleRunner (pre-generated deterministic event schedule).
  - WaitForQuiescence (ForManagerAsync, EntryRefcountReachesAsync, EntryGoneAsync).
  - MetricsCollector (subscribes to Opc.Ua.ChannelManager EventSource + IMeter).
  - LeakCounters (snapshot-based refcount/cert/entry validation).

CI wiring:
  - .github/workflows/buildandtest.yml now runs Category=Contract|Integration in PR CI.
  - .github/workflows/channel-manager-stress-test.yml runs Category=ChaosTCP nightly with random seed.

Small production-code tweaks discovered while building tests:
  - ClientChannelManager.Managed.cs / .Metrics.cs: minor refactors for testability.
  - Session.cs / Session.ChannelManager.cs / ManagedSession.cs: small adjustments to
    make IClientChannelManager-aware flows easier to assert.

Docs:
  - Docs/Sessions.md section 4 now has a "Testing the channel manager" subsection
    pointing at the test categories with run-and-reproduce commands.

Build: 0 warnings, 0 errors on net10.0.
Tests: 33/33 pass in Category=Contract|Integration.
 2026-06-05 23:17:33 +02:00
Marc Schier 82347dc1da Address PR #3852 review feedback 
- Move all channel-related types into `Stack/Opc.Ua.Core/Stack/Client/Channels/`
  subfolder (#13).
- Un-obsolete `SessionReconnectHandler` and the SessionExtensions
  `ReconnectAsync(connection, ct)` / `(channel, ct)` extensions; remove
  all SRH-related `#pragma warning disable CS0618` suppressions from
  applications and tests. AttachChannel/DetachChannel remain obsolete (#1, #4).
- Remove the shared-budget section from MigrationGuide.md (#3).
- Mark `ManagedSession.AttachChannel`/`DetachChannel` `[Obsolete]` so the
  warning surfaces all the way up the supported API surface (#9).
- Break the `<see cref=…>` line in `Session.ChannelManager.cs` to stay under
  140 chars (#10).
- Move `ChannelManagerSessionFactory` from `Opc.Ua.Gds.Client.Common` into
  `Opc.Ua.Client` as a public, documented session-factory option (#11).
- Audit other client classes for `IClientChannelManager`-aware overloads;
  add `ISessionFactory`-accepting overloads on `GlobalDiscoveryServerClient`,
  `LocalDiscoveryServerClient`, `ServerPushConfigurationClient` so any
  session factory (including `ChannelManagerSessionFactory`) works (#12).
- Refactor MCP server (`OpcUaSessionManager`, `Program`) to use
  `ManagedSession` + DI-resolved `IClientChannelManager`; remove
  `SessionReconnectHandler` and manual keep-alive reconnect (#2).
- ConnectionStateMachine code-style fixes: use named delegate types,
  collapse multi-line callback properties to single lines, swap
  `timeProvider`/`maxTotalReconnectTime` constructor param order,
  fix multi-line declaration (#6, #7, #8).
- HTTPS resilience: confirmed `Microsoft.Extensions.Http` and
  `Microsoft.Extensions.Http.Resilience` 10.6.0 support
  `net472`/`net48`/`netstandard2.1`; removed `#if NET8_0_OR_GREATER`
  gating from `ManagedSessionBuilder` and `OpcUaClientBuilderExtensions`
  and HTTPS csproj package refs (#5).

Verification:
- `Opc.Ua.Client` + `Opc.Ua.Core` + `Opc.Ua.Gds.Client.Common` build
  clean (0 warnings, 0 errors).
- 56/56 core channel-manager / retry-budget / HTTPS factory tests pass.
- 129/129 client (ManagedSession + legacy SRH back-compat + SessionExtensions)
  tests pass.
 2026-06-05 17:22:41 +02:00
Marc Schier 36d67b3d3a [Client] Central channel manager with shared, ref-counted transport channels (#3288) 
Introduces `IClientChannelManager` as the central registry for client-side
transport channels. Sessions and discovery clients now share ref-counted
managed channels per (endpoint, reverse-connect identity); reconnect is
coalesced and notified to attached participants via a new
`IReconnectParticipant` callback interface; service calls are gated by a
three-state lifecycle (`TransportReconnecting` -> `TransportConnectedSessionReactivating`
-> `Ready`) until reactivation completes.

New types in `Stack/Opc.Ua.Core/Stack/Client/`:
- `ManagedChannelKey`, `ChannelState`, `ChannelStateChange`, `ParticipantReconnectResult`
- `IReconnectParticipant`, `IManagedTransportChannel`, `IClientChannelManager`
- `IChannelReconnectPolicy` + `ExponentialBackoffChannelReconnectPolicy`
- `IRetryBudget` + `RetryBudget` (shared retry deadline across the two layers)
- `ClientChannelManager.Managed/Entry/Lease/Metrics/Diagnostics/CertRotation.cs`
  partials with refcount, coalesced reconnect, IMeter instruments, ActivitySource
  + EventSource, and automatic ReconnectAllAsync on certificate rotation.

Session integration (Libraries/Opc.Ua.Client):
- `Session.CreateAsync(IClientChannelManager, ...)` overload constructs a
  Session that shares its channel with co-located participants.
- `Session` implements `IReconnectParticipant`; reactivation handler
  distinguishes Reactivated / RequiresSessionRecreate / TransientFailure /
  FatalForParticipant / FatalForChannel.
- `Session.ReconnectAsync(ct)` automatically delegates to the channel
  manager when wired.
- `Session.RecreateInPlaceAsync` swaps managed-channel leases for
  failover-to-different-endpoint; same-key recreates delegate to manager
  reconnect; explicit channel/connection callers retain legacy behavior.
- KA failure routes through `IClientChannelManager.ReconnectAsync(channel)`.

ManagedSession integration:
- `WithChannelManager(...)` builder + ctor param.
- Two-level retry: channel-mgr handles transparent reconnect; outer
  `ConnectionStateMachine` + `IReconnectPolicy` only triggers on terminal
  channel `Faulted`. Outer-state churn suppressed during channel-mgr
  cycles via `_channelReconnectInProgress` flag wired through
  `IManagedTransportChannel.StateChanged`.
- New `ManagedSession.ChannelStateChanged` event surfaces transparent
  reconnects to UI / health dashboards.
- `ConnectionStateChangedEventArgs.UnderlyingChannelState` populated when
  outer reconnect was triggered by a channel fault.
- Shared `IRetryBudget` propagated to channel-mgr so the two layers
  enforce a single max-total-time instead of compounding multiplicatively.

Discovery/Registration/GDS:
- Channel-manager-aware `CreateAsync` overloads on `DiscoveryClient`,
  `RegistrationClient`, `ServerPushConfigurationClient`,
  `LocalDiscoveryServerClient`, `GlobalDiscoveryServerClient`. Each
  registers a minimal `IReconnectParticipant`; co-located sessions and
  discovery probes targeting the same endpoint share a channel.

HTTPS transport (`Stack/Opc.Ua.Bindings.Https/`):
- New `IOpcUaHttpClientFactory` abstraction.
- HTTPS / OPC-HTTPS channels migrated to `IHttpClientFactory` +
  `Microsoft.Extensions.Http.Resilience` (10.6.0, AOT-compatible on net10
  via source generators; legacy direct-HTTP path retained for older TFMs
  / no-DI consumers).

DI:
- `AddOpcUa().AddClient(...)` registers `IClientChannelManager` and the
  named HTTPS HttpClient + standard resilience handler automatically.
- `ManagedSessionBuilder` resolves the manager from DI when present.

Obsoletions (functional, `[Obsolete]` with guidance):
- `IClientBase.AttachChannel`/`DetachChannel`
- `SessionReconnectHandler`
- `SessionExtensions.ReconnectAsync(connection, ct)` and `(channel, ct)`
  legacy overloads

Tests (~70 new unit + 4 live-server integration fixtures):
- Core: `ClientChannelManagerManagedTests`, `ClientChannelManagerCertRotationTests`,
  `RetryBudgetTests`, `OpcUaHttpClientFactoryTests` (56/56 pass).
- Client: `ManagedSession*Tests` updated (129/129 pass) + back-compat
  suites pass with `#pragma warning disable CS0618`.
- Sessions integration: `ChannelManagerSharing/TransparentReconnect/SessionLifecycle/CertRotation`
  (6 pass, 2 skipped with documented blockers for faulted-entry reset and
  RequiresSessionRecreate end-to-end plumbing).

Builds clean (0 warnings / 0 errors) across all six TFMs (net472, net48,
netstandard2.1, net8.0, net9.0, net10.0).

Docs:
- `Docs/Sessions.md` new section 4 documents the channel manager,
  three-state gating, two-level retry with shared `IRetryBudget`, and
  HTTPS resilience layering.
- `Docs/MigrationGuide.md` migration recipes for the four obsoleted API
  groups.
- `Docs/DependencyInjection.md` channel-manager and HTTPS factory
  registration.
 2026-06-05 15:37:23 +02:00
Marc Schier 8d2402c995 Bump version to 2.0 and land 1.5.378 to 2.0 migration guide (#3819) 
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.
 2026-05-29 08:18:41 +02:00
Marc Schier f3928db05b Add unified Microsoft.Extensions DI surface across OPC UA libraries (#3803) 
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.
 2026-05-25 20:24:53 +02:00
Marc Schier 239a40b183 GC reduction via IPooledEncodeable activator pooling (#3793) 
* GC reduction via IPooledEncodeable activator pooling

Add opt-in activator-level pooling for IEncodeable instances decoded
during V2 subscription publish dispatch. The design replaces the
earlier IAllocator-on-IServiceMessageContext approach (which had a
cross-contamination hazard for non-publish decodes) with a clean
factory-based model where pooling lives on the encodeable activator.

New public API:
- IPooledEncodeable : IEncodeable - opt-in marker with Reuse() method
- PooledEncodeableType<T> : EncodeableType<T> - activator base with
  BoundedObjectPool<T> (lock-free, no new package dependency)
- ISubscriptionManager.PoolNotifications { get; set; }
- ManagedSessionOptions.PoolNotifications { get; init; }
- ManagedSessionBuilder.WithPoolNotifications(bool)

Source-gen:
- All concrete non-abstract structure types (including service
  request/response types) are generated with PooledEncodeableType<T>
  activators and IPooledEncodeable.Reuse() bodies by default
- Derived types use 'new' to hide inherited Reuse/ClearPooledSentinel
  so each concrete type routes through its own activator's pool
- No changes to external design XML files (UA Core Services.xml etc.)
  - poolable selection is hardcoded in the generator

Benchmarks (MonitoredItemNotification, 1000 ops):
- Allocations: 128 KB -> 408 B (~315x reduction)
- Gen0 collections: 29.75 -> 0.09 per 1000 ops

No interface changes to IEncodeable, IDecoder, IServiceMessageContext,
or ISubscriptionNotificationHandler. Handlers retain by copy when
pooling is enabled.
Call IPooledEncodeable.Reuse() on decoded IServiceRequest and
IServiceResponse after the server is done with them:

- TcpTransportListener.OnRequestReceivedAsync: reuse both request
  and response in a finally block after ProcessRequestAsync +
  SendResponse complete
- EndpointBase.InvokeServiceAsync (HTTPS path): same pattern after
  ProcessRequestAsync + BinaryEncoder.EncodeMessage

Walk acknowledged, overflow-evicted, and disposed NotificationMessage
objects and call IPooledEncodeable.Reuse() on their notification
payloads (MonitoredItemNotification, DataChangeNotification,
EventFieldList, EventNotificationList).

Insertion points in Subscription.cs:
- Acknowledge(): after RemoveAt from m_sentMessages
- InnerPublish() overflow: before RemoveRange/Clear on m_sentMessages
- Dispose(): before m_sentMessages.Clear()
- InnerPublish() unsent-message overflow: before RemoveRange on
  the messages list

Replace new T() with XxxActivator.Instance.CreateInstance() for all
server-side notification payload types so instances are rented from
the activator pool instead of heap-allocated:

New static helper ReuseNotificationPayloads() walks the
NotificationMessage.NotificationData, extracts DataChangeNotification
and EventNotificationList via TryGetValue, iterates their items, and
calls Reuse() on each pooled payload.
 2026-05-22 12:42:33 +02:00
Marc Schier bd4543e961 ManagedSession, Pluggable Subscription engine, and fluent builder + DI (#3730) 
- Add new managed session, wrapping session and providing connection management and failover handling
- Add new Subscription engine that can act as alternative to current engine, but is based on channels with worker tasks
- Add a fluent builder for managed session clients
- Replace NodeCache with LruNodeCache, rename ILruNodeCache and LruNodeCache to INodeCache and NodeCache
- Update migration guide and document new functionality.
 2026-05-05 19:09:07 +02:00