Complete fluent node manager extensibility

[marcschier]

Description

Complete the fluent node-manager extensibility surface needed by dynamic and externally backed address spaces.

This change:

• adds virtual node families with cheap NodeId ownership checks, async materialization, per-operation caching, custom browsing, and family-level callbacks;
• adds monitored-item pre-creation decisions, complete lifecycle hooks, async batch hooks, stack-managed custom monitored items, and subscription-gated polling;
• exposes the startup ApplicationConfiguration to generated manager partials through FluentNodeManagerBase;
• fixes typed builder proxy support, concrete object wrapper types, and fully-qualified generated model composition;
• reports unresolved [NodeManager] namespace expressions as MODELGEN035 instead of silently dropping them;
• documents the new APIs and compatibility behavior.

Related Issues

• Fixes Fluent node manager: no surface for on-demand (virtual) nodes; managers must still override GetManagerHandleAsync/ValidateNodeAsync #4397
• Fixes Fluent node manager: monitored-item lifecycle hooks beyond OnMonitoredItemCreated (deleted/modified/mode) and a subscription-gated value source #4398
• Fixes Fluent node manager: pre-creation monitored-item hook (refuse or substitute a custom MonitoredItem) #4399
• Fixes [NodeManager] partials cannot access the ApplicationConfiguration (forces GenerateFactory = false) #4403
• Fixes [NodeManager(AdditionalNamespaceUris)] silently drops entries that are not string literals #4404
• Fixes Generated typed node manager builder: Simulation() rejects the typed proxy, object wrappers typed as BaseObjectState, unqualified Add{Namespace} call #4405

Validation

• Opc.Ua.Server.Tests on net10.0: 4,886 passed, 5 skipped.
• Opc.Ua.SourceGeneration.Core.Tests on net10.0: 3,807 passed, 8 skipped.
• Opc.Ua.SourceGeneration.Tests on net10.0: 164 passed.
• Runtime and generator regression selections passed on net48.
• Review-feedback validation: 376 fluent tests passed on net10.0; 22 focused tests passed on net48.
• The CI timing regression was repeated five times on net48 and once on net10.0.
• All 266 applicable GitHub Actions and Azure Pipelines checks, including CodeQL and coverage, pass on 83c571423.
• AppVeyor reports an immediate zero-duration no-run failure because appveyor.yml whitelists only the appveyor branch; it did not execute this PR.
• UA.slnx builds successfully for net10.0; affected project builds are warning-free.
• The repository-wide dotnet test UA.slnx invocation is currently blocked by the solution's mixed VSTest/Microsoft.Testing.Platform configuration under the .NET 10 SDK, so the affected test projects were run individually.

Checklist

• I have signed the CLA and read the CONTRIBUTING doc.
• I have added tests that prove my fix is effective or that my feature works and increased code coverage.
• I have added all necessary documentation.
• I have verified that my changes do not introduce (new) build or analyzer warnings.
• I ran all tests locally using the UA.slnx solution against at least .net framework and .net 10, and all passed.
• I fixed all failing and flaky tests in the CI pipelines and all CodeQL warnings.
• I have addressed all PR feedback received.

[Copilot]

🟡 Changes recommended

The new monitored-source reconcile path awaits user callbacks while holding its internal async lock, which can cause deadlocks and operational stalls under real workloads.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR completes the fluent node-manager extensibility surface in Opc.Ua.Server and the model/source-generation tooling needed to support on-demand (virtual) address spaces plus richer monitored-item lifecycle customization, with corresponding tests and docs.

Changes:

• Added fluent support for virtual node families (cheap ownership predicates, async materialization, per-operation caching, custom browsing, and family-level callbacks).
• Added monitored-item pre-creation decisions (refuse/default/custom item) plus full lifecycle and async batch hooks, including subscription-gated polling sources.
• Improved source-generation behavior and diagnostics for [NodeManager] namespace URI binding, plus typed builder/model composition fixes and documentation updates.

File summaries

File	Description
tools/Opc.Ua.SourceGeneration/SourceGenerator.cs	Adds MODELGEN035 diagnostic descriptor for unresolved [NodeManager] namespace expressions.
tools/Opc.Ua.SourceGeneration/NodeManagerAttributeDiscovery.cs	Captures unresolved attribute expressions for [NodeManager] URI arguments.
tools/Opc.Ua.SourceGeneration/ModelCompilation.cs	Reports MODELGEN035 and suppresses emission when [NodeManager] URI expressions are unresolved.
tools/Opc.Ua.SourceGeneration/AnalyzerReleases.Unshipped.md	Documents new analyzer ID MODELGEN035.
tools/Opc.Ua.SourceGeneration.Core/Generators/NodeManagerTemplates.cs	Emits fully-qualified model composer invocation in generated node managers.
tools/Opc.Ua.SourceGeneration.Core/Generators/NodeManagerGenerator.cs	Plumbs model namespace/prefix to templates for qualified generation.
tools/Opc.Ua.SourceGeneration.Core/Generators/FluentBuilderGenerator.cs	Improves typed wrapper state resolution for objects (prefers concrete generated *State).
tests/Opc.Ua.SourceGeneration.Tests/ModelGeneratorTests.cs	Adds tests for MODELGEN035 and constant-resolution behavior.
tests/Opc.Ua.SourceGeneration.Core.Tests/Generators/NodeManagerGeneratorTests.cs	Updates generator tests and adds qualified composer assertion.
tests/Opc.Ua.SourceGeneration.Core.Tests/Generators/FluentBuilderGeneratorTests.cs	Adds test asserting object wrappers use concrete state types.
tests/Opc.Ua.Server.Tests/Fluent/VirtualNodeBuilderTests.cs	Adds coverage for virtual node family behavior and configuration retention.
tests/Opc.Ua.Server.Tests/Fluent/SimulationBuilderExtensionsTests.cs	Ensures Simulation(...) accepts typed builder facades.
tests/Opc.Ua.Server.Tests/Fluent/MonitoredItemFluentTests.cs	Adds tests for monitored-item pre-creation decisions, lifecycle hooks, and subscription-gated polling.
src/Opc.Ua.Server/NodeManager/MonitoredItem/SamplingGroupMonitoredItemManager.cs	Implements ICustomMonitoredItemManager custom monitored-item creation for sampling-group manager.
src/Opc.Ua.Server/NodeManager/MonitoredItem/MonitoredNodeMonitoredItemManager.cs	Implements ICustomMonitoredItemManager custom monitored-item creation for monitored-node manager.
src/Opc.Ua.Server/NodeManager/MonitoredItem/MonitoredItemCreateDecision.cs	Introduces decision/context types to refuse/default/customize monitored-item creation.
src/Opc.Ua.Server/NodeManager/MonitoredItem/ICustomMonitoredItemManager.cs	Adds internal interface + validation helper for stack-managed custom monitored items.
src/Opc.Ua.Server/NodeManager/AsyncCustomNodeManager.cs	Adds pre-creation decision hook, async batch hook, monitored-item attach/detach notifications, and history-read/update interception points.
src/Opc.Ua.Server/Fluent/VirtualNodeBuilder.cs	Adds fluent virtual node family builder and registration plumbing.
src/Opc.Ua.Server/Fluent/RuntimeValueBuilderExtensions.cs	Makes PollEvery work through typed builder facades via attached-builder resolution.
src/Opc.Ua.Server/Fluent/ReferenceBuilderExtensions.cs	Adds fluent monitored-item hook registration through reference builders.
src/Opc.Ua.Server/Fluent/NodeManagerBuilder.cs	Adds virtual-family registry and expands dispatcher with monitored-item routing + batch hooks.
src/Opc.Ua.Server/Fluent/NodeBuilder.cs	Adds new monitored-item lifecycle hook registrations on node builders.
src/Opc.Ua.Server/Fluent/MonitoredSourceRegistry.cs	Adds subscription-gated polling/lifecycle infrastructure for monitored sources.
src/Opc.Ua.Server/Fluent/MonitoredSourceBuilderExtensions.cs	Adds public fluent extensions for subscription-gated sources (OnFirstSubscriber/OnLastSubscriber/PollWhileMonitored).
src/Opc.Ua.Server/Fluent/MonitoredItemBuilderExtensions.cs	Adds manager-level async monitored-item batch hook extensions.
src/Opc.Ua.Server/Fluent/ISimulationBuilder.cs	Makes Simulation(...) work through typed builder facades via attached-builder resolution.
src/Opc.Ua.Server/Fluent/InstanceCreationBuilderExtensions.cs	Adds fluent monitored-item hook registration through instance-creation builders.
src/Opc.Ua.Server/Fluent/INodeBuilder.cs	Extends fluent node builder interface with monitored-item creation + lifecycle hook APIs.
src/Opc.Ua.Server/Fluent/IFluentDispatcher.cs	Extends dispatcher contract for pre-creation decisions, lifecycle routing, and batch hooks.
src/Opc.Ua.Server/Fluent/FluentNodeManagerBase.cs	Centralizes fluent lifecycle forwarding, virtual node resolution, startup configuration exposure, and monitored-source registry wiring.
src/Opc.Ua.Server/Fluent/FluentDelegates.cs	Adds delegate types for monitored-item lifecycle, pre-creation decisions, and monitored-source lifecycle.
src/Opc.Ua.Server/EventIds.cs	Allocates event-id block for monitored source registry logging.
docs/NodeManagers.md	Documents virtual node families, monitored-item creation/lifecycle, subscription-gated sources, typed builder compatibility, and MODELGEN035 behavior.

Review details

• Files reviewed: 34/34 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.