Introduce InvokeAsync, ShowAsync, ShowDialogAsync

[KlausLoeffelmann]

Rationale

[Scenario and API proposal updated to reflect the current eco system.]

A growing number of components in and for WinForms requires to asynchronously marshal an async method to run on the UI-Thread. These are for example APIs around WebView2, projected native Windows 10 and 11 APIs or async APIs from modern libraries for example for Semantic Kernel.

Other scenarios make it necessary to show a Form, a Popup or a MessageBox asynchronously, to be in alignment of other UI stacks like WinUI or .NET MAUI and share/adapt their ViewModel implementations for migration and modernization purposes.

One example where we need to use these APIs is when we need to implement a Login-Dialog in WinForms to authenticate a user on a WebAPI which represents the WinForms App's backend, and which uses Windows WebView2 control and MSALs ICustomWebUI interface for acquiring an authorization code asynchronously.

Since a modern architecture would it make necessary to call this Dialog via an UI-Service from a ViewModel, we would need to show this Form either with ShowAsync or ShowDialogAsync. Inside of the Form, when we would need to navigate to a specific URL and to honor the implementation of ICustomWebUI, we would need to call NavigateAsyncTo which would need to run a) asynchronously and b) on WinForms's UI Thread:

public partial class FormWebLogin : Form, ICustomWebUi
{
    public FormWebLogin()
    {
        InitializeComponent();
        InitializeBrowser();
    }

    /// <summary>
    ///  Implements the <see cref="ICustomWebUi.AcquireAuthorizationCodeAsync(Uri, Uri, CancellationToken)"/> method.
    /// </summary>
    public async Task<Uri> AcquireAuthorizationCodeAsync(
        Uri authorizationUri,
        Uri redirectUri,
        CancellationToken cancellationToken)
    {
        _redirectUri = redirectUri;

        // NavigateToAsync must be called asynchronously AND need to run on the UI thread.
        return await InvokeAsync<Uri>(
            () => NavigateToAsync(authorizationUri),
            cancellationToken);
    }

The following is a demo which utilizes InvokeAsync with the Periodic Timer, demos parallelized rendering into the WinForms's GDI+ Graphics surface and also shows off the new Windows title bar customizing (which is part of the Dark Mode features):

API Suggestion:

Note: We suggest for .NET 9 to implement the new APIs under the Experimental attribute, so we can collect and react to respective feedback, and then introduce the new APIs finally in .NET 10.

namespace System.Windows.Forms;

public static partial class TaskDialog
{
    public static Task<TaskDialogButton> ShowDialogAsync(nint hwndOwner, TaskDialogPage page, TaskDialogStartupLocation startupLocation, CancellationToken cancellationToken);
    public static Task<TaskDialogButton> ShowDialogAsync(IWin32Window win32Window, TaskDialogPage page, TaskDialogStartupLocation startupLocation, CancellationToken cancellationToken);
    public static Task<TaskDialogButton> ShowDialogAsync(TaskDialogPage page);
    public static Task<TaskDialogButton> ShowDialogAsync(TaskDialogPage page, CancellationToken cancellationToken);
    public static Task<TaskDialogButton> ShowDialogAsync(TaskDialogPage page, TaskDialogStartupLocation startupLocation);
    public static Task<TaskDialogButton> ShowDialogAsync(TaskDialogPage page, TaskDialogStartupLocation startupLocation, CancellationToken cancellationToken);
}

public partial class Form
{
    public Task ShowAsync(IWin32Window? owner = null, CancellationToken cancellationToken = default);
    public Task<DialogResult> ShowDialogAsync();
    public Task<DialogResult> ShowDialogAsync(IWin32Window owner);
    public Task<DialogResult> ShowDialogAsync(CancellationToken cancellationToken);
    public Task<DialogResult> ShowDialogAsync(IWin32Window owner, CancellationToken cancellationToken);
}

public partial class Control
{
    // Awaiting the execution of the UI-Thread-marshalled `Action` or `Func`. 
    // If `Func` returns `Task[<TResult>]` it is also awaited.
    public Task InvokeAsync(Action action);
    public Task InvokeAsync(Action action, CancellationToken cancellationToken);
    public Task InvokeAsync(Func<Task> asyncFunc, CancellationToken cancellationToken);
    public Task<T> InvokeAsync<T>(Func<Task<T>> asyncFunc, CancellationToken cancellationToken);
    public Task<TResult> InvokeAsync<TResult>(Func<TResult> syncFunction);
    public Task<TResult> InvokeAsync<TResult>(Func<TResult> syncFunction, CancellationToken cancellationToken);
}

[KlausLoeffelmann]

[Update: This implementation is no longer valid.]

Oh, and this is the implementation I did so far with which I used in the demo:

        private async Task<T> InvokeAsync<T>(
            Delegate invokeDelegate,
            TimeSpan timeOutSpan = default,
            CancellationToken cancellationToken = default,
            params object[] args)
        {
            var tokenRegistration = default(CancellationTokenRegistration);
            RegisteredWaitHandle? registeredWaitHandle = null;

            try
            {
                TaskCompletionSource<bool> taskCompletionSource = new();
                IAsyncResult? asyncResult = BeginInvoke(invokeDelegate, args);

                registeredWaitHandle = ThreadPool.RegisterWaitForSingleObject(
                    asyncResult.AsyncWaitHandle,
                    new WaitOrTimerCallback(InvokeAsyncCallBack),
                    taskCompletionSource,
                    timeOutSpan.Milliseconds,
                    true);

                tokenRegistration = cancellationToken.Register(
                    CancellationTokenRegistrationCallBack,
                    taskCompletionSource);

                await taskCompletionSource.Task;

                object? returnObject = EndInvoke(asyncResult);
                return (T)returnObject;
            }
            finally
            {
                registeredWaitHandle?.Unregister(null);
                tokenRegistration.Dispose();
            }

            static void CancellationTokenRegistrationCallBack(object? state)
            {
                if (state is TaskCompletionSource<bool> source)
                    source.TrySetCanceled();
            }

            static void InvokeAsyncCallBack(object? state, bool timeOut)
            {
                if (state is TaskCompletionSource<bool> source)
                    source.TrySetResult(timeOut);
            }
        }
    }

[weltkante]

public Task InvokeAsync(
    Func<Task> invokeDelegate,
    TimeSpan timeOutSpan = default,
    CancellationToken cancellationToken = default,
    params object[] args) 

The args make no sense, Func<Task> takes no arguments and if you pass anything but an empty array you'll get an exception (same for the other overload).

Also do you really want BeginInvoke behavior which always interrupts control flow (posting to the message loop) even if you are already on the UI thread? I mean its ok to do if you document it, people can do their own extension method which checks InvokeRequired just like they are doing currently. I only want to make sure its discussed which variant is expected to be the more common use case, immediate execution when already being on the UI thread, or always post like BeginInvoke.

If you divert from BeginInvoke behavior and execute the callback inline on the UI thread then you should also discuss returning ValueTask instead of class Task. I've not got any experience with ValueTask patterns so I'm just throwing this into the discussion for consideration not because its necessarily a good idea. (If you have BeginInvoke behavior and always post there is no point of ValueTask though).

---

Also (without seeing how the private InvokeAsync is called) I suspect this is an overly complex and probably bad approach to implement InvokeAsync, but shouldn't derail the API discussion, implementation can be discussed separately if desired. (For example I'm missing unrolling and awaiting of the Task returned by Func<Task> but maybe its done in the caller. Without having this the Task returned by InvokeAsync would complete before the async callback runs to completion.)

Cancellation also seems suspect

• do we really need both timeout and cancellation token? there exist timeout cancellation tokens. I suspect the API is driven by the implementation here, and the implementation may be particularly bad.
• the implementation of faking a cancellation/timeout after the callback started running seems questionable, I'm not aware of anything else in the framework doing this. As far as I'm aware cancellation is always done before the callback starts, once it starts the callback itself is responsible for observing cancellation. Faking early cancellation while the task still runs to completion in the background may cause issues.

Thats not to say cancellation isn't useful to have in this API, if you do BeginInvoke behavior of posting you may want to cancel your posted callback before it runs.

[terrajobst]

• The scenario makes sense
  • @stephentoub should review this as he's working on adding support for timeout and cancellation token support as part of Developers can have access to more options when configuring async awaitables runtime#47525

namespace System.Windows.Forms
{
    public partial class Control
    {
        public Task InvokeAsync(
            Func<Task> invokeDelegate,
            TimeSpan timeOutSpan = default,
            CancellationToken cancellationToken = default,
            params object[] args
        );
        public async Task<T> InvokeAsync<T>(
            Func<Task<T>> invokeDelegate,
            TimeSpan timeOutSpan = default,
            CancellationToken cancellationToken = default,
            params object[] args
        );
    }
}

[stephentoub]

Just skimming the post now...

Am I understanding correctly that the timeout and CancellationToken don't actually impact the execution of the invokeDelegate, rather they cause the returned task to transition to a completed state even when the invokeDelegate may still be executing?

If so, that's exactly what the new WaitAsync methods will do:
dotnet/runtime#48842
e.g. if there's an existing Task-returning InvokeAsync method, you wouldn't need these overloads, and could instead just do:

await InvokeAsync(() => ...).WaitAsync(cancellationToken, timeout);

That WaitAsync takes the task from the InvokeAsync and returns a task that also incorporates cancellation / timeout, e.g. if cancellation is requested, the task returned from WaitAsync will be canceled even though the task returned from InvokeAsync may still be running.

[noseratio]

Oh, and this is the implementation I did so far with which I used in the demo:

Alternatively, I've been using the following version, modified to support timeOutSpan. I my experience, I never needed timeOutSpan, as CancellationToken was always good enough. Removing timeOutSpan could make it a bit shorter and perhaps a bit more performant, as the linked CancellationTokenSource would be gone too.

public static async Task<T?> InvokeAsync<T>(
    this Control @this,
    Delegate invokeDelegate,
    TimeSpan timeOutSpan = default,
    CancellationToken  = default,
    params object?[]? args)
{
    using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
    if (timeOutSpan != default)
    {
        cts.CancelAfter(timeOutSpan);
    }

    var tcs = new TaskCompletionSource<T?>(TaskCreationOptions.RunContinuationsAsynchronously);
    @this.BeginInvoke(new Action(() =>
    {
        try
        {
            // don't invoke the delegate if cancelled
            cts.Token.ThrowIfCancellationRequested();
            tcs.TrySetResult((T?)invokeDelegate.DynamicInvoke(args));
        }
        catch(Exception ex)
        {
            tcs.TrySetException(ex);
        }
    }), null);

    using (cts.Token.Register(() => tcs.TrySetCanceled()))
    {
        return await tcs.Task;
    }
}

Edited: addressing the comments, here is an updated version that supports both regular and async delegates for invokeDelegate.

[weltkante]

Alternatively, I've been using the following version

Contrary to the original method (where I couldn't see the caller) this is public, thus definitely broken, because it doesn't unwrap and await the task returned by Func<Task> or Func<Task<T>> but instead returns a Task<Task>

When passing an actual async function the Task returned by InvokeAsync completes before the invokeDelegate completes.

In other words, your InvokeAsync does not support async callbacks, it supports calling synchronous callbacks in an async way. While in isolation it may be valid its different from how the rest of the dotnet framework developed.

I believe you shouldn't be writing a catch-all method handling arbitrary delegates. While you could try inspecting the return type of the delegate and "guess" based on its type whether you have to await it, that only works for Task and falls short for other cases. ValueTask and custom implementations will again cause the same problem of completing before the callback completes.

The IMHO correct solution is to only accept Func<Task> and Func<Task<T>>, by forcing the delegate signature to return Task (instead of accepting arbitrary delegates) you ensure the user gets a compiler error instead of runtime bugs. He has then a simple way to fix this compile error, by marking his method async and doing an await if necessary. This will always convert his method into the proper Task-returning signature.

[noseratio]

Contrary to the original method (where I couldn't see the caller) this is public, thus definitely broken, because it doesn't unwrap and await the task returned by Func<Task> or Func<Task<T>> but instead returns a Task<Task>

I guess I see what you mean. That version was for invoking synchronous delegates, and the real code accepts an Action (edited: Func<T?>), not an untyped Delegate:

static async Task<T?> InvokeAsync<T>(this Control @this, Func<T?> func, CancellationToken cancellationToken)

As for async lambdas, I use a different override (similar to how Task.Run does it):

public static async Task<T?> InvokeAsync<T>(
    this Control @this,
    Func<CancellationToken, Task<T?>> asyncFunc,
    CancellationToken cancellationToken = default)
{
    var tcs = new TaskCompletionSource<T?>(TaskCreationOptions.RunContinuationsAsynchronously);
    @this.BeginInvoke(new Action(async () =>
    {
        // we use async void on purpose here
        try
        {
            cancellationToken.ThrowIfCancellationRequested();
            tcs.TrySetResult((T?)await asyncFunc(cancellationToken));
        }
        catch (Exception ex)
        {
            tcs.TrySetException(ex);
        }
    }), null);

    using (cancellationToken.Register(() => tcs.TrySetCanceled()))
    {
        return await tcs.Task;
    }
}

The IMHO correct solution is to only accept Func and Func<Task>, by forcing the delegate signature to return Task (instead of accepting arbitrary delegates) you ensure the user gets a compiler error instead of runtime bugs. He has then a simple way to fix this compile error, by marking his method async and doing an await if necessary. This will always convert his method into the proper Task-returning signature.

Totally agree and that's how I do it in my projects, following the pattern of many others existing APIs in .NET.

Edited, as a matter of fact, @KlausLoeffelmann's version throws for the following code due to the same reason:

private async void Form1_Load(object sender, EventArgs e)
{
    // we're on UI thread
    await Task.Run(async () =>
    {
        // we're on thread pool
        var res = await this.InvokeAsync<bool>(new Func<Task<bool>>(async () => 
        {
            // we're on UI thread
            await Task.Delay(5000);
            return true;
        }));

        // we're on thread pool again
        await Task.Delay(1000);
    });

    // back on UI thread
    MessageBox.Show("Done");
}

BeginInvoke is unaware of the fact that the delegate is async and returns to the caller before Task.Delay(5000) is completed. This of course is solved with a proper override like I mentioned in this post.