Framework compatibility and validation

This change addresses #11. It does not change the public invocation API or publish a package.

Contract, runtime and SDK are different

The core package has three assets:

ConsumerNormally selected assetValidation scope
.NET 10net10.0Full unit and provider-method E2E suites
.NET 8net8.0Full unit and provider-method E2E suites
.NET 9net8.0Compatible selection; not an independently tested runtime
.NET 6netstandard2.0Full provider-method E2E compatibility check, plus local-package Native/Triple smoke
.NET 7netstandard2.0Compatible selection; not an independently tested runtime
.NET Framework 4.8netstandard2.0Windows package smoke job for Native/Triple and body deadlines; see registry limitations below
Other Standard 2.0 implementationsnetstandard2.0, if their full dependency graph is compatibleNot verified (including Mono/Unity/mobile/AOT)

The full unit and E2E suites also explicitly select the Standard DLL on .NET 8 and .NET 10. Merely running tests on .NET 10 would otherwise select the modern DLL and leave compatibility code untested. E2E target frameworks run sequentially: xUnit collection locks do not extend to another host process, and these tests intentionally share stateful Java fixtures. The workflow runs native .NET 10 first, then the Standard consumer on .NET 6, then native .NET 8. The existing forced-Standard runs on .NET 10/8 remain. Each run has separate log/TRX names; patch-only roll-forward prevents a missing .NET 6 runtime from being replaced by a newer major during validation.

.NET Standard is a reference API contract, not a runtime to install. The application supplies the actual runtime. Building the repository still uses the .NET 10 SDK and a pinned C# 12 language version; examples remain net10.0. Unit projects use net8.0 and net10.0; E2E also targets net6.0 as a Standard consumer. Compiler-only init/record/nullability markers for Standard are internal, not additions to the library's public API.

NuGet compatibility is not a vendor lifecycle promise. Prefer a runtime supported by its vendor; running on an out-of-support runtime is the application‘s decision. In particular, .NET 6 compatibility checks do not suppress SDK end-of-support warnings or extend Microsoft’s runtime support lifecycle. These targets describe packages built from this branch, not historical NuGet releases.

Dependency audit

All direct libraries have a Standard 2.0-compatible asset. The complete resolved consumer graph, not just DubboNet's own target, must be checked.

DependencyVersionReason
DistributedLock.ZooKeeper1.0.0Existing registry/session support, unchanged
nacos-sdk-csharp1.3.10Existing Naming/Config SDK, unchanged; gRPC limitations below
NHessian0.4.3Existing Hessian binding, unchanged
Microsoft.Extensions.DependencyInjection8.0.1Directly used by MyNacos; avoid relying on an SDK transitive dependency
System.Text.Json8.0.6 (Standard only)Explicit Standard dependency; modern assets use the shared framework without relying on package pruning to remove a redundant direct reference
Microsoft.Bcl.AsyncInterfaces8.0.0 (Standard only)Existing public IAsyncDisposable contract
System.Memory4.5.5 (Standard only)BinaryPrimitives/Span used by bounded protocol parsing
System.Threading.Tasks.Extensions4.5.4 (Standard only)ValueTask on the Standard API surface
Microsoft.Extensions.DependencyModel8.0.2 (Standard only)Prevent Nacos' old 3.1 dependency group from selecting Newtonsoft.Json 9.0.1 on Framework

That last difference is visible only when restoring a real Framework consumer. Auditing the netstandard2.0 project alone does not discover every package that a Framework consumer's NuGet graph will choose. The package smoke restores treat NU1901–NU1904 advisory warnings as errors. Do not solve advisory failures by suppressing audit warnings.

Nacos still brings some older Microsoft.Extensions 3.1 packages in its Standard dependency group. A clean advisory scan is not a claim that those upstream packages remain supported; broader SDK/dependency modernization is separate work. Modern assets keep the SDK's modern dependency group.

Compatibility implementation and behavior

Compatibility code is internal under Compatibility. Non-obvious call-site changes also have comments.

  • Waiting: the Standard Task.WaitAsync equivalent abandons only the wait, never cancels a shared registry operation. Timers/registrations are disposed; late failures are observed; the caller's cancellation token is retained.
  • TCP: old array-based async APIs use the existing buffer, not a copied one. Legacy I/O waits remain bounded even if an implementation ignores its token. Only an unpublished connect attempt is disposed to cancel connection setup. A partial-frame write still faults its channel; cancelling an ordinary RPC does not dispose another caller's shared connection.
  • HTTP: net8/net10 keep SocketsHttpHandler, memory-based I/O and native cancellation APIs. A Standard DLL on modern .NET binds the same handler and cancellation-aware HttpContent method at runtime. Legacy HttpClientHandler retains per-handler maximum connections, but has no equivalent per-handler idle-eviction control: MasterConnectionAliveTime follows runtime defaults there, with a warning. No global ServicePointManager/TLS settings are changed.
  • HTTP body deadlines: the legacy fallback disposes only its owned response and bounds its read wait. It retains HttpContent charset/BOM decoding, never cancels/disposes the shared HttpClient or ignores certificate validation.
  • Load balancing: the Standard random source uses per-thread state and unbiased 64-bit rejection sampling, preserving long cumulative weights. Time intervals use a monotonic clock, not wall time or wrapping TickCount.
  • Collections: removing a discovery task by key/value remains atomic, so an older caller cannot remove a newer task. Dictionary copies retain ordinal keys.
  • Protocol parsing: numeric endpoint parsing never performs DNS; trimmed splitting is tested against the runtime's semantics; Hessian chunk copies are bounded, allocation-free array writes with existing size/depth budgets.
  • TCP keepalive: Standard uses named runtime options when present. Older runtimes without those options retain OS keepalive timings/retries and log the limitation, rather than guessing OS-specific numeric constants.
  • Packaging: multi-target outer builds explicitly include LICENSE/NOTICE and historical licensing documents. Local artifact/package caches are excluded from the root source glob (some dependencies contain .cs files).

Runtime light-up is isolated to the Standard path. Trimming/NativeAOT and private reflection policies have not been validated; do not infer their support from the TFM.

Registry and Framework boundaries

ZooKeeper uses its existing session/ephemeral-node behavior. Consumer registration remains optional, shared per registry, and runtime-reconfigurable; retry, session recovery and shutdown unit tests run for each library asset.

Nacos V2 uses Grpc.Net.Client and bidirectional streaming to its gRPC server port (in addition to HTTP port 8848). A netstandard2.0 assembly does not make HTTP/2/gRPC streaming work on every .NET Framework/Windows combination. The existing SDK does not automatically configure the Windows handlers/TLS needed by restricted legacy environments. Full Framework + Nacos 2 Naming/Config support is therefore not claimed, nor is Framework + ZooKeeper certified by the Native/Triple loopback smoke job. Test the application's exact registry/runtime/OS before rollout.

This Nacos gRPC restriction is separate from DubboNet's Triple transport: Triple here is Java-interface unary HTTP/1.1 JSON, not framed gRPC.

References: Microsoft .NET Standard guidance, Microsoft gRPC supported platforms, Nacos SDK gRPC implementation.

Reproducing validation

Normal builds require the .NET 10 SDK; unit tests require .NET 8/10 runtimes, and the full E2E suite also requires the .NET 6 runtime:

dotnet msbuild Tests/PackageCompatibilitySmoke/Prepare.proj
dotnet build DubboNet.sln -c Release -p:GeneratePackageOnBuild=false
dotnet test Tests/UnitTestForDubboNet/UnitTestForDubboNet.csproj \
  -c Release -p:GeneratePackageOnBuild=false
dotnet test Tests/UnitTestForDubboNet/UnitTestForDubboNet.csproj \
  -c Release -p:DubboNetTestTargetFramework=netstandard2.0 \
  -p:GeneratePackageOnBuild=false

The test-only selector restricts the library‘s advertised targets to one, so restore chooses a consistent transitive graph. Test binaries and obj files are isolated by selected library target. Unit tests and all network test/example programs assert the loaded assembly’s TargetFrameworkAttribute before doing RPC. Packing with the selector set is rejected: release packages must contain all assets.

After starting the local fixture environment, run the E2E project normally (sequentially .NET 10, .NET 6, .NET 8) and force Standard on the modern hosts:

export DUBBONET_E2E_ENABLED=true
export DUBBONET_E2E_ZOOKEEPER_ADDRESS=127.0.0.1:2181
export DUBBONET_E2E_NACOS_ADDRESS=nacos://127.0.0.1:8848
dotnet test Tests/DubboNetEndToEndTests/DubboNetEndToEndTests.csproj \
  -c Release -p:GeneratePackageOnBuild=false
for framework in net10.0 net8.0; do
  dotnet test Tests/DubboNetEndToEndTests/DubboNetEndToEndTests.csproj \
    -c Release -f "$framework" -p:DubboNetTestTargetFramework=netstandard2.0 \
    -p:GeneratePackageOnBuild=false
done

Use explicit runtime arguments/environment variables for any non-local registry. No public test IP is a project, documentation or CI default.

A smoke project consumes the actual packed NuGet, never a project reference. It is included in the solution for IDE use. On a fresh checkout, prepare its local package before solution/IDE restore. Run preparation again after library edits when checking the new package; ordinary restore intentionally does not compile or pack:

dotnet msbuild Tests/PackageCompatibilitySmoke/Prepare.proj
dotnet restore DubboNet.sln
dotnet run --project Tests/PackageCompatibilitySmoke/PackageCompatibilitySmoke.csproj \
  -c Release -f net8.0 --no-restore -- net8.0
dotnet run --project Tests/PackageCompatibilitySmoke/PackageCompatibilitySmoke.csproj \
  -c Release -f net10.0 --no-restore -- net10.0
# Optional, requires the .NET 6 runtime:
dotnet run --project Tests/PackageCompatibilitySmoke/PackageCompatibilitySmoke.csproj \
  -c Release -f net6.0 --no-restore -- netstandard2.0
# Windows only, actual Framework execution:
dotnet build Tests/PackageCompatibilitySmoke/PackageCompatibilitySmoke.csproj \
  -c Release -f net48 --no-restore
Tests/PackageCompatibilitySmoke/bin/Release/net48/PackageCompatibilitySmoke.exe netstandard2.0

Preparation works on Windows/macOS/Linux with the .NET 10 SDK. It reads the core version, packs all three assets under a new private prerelease identity, writes artifacts/compatibility/PackageVersion.props, and restores the consumer with advisory warnings treated as errors. Unique identities prevent NuGet from reusing an older DLL cached under the same validation version; no global cache is cleared.

The project explicitly selects its own NuGet.Config even during solution restore, adds the local feed and a project-private package cache, and maps the exact DubboNet ID exclusively to that feed. Other dependencies come from nuget.org. It does not change user/global NuGet settings, publish anything, or fall back to a public release. Missing local packages fail with the preparation command. VS Code uses the same settings without needing command-line source overrides; if an old diagnostic remains after preparation, reload the project/window. See NuGet source-mapping behavior.

Each package smoke verifies selected asset identity, Native Hessian2 and Triple HTTP/JSON round trips, and a stalled HTTP body deadline, all against loopback. The Windows job must execute successfully before claiming Framework runtime validation; cross-compiling net48 on macOS is not execution.

Build and test keeps its existing required job name and adds full Standard unit tests and package smoke checks. E2E retains temporary local Java/registry fixtures, existing method cases, examples, logs and unconditional cleanup, and adds Standard runs. Its .NET 6 check also executes the prepared real NuGet consumer, covering package dependency resolution as well as project-reference behavior. Both workflows and the local E2E runner prepare the package before restoring the solution. No existing tests are skipped or removed.

Local validation snapshot (2026-11-11)

On macOS arm64 with SDK 10.0.201 and the installed .NET 6/8/10 hosts:

  • Full unit suite: 592 passed, 0 failed, 0 skipped in each of four combinations (net8/net8, net10/net10, net8/Standard, net10/Standard). All 556 original cases remain; 36 compatibility cases were added.
  • Provider-method E2E: 156 passed, 0 failed, 0 skipped in each of five combinations: net10/net10, net6/Standard, net8/net8, net10/Standard, net8/Standard. These were rerun through the permanent E2E project against explicitly supplied remote ZooKeeper/Nacos fixtures, with hosts run sequentially. Testhost diagnostics confirmed .NET 10.0.5 / 6.0.36 / 8.0.15, and generated metadata/dependency graphs confirmed the .NET 6 consumer selected Standard; no runtime-major substitution.
  • Standard integration executable: ZooKeeper 54/54, Nacos 32/32. QueryDemo: 12/12 for each registry with Standard and net10 library assets.
  • Separate, uncommitted remote smoke: Standard consumer registration, shared client leases, disable/re-enable without new RPC, and final deregistration passed on both registries. Only uniquely identified test consumers were inspected; their absence was verified during final cleanup.
  • Actual local NuGet consumers on .NET 6/8/10 passed asset selection, Native/Triple round trips and stalled-body deadlines. Framework 4.8 cross-compilation passed. The full consumer dependency graph, including Framework, had no reported NuGet advisories at validation time; the known Newtonsoft.Json 9.0.1 path was removed.
  • Each library asset retained 61 exported types / 1041 public/protected declarations, with no differences from the original public surface. The package contains all three DLL/XML pairs and licensing documents, not test sources or package-cache sources. Partial-target packing is rejected.

Windows execution and Docker-based CI were not run on this macOS machine. The newly configured Windows smoke and temporary-container E2E workflow still need their real GitHub runs; local validation is not represented as a CI approval.

Package restore / IDE follow-up

Project-local source configuration and explicit preparation were verified with ordinary solution restore/build (the smoke project included), repeated preparation with distinct package identities, and .NET 6/8/10 package execution. Native unit suites still passed 592/592 on both .NET 8 and .NET 10.

A source-only checkout under a path containing spaces produced the expected actionable error before preparation, then prepared its own new DubboNet package and restored/built the solution successfully. Its initial fully uncached dependency download hit upstream NuGet EOF failures; the successful retry reused trusted third-party dependency caches, but deliberately did not copy any DubboNet package. No cache deletion, signature bypass or public-release substitution was used.

Review follow-up validation (2026-11-14)

The JSON package reference is now explicitly Standard-only. Both the default pack and a pack with RestoreEnablePackagePruning=false retain System.Text.Json 8.0.6 in the Standard dependency group and omit it from the modern groups. This does not alter dependency declarations made by Nacos itself.

Empty/null string separators now follow the BCL string-array overload without entering a non-advancing loop. Telnet's own connection deadline again retains the original duration-bearing error and state-report messages; cancellation semantics of the shared socket helper are unchanged. Twenty additional cases cover these boundaries, unrelated cancellation, ordinary connection failure and a real loopback connection.

  • Full unit suite: 622 passed, 0 failed, 0 skipped in each of four combinations (net8/net8, net10/net10, net8/Standard, net10/Standard).
  • Provider-method E2E: 156 passed, 0 failed, 0 skipped in each of five combinations (net10/net10, net6/Standard, net8/net8, net10/Standard, net8/Standard).
  • The prepared NuGet consumers on .NET 6/8/10 passed asset selection, Native/Triple round trips and stalled-body deadlines. Framework 4.8 cross-compilation passed; Framework runtime execution still requires Windows CI.
  • Standard and modern assets retain the same 61 exported types / 1041 public/protected declarations, with no public API differences.

These are local results; the updated commit must also pass its GitHub checks.