Interface IApplicationDispatcher

Namespace

Acuit.Pinpoint.Windows

Assembly

Acuit.Pinpoint.Windows.dll

Provides members for interacting with the main application dispatcher (i.e., the dispatcher used by the main user interface thread).

public interface IApplicationDispatcher

Extension Methods

IApplicationDispatcherExtensions.InvokeTaskAsync(IApplicationDispatcher, Func<Task>, DispatcherPriority)

IApplicationDispatcherExtensions.InvokeTaskAsync<TResult>(IApplicationDispatcher, Func<Task<TResult>>, DispatcherPriority)

Remarks

Using this service, as opposed to simply referencing Application.Current.Dispatcher, allows for easier unit testing.

Some notes about the error-handling behavior of InvokeAsync(Action) and its overloads (which reflect the behavior of Dispatcher.InvokeAsync(Action)):

It returns an awaitable that will complete after the callback executes synchronously, reflecting a fault if the callback throws an exception. The dispatcher assumes that error handling will be performed by the InvokeAsync(Action) caller via the returned Task. If the caller does not observe a fault returned via the returned Task, then UnobservedTaskException will eventually be raised, when the Task's finalizer executes. DefaultErrorHandler (i.e., used by Acuit Pinpoint Workstation) will log the error and exit the application. To raise the unexpected error immediately (which is usually preferred), a pattern like the following can be used:

IApplicationDispatcher _ApplicationDispatcher; // initialized from dependency injection
IErrorHandler _ErrorHandler; // initialized from dependency injection

_ApplicationDispatcher.InvokeAsync(() => { /* code to execute asynchronously */ }).HandleFaultAsUnexpectedException(_ErrorHandler);

Properties

Dispatcher

Gets the application dispatcher.

[Obsolete("This is deprecated and will be removed in a future version.")]
Dispatcher Dispatcher { get; }

Property Value

Dispatcher

Methods

CheckAccess()

Determines whether the calling thread is the thread associated with the application dispatcher.

bool CheckAccess()

Returns

bool

true if the calling thread is the thread associated with the application dispatcher; otherwise, false.

InvokeAsync(Action)

Executes the specified Action asynchronously on the thread the application dispatcher is associated with.

Task InvokeAsync(Action callback)

Parameters

callback Action

A delegate to invoke through the dispatcher.

Returns

Task

A task that represents the asynchronous operation.

Remarks

See the remarks for IApplicationDispatcher for notes about error-handling behavior.

Exceptions

ArgumentNullException

callback is null.

InvokeAsync(Action, DispatcherPriority)

Executes the specified Action asynchronously on the thread the application dispatcher is associated with.

Task InvokeAsync(Action callback, DispatcherPriority priority)

Parameters

callback Action

A delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the dispatcher.

Returns

Task

A task that represents the asynchronous operation.

Remarks

See the remarks for IApplicationDispatcher for notes about error-handling behavior.

Exceptions

ArgumentNullException

callback is null.

InvokeAsync<TResult>(Func<TResult>)

Executes the specified Func<TResult> asynchronously on the thread the application dispatcher is associated with.

Task<TResult> InvokeAsync<TResult>(Func<TResult> callback)

Parameters

callback Func<TResult>

A delegate to invoke through the dispatcher.

Returns

Task<TResult>

A task that represents the asynchronous operation. The value of its Result property contains the value returned by callback.

Type Parameters

TResult

The return value type of the specified delegate.

Remarks

See the remarks for IApplicationDispatcher for notes about error-handling behavior.

Take care when using this when callback is itself an asynchronous method (i.e., it returns a Task or Task<TResult>). Specifically:

• The Task returned by this method will complete when the asynchronous callback method returns synchronously, with its Task as the return value, not when the callback's asynchronous task completes.
• If the callback's asynchronous task faults (i.e., it returns a Task object with a status that is initially or eventually Faulted), the Task returned by this method will not reflect the error, but will reflect a RanToCompletion status.

To avoid these issues, InvokeTaskAsync(IApplicationDispatcher, Func<Task>, DispatcherPriority) or InvokeTaskAsync<TResult>(IApplicationDispatcher, Func<Task<TResult>>, DispatcherPriority) should be used instead.

Exceptions

ArgumentNullException

callback is null.

InvokeAsync<TResult>(Func<TResult>, DispatcherPriority)

Executes the specified Func<TResult> asynchronously on the thread the application dispatcher is associated with.

Task<TResult> InvokeAsync<TResult>(Func<TResult> callback, DispatcherPriority priority)

Parameters

callback Func<TResult>

A delegate to invoke through the dispatcher.

priority DispatcherPriority

The priority that determines in what order the specified callback is invoked relative to the other pending operations in the dispatcher.

Returns

Task<TResult>

A task that represents the asynchronous operation. The value of its Result property contains the value returned by callback.

Type Parameters

TResult

The return value type of the specified delegate.

Remarks

See the remarks for IApplicationDispatcher for notes about error-handling behavior.

Take care when using this when callback is itself an asynchronous method (i.e., it returns a Task) or Task<TResult>). Specifically:

• The Task returned by this method will complete when the asynchronous callback method returns synchronously, with its Task as the return value, not when the callback's asynchronous task completes.
• If the callback's asynchronous task faults (i.e., it returns a Task object with a status that is initially or eventually Faulted), the Task returned by this method will not reflect the error, but will reflect a RanToCompletion status.

To avoid these issues, InvokeTaskAsync(IApplicationDispatcher, Func<Task>, DispatcherPriority) or InvokeTaskAsync<TResult>(IApplicationDispatcher, Func<Task<TResult>>, DispatcherPriority) should be used instead.

Exceptions

ArgumentNullException

callback is null.