Control.InvokeAsync Method

Source:

Control.ExtendedStates.cs

public System.Threading.Tasks.Task InvokeAsync (Action callback, System.Threading.CancellationToken cancellationToken = default);

member this.InvokeAsync : Action * System.Threading.CancellationToken -> System.Threading.Tasks.Task

Public Function InvokeAsync (callback As Action, Optional cancellationToken As CancellationToken = Nothing) As Task

Parameters

Returns

A task that represents the asynchronous invoke operation.

Remarks

When you pass a CancellationToken to this method, the method will return, but the callback will still be executed. The callback will be running on the UI thread and will be also blocking the UI thread. InvokeAsync in this case is just queuing the callback to the end of the message queue and returns immediately, but as soon as the callback gets executed, it will still block the UI thread for the time it is running. For this reason, it is recommended to only execute short sync running operations in the callback, like updating a control's property or similar.

If you want to execute a long-running operation, consider using asynchronous callbacks instead, by making sure that you use either the overload InvokeAsync(Func<CancellationToken,ValueTask>, CancellationToken) or InvokeAsync<T>(Func<CancellationToken,ValueTask<T>>, CancellationToken).

Source:

Control.ExtendedStates.cs

public System.Threading.Tasks.Task InvokeAsync (Func<System.Threading.CancellationToken,System.Threading.Tasks.ValueTask> callback, System.Threading.CancellationToken cancellationToken = default);

member this.InvokeAsync : Func<System.Threading.CancellationToken, System.Threading.Tasks.ValueTask> * System.Threading.CancellationToken -> System.Threading.Tasks.Task

Public Function InvokeAsync (callback As Func(Of CancellationToken, ValueTask), Optional cancellationToken As CancellationToken = Nothing) As Task

Parameters

Returns

A task that represents the asynchronous invoke operation.

Exceptions

Remarks

The callback will be marshalled to the thread that owns the control's handle, and then awaited. Exceptions will be propagated back to the caller. Also note that the returned task is not the task associated with the callback, but a task representing the operation of marshalling the callback to the UI thread. If you need to pass a callback returning a Task rather than a ValueTask, use the ValueTask(Task)'s constructor to create a new ValueTask which wraps the original Task. The CancellationToken will be both taken into account when marshalling the callback to the thread that owns the control's handle, and when executing the callback.

If you want to asynchronously execute a synchronous callback, use the overload InvokeAsync<T>(Func<T>, CancellationToken) or the overload InvokeAsync(Action, CancellationToken).

Source:

Control.ExtendedStates.cs

public System.Threading.Tasks.Task<T> InvokeAsync<T> (Func<System.Threading.CancellationToken,System.Threading.Tasks.ValueTask<T>> callback, System.Threading.CancellationToken cancellationToken = default);

member this.InvokeAsync : Func<System.Threading.CancellationToken, System.Threading.Tasks.ValueTask<'T>> * System.Threading.CancellationToken -> System.Threading.Tasks.Task<'T>

Public Function InvokeAsync(Of T) (callback As Func(Of CancellationToken, ValueTask(Of T)), Optional cancellationToken As CancellationToken = Nothing) As Task(Of T)

Type Parameters

Parameters

Returns

A task representing the operation and containing the function's result of type T.

Exceptions

Remarks

The callback will be marshalled to the thread that owns the control's handle, and then be awaited. Exceptions will be propagated back to the caller. Also note that the returned task is not the task associated with the callback, but a task representing the operation of marshalling the callback to the UI thread. If you need to pass a callback returning a Task<TResult> rather than a ValueTask<TResult>, use the ValueTask<TResult>(Task<TResult>)'s constructor to create a new ValueTask<TResult> which wraps the original Task. The CancellationToken will be both taken into account when marshalling the callback to the thread that owns the control's handle, and when executing the callback.

If you want to asynchronously execute a synchronous callback, use the overload InvokeAsync<T>(Func<T>, CancellationToken) or the overload InvokeAsync(Action, CancellationToken).

Source:

Control.ExtendedStates.cs

public System.Threading.Tasks.Task<T> InvokeAsync<T> (Func<T> callback, System.Threading.CancellationToken cancellationToken = default);

member this.InvokeAsync : Func<'T> * System.Threading.CancellationToken -> System.Threading.Tasks.Task<'T>

Public Function InvokeAsync(Of T) (callback As Func(Of T), Optional cancellationToken As CancellationToken = Nothing) As Task(Of T)

Type Parameters

Parameters

Returns

A task representing the operation and containing the function's result.

Remarks

When you pass a CancellationToken to this method, the method will return, but the callback will still be executed. The callback will be running on the UI thread and will be also blocking the UI thread. InvokeAsync in this case is just queuing the callback to the end of the message queue and returns immediately, but as soon as the callback is executed, it will still block the UI for the time it is running. For this reason, it is recommended to only execute short sync running operations in the callback, like updating a control's property or similar.

If you want to execute a long-running operation, consider using asynchronous callbacks instead, which you use with the overloads of InvokeAsync described below.

Important: Also note that if you use this overload to pass a callback which returns a Task that this Task will NOT be awaited but return immediately and has the characteristics of an "engage-and-forget". If you want the task which you pass to be awaited, make sure that you use either the overload InvokeAsync(Func<CancellationToken,ValueTask>, CancellationToken) or InvokeAsync<T>(Func<CancellationToken,ValueTask<T>>, CancellationToken).