Table of Contents

Interface IApplicationDispatcher

Namespace
Acuit.Pinpoint.Workstation
Assembly
Acuit.Pinpoint.Workstation.Abstractions.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

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, and Acuit Pinpoint Workstation will log the error. When the caller isn't otherwise explicitly handling a faulted task completion itself, it is usually preferable to treat a faulted task completion as an unexpected application error (i.e., logging it to the application log, submitting it to the crash-reporting service, and stopping Acuit Pinpoint Workstation with an "An unexpected error occurred" message to the user). To do so, 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);

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

The task object representing 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

The task object representing 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>

The task object representing the asynchronous operation.

Type Parameters

TResult

The return value type of the specified delegate.

Remarks

Once the operation completes, the Result property on the returned task object contains the value returned by callback.

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>

The task object representing the asynchronous operation.

Type Parameters

TResult

The return value type of the specified delegate.

Remarks

Once the operation completes, the Result property on the returned task object contains the value returned by callback.

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.