Control.InvokeAsync Method

Definition

Namespace:

System.Windows.Forms

Assembly:

System.Windows.Forms.dll

Overloads

InvokeAsync(Action, CancellationToken)	Invokes the specified synchronous callback asynchronously on the thread that owns the control's handle.
InvokeAsync(Func<CancellationToken,ValueTask>, CancellationToken)	Executes the specified asynchronous callback on the thread that owns the control's handle asynchronously.
InvokeAsync<T>(Func<CancellationToken,ValueTask<T>>, CancellationToken)	Executes the specified asynchronous callback on the thread that owns the control's handle.
InvokeAsync<T>(Func<T>, CancellationToken)	Invokes the specified synchronous callback asynchronously on the thread that owns the control's handle.

InvokeAsync(Action, CancellationToken)

Invokes the specified synchronous callback asynchronously on the thread that owns the control's handle.

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

callback

Action

The synchronous action to execute.

cancellationToken

CancellationToken

The cancellation token.

Returns

Task

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).

InvokeAsync(Func<CancellationToken,ValueTask>, CancellationToken)

Executes the specified asynchronous callback on the thread that owns the control's handle asynchronously.

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

callback

Func<CancellationToken,ValueTask>

The asynchronous function to execute, which takes a CancellationToken and returns a ValueTask.

cancellationToken

CancellationToken

The cancellation token.

Returns

Task

A task that represents the asynchronous invoke operation.

Exceptions

InvalidOperationException

The control's handle is not yet created.

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).

InvokeAsync<T>(Func<CancellationToken,ValueTask<T>>, CancellationToken)

Executes the specified asynchronous callback on the thread that owns the control's handle.

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

T

The return type of the asynchronous callback.

Parameters

callback

Func<CancellationToken,ValueTask<T>>

The asynchronous function to execute, which takes a CancellationToken and returns a ValueTask<TResult>.

cancellationToken

CancellationToken

The cancellation token.

Returns

Task<T>

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

Exceptions

InvalidOperationException

The control's handle is not yet created.

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).

InvokeAsync<T>(Func<T>, CancellationToken)

Invokes the specified synchronous callback asynchronously on the thread that owns the control's handle.

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

T

The return type of the synchronous callback.

Parameters

callback

Func<T>

The synchronous function to execute.

cancellationToken

CancellationToken

The cancellation token.

Returns

Task<T>

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).