# Description
`NodeBrowser` was synchronous end to end, so a node manager whose browse
result depends on I/O had nowhere to `await`. The aggregation server
sample is the concrete case: its browser has to browse the aggregated
server, and the only way to write it was `Next() =>
NextAsync().GetAwaiter().GetResult()`, which holds a request worker for
the full remote round trip on every browse.
This is option (1) from the issue, the small non-breaking step:
- `INodeBrowser` and `NodeBrowser` gain `ValueTask<IReference?>
NextAsync(CancellationToken cancellationToken = default)`. The default
completes synchronously with the result of `Next()`, so every existing
browser that only overrides `Next()` keeps working unchanged (the
samples' `MemoryBufferBrowser` and the migration-analyzer test snippets
compile untouched).
- `AsyncCustomNodeManager.BrowseAsync` and `TranslateBrowsePathAsync`
iterate browsers through `NextAsync` with the request's cancellation
token. The loop bodies already awaited; only the iteration could not.
- `DirectoryBrowser` was the one browser the stack ships that blocked on
async I/O. It now awaits the file-system provider enumeration in
`NextAsync` and keeps `Next()` as the bridge for the remaining
synchronous consumers (`UANodeSetHelpers` export, `CustomNodeManager2`).
Cancellation now propagates instead of being reported as an empty
directory.
- The synchronous paths (`CustomNodeManager2`, `CoreNodeManager`
diagnostics, nodeset export) are unchanged on purpose; they have no
place to await.
**Not done, by design.** Browser creation stays synchronous.
`OnCreateBrowser` runs under the node's browse lock, so the documented
contract is that a browser fetches lazily on its first `NextAsync`. The
issue itself notes the async creation seam is not needed for the
aggregation case. `IAsyncEnumerable` (option 3) is not attempted.
**Compatibility note.** A type that implements `INodeBrowser` directly
without deriving from `NodeBrowser` has to add the member. Nothing in
this repo or the samples does that; derived browsers are unaffected.
**Docs** updated in `NodeManagers.md`, `AsyncServerSupport.md`,
`MigrationGuide.md` and `migrate/2.0.x/node-states.md`, with a was/now
example for a browser that previously bridged sync-over-async.
**Tests**
- `NodeBrowserTests` (new): default wrapper completes synchronously and
yields the same sequence as `Next()`, push-back through `NextAsync`, a
`Next`-only override observed through `NextAsync`, an awaited
`NextAsync` override with cancellation.
- `AsyncCustomNodeManagerTests`: a browser whose `Next()` throws is
driven entirely through `NextAsync` by browse, by the continuation-point
round trip (push-back on the async path), and by translate-path.
- `DirectoryObjectStateTests`: the async path of the directory browser,
including the throwing provider and cancellation.
Verified locally: `Opc.Ua.Server` builds on net10.0 and net48 with 0
errors; the browser-related server suites (1342 tests) and the new unit
tests pass on net10.0; `dotnet format whitespace --verify-no-changes` is
clean on the changed files.
## Related Issues
- Fixes#4415
## 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.
- [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.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
romanett