[API Proposal]: Add async overload of ChangeToken.OnChange

[davidfowl]

Background and motivation

Today it's not possible to use ChangeToken.OnChange to execute asynchronous logic before re-subscribing for new updates. The current API has an Action<T> based callback only. We need an async overload to run async logic so people don't end up using async void or blocking when using this helper.

API Proposal

 namespace Microsoft.Extensions.Primitives;

 public static class ChangeToken
 {
    // existing 
    // public static IDisposable OnChange(Func<IChangeToken?> changeTokenProducer, Action changeTokenConsumer);
    // public static IDisposable OnChange<TState>(
    //     Func<IChangeToken?> changeTokenProducer, Action<TState> changeTokenConsumer, TState state);

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

API Usage

using Microsoft.Extensions.Primitives;

var config = new ConfigurationBuilder().AddJsonFile("config.json", optional: false, reloadOnChange: true)
            .Build();

_ = ChangeToken.OnChange(config.GetReloadToken, async () =>
{
    await Task.Delay(1000);
    Console.WriteLine("Change happened");
});

Alternatives (added by @svick)

• Add a CancellationToken parameter that's canceled when a following change is detected. This would probably be confusing, since not every caller would want to honor it and can be implemented by users if needed.
• Change the name to OnAsyncChange (or similar). For those that use async lambda with OnChange today, this would be less breaking, but they wouldn't automatically get the benefit of the new version.

Risk (added by @svick)

This change means that existing code that uses an async lambda when calling OnChange will change meaning: previously, it compiled to an async void method; with this change, it will be an async Task method, where the callback is re-registered only once the returned Task completes. This could break some users, though the new behavior should be more correct.

Tagging subscribers to this area: @mangod9
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Today it's not possible to use ChangeToken.OnChange to execute asynchronous logic before re-subscribing for new updates. The current API has a Action<T> based callback only (https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.primitives.changetoken.onchange?view=dotnet-plat-ext-6.0). We need an async overload to run async logic so people don't end up using async void or blocking when using this helper.

API Proposal

namespace Microsoft.Extensions.Primitives;

public static class ChangeToken
{
    public IDisposable OnChange(Func<IChangeToken> changeTokenProducer, Func<Task> changeTokenConsumer);
    public IDisposable OnChange<TState>(Func<IChangeToken> changeTokenProducer, Func<TState, Task> changeTokenConsumer, TState state);
}

API Usage

using Microsoft.Extensions.Primitives;

var config = new ConfigurationBuilder().AddJsonFile("config.json", optional: false, reloadOnChange: true)
            .Build();

_ = ChangeToken.OnChange(config.GetReloadToken, async () =>
{
    await Task.Delay(1000);
    Console.WriteLine("Change happened");
});

Alternative Designs

No response

Risks

None

Author:	davidfowl
Assignees:	-
Labels:	api-suggestion, area-System.Threading, untriaged
Milestone:	-

Tagging subscribers to this area: @dotnet/area-extensions-primitives
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Today it's not possible to use ChangeToken.OnChange to execute asynchronous logic before re-subscribing for new updates. The current API has a Action<T> based callback only (https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.primitives.changetoken.onchange?view=dotnet-plat-ext-6.0). We need an async overload to run async logic so people don't end up using async void or blocking when using this helper.

API Proposal

namespace Microsoft.Extensions.Primitives;

public static class ChangeToken
{
    public IDisposable OnChange(Func<IChangeToken> changeTokenProducer, Func<Task> changeTokenConsumer);
    public IDisposable OnChange<TState>(Func<IChangeToken> changeTokenProducer, Func<TState, Task> changeTokenConsumer, TState state);
}

API Usage

using Microsoft.Extensions.Primitives;

var config = new ConfigurationBuilder().AddJsonFile("config.json", optional: false, reloadOnChange: true)
            .Build();

_ = ChangeToken.OnChange(config.GetReloadToken, async () =>
{
    await Task.Delay(1000);
    Console.WriteLine("Change happened");
});

Alternative Designs

No response

Risks

None

Author:	davidfowl
Assignees:	-
Labels:	api-suggestion, untriaged, area-Extensions-Primitives
Milestone:	-

[maryamariyan]

Marked for future. @davidfowl is this a critical feature for 7.0?

[davidfowl]

Critical, no but I can take it to API review and do the implementation if needed for .NET 7. It's currently a pit of failure (I filed this because I saw someone use it in a way that would fail).

[lonix1]

This would be highly appreciated!

Another use case. There's double detection of changes to appsettings.json. There are still open issues for that. Those issues and the docs recommend debouncing the detections. But using the change token approach needs an async overload. (I documented the problem here).

[dazinator]

I worked around this a while ago: https://github.com/dazinator/Changify/blob/develop/src/Changify/Extensions/ChangeTokenExtensions.cs

Basically, in order to use ChangeToken.OnChange you need:

• Func<IChangeToken> produces the token.
• `Action`` is called when the token changes.

So I wrote the above extension method for Func<IChangeToken> so you can do this:

Func<IChangeToken> changeTokenProducer = GetOrInjectThis();

await changeTokenProducer.WaitOneAsync();

// token has been signalled do your async work here.
await MyStuff();

// One draw back of this approach is that it's one execution at a time, i.e so to listen for the next signal you have to make this call again or refactor this into a loop so can be used similar to ChangeToken.OnChange style.

 await changeTokenProducer.WaitOneAsync();

[davidfowl]

One other idea is an IAsyncEnumerable approach?