Update NATS.Net to 3.2.0

[Jose Perez Rodriguez (joperezr)]

Description

Updates the NATS client dependency to NATS.Net 3.2.0 in a separate, rollbackable change because the upstream major version has narrow source and concurrency compatibility considerations.

The Aspire integration continues to construct NatsOpts.Default and NatsConnection, so it intentionally inherits NATS.Net 3 defaults:

• Request/reply uses Direct mode instead of SharedInbox, with request/reply semantics preserved. Applications can opt back into SharedInbox through configureOptions.
• Subscription overflow remains BoundedChannelFullMode.DropNewest; the pending capacity increases from 1,024 to 16,384.
• Existing serializers continue to work.
• The moved socket interfaces keep their namespaces and are type-forwarded, so existing callers remain source and binary compatible.

The existing Aspire tracing registration remains unchanged. NATS.Net 3 still emits activities from the "NATS.Net" source, so the current AddSource("NATS.Net") registration remains valid. NATS.Net 3 also introduces a meter with that name, but registering new metrics is intentionally left out of this dependency-only PR because it would be a separate Aspire feature and configuration-surface change.

Breaking changes

Ordinary INatsClient, INatsConnection, and JetStream callers are not affected by an API break. The source break is limited to applications and test fakes that directly implement INatsJSStream or INatsJSConsumer; they must add the members introduced in NATS.Net 3.2:

ValueTask<ConsumerResetResponse> ResetConsumerAsync(
    string consumer,
    ulong seq = 0,
    CancellationToken cancellationToken = default);

ValueTask<ConsumerResetResponse> ResetAsync(
    ulong seq = 0,
    CancellationToken cancellationToken = default);

NATS.Net 3 no longer marks NatsHeaders read-only after publishing. A single headers instance must not be reused across concurrent publishes because the writer and context-aware serializers can access or mutate it concurrently. Create a fresh NatsHeaders instance per publish, or wait for one publish to complete before reusing it:

await connection.PublishAsync(
    "orders.created",
    order,
    headers: new NatsHeaders { ["tenant-id"] = tenantId });

To restore the previous request/reply implementation:

builder.AddNatsClient("nats", configureOptions: options =>
    options with { RequestReplyMode = NatsRequestReplyMode.SharedInbox });

Upstream release notes:

• https://github.com/nats-io/nats.net/releases/tag/v3.0.0
• https://github.com/nats-io/nats.net/releases/tag/v3.2.0
• nats-io/nats.net@v2.8.2...v3.2.0

Rollback is a single PR revert, restoring the NATS.Net 2.8.x dependency.

Dependency availability

NATS.Net 3.2.0 is present in dotnet-public, but its new transitive dependency NATS.Extensions.Microsoft.DependencyInjection 3.2.0 is not. Approved-feed restore currently fails with NU1101 until that package is mirrored. No mirror pipeline was queued because the parent dependency-update run is paused after an unrelated intermediate quarantine failure.

Validation

Approved-feed validation is blocked before compilation: a forced, no-cache restore of Aspire.NATS.Net.Tests fails because NATS.Extensions.Microsoft.DependencyInjection 3.2.0 is unavailable from the approved feeds. Therefore, this PR currently has no build or test result that counts toward readiness.

A temporary local package source was used during investigation before this restriction was clarified. Those results are intentionally excluded from readiness claims; the local source, package artifact, and validation config were removed and are not committed.

Fixes # (issue)

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 20043

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 20043"

[Copilot]

Copilot review overview

🟡 Changes recommended

Approved-feed restore fails until the new transitive dependency is mirrored and validation succeeds.

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

Review tier: Balanced
Findings: 1

New issues introduced by this change (1)

Severity	Finding
	Directory.Packages.props — Mirror the new transitive dependency before merging

What changed in this PR

Updates the NATS client integration from 2.8.0 to 3.2.0 and documents compatibility considerations.

Changes:

• Upgrades the centrally managed NATS.Net dependency.
• Documents changed defaults and interface requirements.

File	Description
Directory.Packages.props	Updates NATS.Net to 3.2.0.
src/​Components/​Aspire.NATS.Net/​README.md	Adds NATS.Net 3 migration guidance.

[github-actions]

Tests selector

Selects the full PR test matrix + all PR-gated jobs (ALL) — a rule matching 'Directory.Packages.props' selects ALL

Advisory workflow impact (4)

• Aspire.Deployment.EndToEnd.Tests (deployment workflow-only)
• Aspire.EndToEnd.Tests (outerloop-only)
• Aspire.Oracle.EntityFrameworkCore.Tests (outerloop-only)
• deployment-e2e (schedule/dispatch-only)

---

Selection computed for commit 3d33beb.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.