Added async overload of ChangeToken.OnChange

[svick]

Fixes #69099.

Adds async (Func<Task>) overloads of ChangeToken.OnChange, so callers can run asynchronous logic when a change token fires without resorting to async void or blocking:

public static IDisposable OnChange(Func<IChangeToken?> changeTokenProducer, Func<Task> changeTokenConsumer);
public static IDisposable OnChange<TState>(Func<IChangeToken?> changeTokenProducer, Func<TState, Task> changeTokenConsumer, TState state);

These match the shape approved in #69099.

Behavior

The existing ChangeTokenRegistration<TState> is refactored into an abstract base class holding the registration/disposal state machine, with SyncChangeTokenRegistration and AsyncChangeTokenRegistration subclasses. The synchronous overloads behave exactly as before.

For the async overloads:

• The consumer is invoked synchronously, so synchronous exceptions from it are propagated to the code that triggers the change token, just like the synchronous overloads.
• The change token is only re-registered once the returned Task completes. Changes that occur while the consumer's task is still in flight are coalesced into a single subsequent invocation.
• Asynchronous faults from the consumer's task cannot be propagated without blocking, so they are left unobserved (observable only through TaskScheduler.UnobservedTaskException). This is documented in the API remarks.
• When the consumer completes synchronously, re-registration happens without allocating an async state machine.

Breaking change

This is a source (not binary) breaking change, as called out in the proposal's Risk section: existing code that passes an async lambda to OnChange previously bound to the Action overload (compiling to async void / fire-and-forget). With these overloads present, such call sites now bind to the Func<Task> overload and re-registration is deferred until the returned task completes. The new behavior is generally more correct. A throwing statement lambda can also become ambiguous between Action and Func<Task> (CS0121); the two pre-existing tests affected were updated with explicit (Action) casts.

Tests

• Null-argument validation for all four overloads.
• Change firing (with and without state) for the async overloads.
• Disposal stops further consumer invocations.
• Re-registration is deferred until the consumer's task completes (in-flight changes coalesce).
• Synchronous consumer exceptions propagate to the trigger; asynchronous faults do not; the subscription survives both.
• Producer exceptions during initial registration propagate to the caller; producer exceptions when the token fires propagate to the trigger (all four overloads).
• Disposal during a running consumer (both from within the consumer and from another thread) suppresses re-registration. The cross-thread case requires real multithreading and is gated with [ConditionalTheory(... IsMultithreadingSupported)].

Note

This PR description was generated by GitHub Copilot.

[Copilot]

Pull request overview

This PR extends Microsoft.Extensions.Primitives.ChangeToken with Task-returning OnChange overloads so consumers can run asynchronous work and delay re-registration until that work completes, and it refactors the internal registration logic to share more between sync and async paths.

Changes:

• Add ChangeToken.OnChange(Func<IChangeToken?>, Func<Task>) and ChangeToken.OnChange<TState>(Func<IChangeToken?>, Func<TState, Task>, TState) public overloads.
• Refactor registration implementation into shared base + sync/async derived registrations.
• Update/add unit tests covering async behavior, disposal while in-flight, and overload binding.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/libraries/Microsoft.Extensions.Primitives/src/ChangeToken.cs	Adds async overloads and refactors internal registration to support deferred re-registration after Task completion.
src/libraries/Microsoft.Extensions.Primitives/ref/Microsoft.Extensions.Primitives.cs	Updates ref assembly to include the new public overloads.
src/libraries/Microsoft.Extensions.Primitives/tests/ChangeTokenTest.cs	Adjusts existing tests for overload binding and adds new tests for async/disposal/coalescing semantics.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

src/libraries/Microsoft.Extensions.Primitives/src/ChangeToken.cs:165

• SetDisposable assumes the incoming disposable is non-null and calls Dispose() on it in the disposed-sentinel race. However, IChangeToken implementations (including this test suite's TestChangeToken) can return null from RegisterChangeCallback, which would make those Dispose() calls throw NullReferenceException under disposal races. Make SetDisposable accept IDisposable? and null-check before disposing so this stays race-safe even when the registration is null.

            private void SetDisposable(IDisposable disposable)
            {
                // We don't want to transition from _disposedSentinel => anything since it's terminal
                // but we want to allow going from previously assigned disposable, to another
                // disposable.
                IDisposable? current = Volatile.Read(ref _disposable);

                // If Dispose was called, then immediately dispose the disposable
                if (current == _disposedSentinel)
                {
                    disposable.Dispose();
                    return;
                }

                // Otherwise, try to update the disposable
                IDisposable? previous = Interlocked.CompareExchange(ref _disposable, disposable, current);

                if (previous == _disposedSentinel)
                {
                    // The subscription was disposed so we dispose immediately and return
                    disposable.Dispose();
                }

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

[rosebyte]

Only a couple of non-blocking comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

[tarekgh]

I left couple of comments, LGTM otherwise.

[github-actions]

Caution

Security scanning requires review for Breaking Change Documentation

Details

The threat detection results could not be parsed. The workflow output should be reviewed before merging.

Review the workflow run logs for details.

Breaking Change Documentation

A breaking change draft has been prepared for this PR.

👉 Click here to create the issue in dotnet/docs

After creating the issue, please email a link to it to
[.NET Breaking Change Notifications]((redacted)

/cc @svick

Note

This documentation was generated with AI assistance from Copilot.

Generated by Breaking Change Documentation for issue #129624 · ● 2.4M · ◷