Control.InvokeAsync Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
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)
- Source:
- Control.ExtendedStates.cs
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.TaskPublic Function InvokeAsync (callback As Action, Optional cancellationToken As CancellationToken = Nothing) As TaskParameters
- callback
- Action
The synchronous action to execute.
- cancellationToken
- CancellationToken
The cancellation token.
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).
Applies to
InvokeAsync(Func<CancellationToken,ValueTask>, CancellationToken)
- Source:
- Control.ExtendedStates.cs
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.TaskPublic Function InvokeAsync (callback As Func(Of CancellationToken, ValueTask), Optional cancellationToken As CancellationToken = Nothing) As TaskParameters
- callback
- Func<CancellationToken,ValueTask>
The asynchronous function to execute, which takes a CancellationToken and returns a ValueTask.
- cancellationToken
- CancellationToken
The cancellation token.
Returns
A task that represents the asynchronous invoke operation.
Exceptions
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).
Applies to
InvokeAsync<T>(Func<CancellationToken,ValueTask<T>>, CancellationToken)
- Source:
- Control.ExtendedStates.cs
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
A task representing the operation and containing the function's result of type T.
Exceptions
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).
Applies to
InvokeAsync<T>(Func<T>, CancellationToken)
- Source:
- Control.ExtendedStates.cs
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
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).
