Documentation:IAsyncSupportService

IAsyncSupportService

This page was created by Alexandra on 2018-01-09. Last edited by Wikiadmin on 2026-07-29.

The IAsyncSupportService is for developers building MDriven desktop clients who need to run EcoSpace business and persistence work away from the UI thread while returning UI updates safely to the UI thread.

What it does

An EcoSpace can coordinate work between two threads through IAsyncSupportService:

The Async thread performs time-consuming business logic and persistence-server communication.
The UI thread (also called the main thread) responds to user input and redraws views.

Use this service when a UI action, such as a button click or menu command, starts work that may load data, save data, or wait for a server response. Keeping that work on the Async thread allows the UI thread to continue processing user interaction and refreshes.

For example, a command can load and process data on the Async thread, then update a text box or open a window on the UI thread.

C# async/await addresses a different pattern: adapting code to APIs that already use C# asynchronous operations. For generic MDriven client code that must separate EcoSpace work from UI work, use IAsyncSupportService.

When you need it

WECPOF uses IAsyncSupportService internally. When you use WECPOF, you normally do not need to coordinate its threads yourself.

When you are not using WECPOF, follow these rules:

Work	Run it on	Example
Business logic and persistence-server communication	Async thread	Load objects, save changes, or process a result returned by a server.
Direct access to UI components	UI thread	Set a text box value directly, show a window, compile a report through a UI action, or otherwise manipulate a UI control outside data binding.

Do not access UI controls directly from the Async thread. Dispatch the UI-specific part of the work back to the UI thread.

Get the service

Get the service from the EcoSpace before scheduling work:

IAsyncSupportService asyncSupport =
    _RootHandle.EcoSpace.GetEcoService<IAsyncSupportService>();

The examples below use asyncSupport for this service instance.

Run work on the Async thread

Use PerformTaskNowIfInAsyncThread

Use PerformTaskNowIfInAsyncThread when code must execute on the Async thread. The callback is the place for business logic and persistence communication.

IAsyncSupportService asyncSupport =
    _RootHandle.EcoSpace.GetEcoService<IAsyncSupportService>();

asyncSupport.PerformTaskNowIfInAsyncThread(() =>
{
    // Run business logic and persistence communication here.
    // Do not directly manipulate UI controls here.
});

Use PerformTaskAsync from a UI action

Use PerformTaskAsync when a UI event starts potentially slow work. Put the business operation in its callback, then use DispatchTaskToMainThread for the UI update.

IAsyncSupportService asyncSupport =
    _RootHandle.EcoSpace.GetEcoService<IAsyncSupportService>();

asyncSupport.PerformTaskAsync(() =>
{
    // Async thread: load, save, or process data here.
    string message = "Data processing is complete";

    asyncSupport.DispatchTaskToMainThread(() =>
    {
        // UI thread: update a control or show a window here.
        // statusTextBox.Text = message;
    });
});

For example, a button handler can schedule a save operation with PerformTaskAsync. When the save operation has finished, dispatch a callback that changes the status text displayed to the user. The persistence operation stays off the UI thread; the control update stays on it.

Write UI-initiated business operations this way consistently. A slow network response can then delay the result without making the UI thread perform that persistence work.

Enable or disable asynchronous handling

IAsyncSupportService exposes these methods:

void TurnOnAsyncHandling();
void TurnOffAsyncHandling();

When asynchronous handling is off, PerformTaskAsync and DispatchTaskToMainThread execute directly. Code structured with the scheduling and dispatch calls can therefore work with handling enabled or disabled, but it only receives the thread separation when handling is enabled.

The documented platform guidance is:

Platform	Guidance
Silverlight with persistence	Async handling must be on.
New WPF and WinForms applications	Leave async handling on and run business logic in Async tasks.
ASP.NET	Turn async handling off; it is off by default.

Configure a platform dispatcher equivalent

In the .NET Standard API, a WPF Dispatcher is not available as a general platform type. When you enable async handling on a platform such as WPF, inject an equivalent implementation of System.ComponentModel.ISynchronizeInvoke. Do this when you turn async handling on.

EcoServiceHelper.GetAsyncSupportService(_ecospace).TurnOnAsyncHandling();
EcoServiceHelper.GetAsyncSupportService(_ecospace)
    .InjectThePlatformDispatcherEqvivalent(
        new DispatcherSynchronizeInvoke(
            System.Windows.Threading.Dispatcher.CurrentDispatcher));

DispatcherSynchronizeInvoke is provided by ECO.WPF for .NET Framework and by MDriven.WPF.core for .NET 8. For package and migration context, see Documentation:MDriven 7.2.

Inform the user that work is running

A responsive UI can still be waiting for data. Subscribe to the events exposed by IAsyncServiceHelper to show that queued Async work is in progress and to detect exceptions from the Async thread.

Event	Use it for	Example UI behavior
`AsyncExceptionsEvent`	Receive exceptions from the Async thread.	Show or log an error indication.
`AsyncQueueHasFormedEvent`	Detect that Async work has been queued.	Start a busy or loading animation.
`AsyncQueueDissolvedEvent`	Detect that the queued Async work has completed.	Stop the busy or loading animation.
`AsyncQueueTickEvent`	Receive progress ticks while the queue exists.	Advance or refresh a progress indicator.

For example, start a loading animation when AsyncQueueHasFormedEvent occurs and stop it when AsyncQueueDissolvedEvent occurs. Handle AsyncExceptionsEvent so failures in Async work are visible instead of appearing as an unexplained absence of results. WECPOF uses these notifications for loading and error indicators.

Example: return a server result to the UI

The following pattern separates a background operation from the notification shown to the user. The operation belongs on the Async thread; the notification belongs on the UI thread.

IAsyncSupportService asyncSupport =
    _RootHandle.EcoSpace.GetEcoService<IAsyncSupportService>();

asyncSupport.PerformTaskAsync(() =>
{
    // Async thread: perform server or business work.
    string resultMessage = "The server operation finished.";

    asyncSupport.DispatchTaskToMainThread(() =>
    {
        // UI thread: present the result through the UI.
        // resultTextBox.Text = resultMessage;
    });
});

A checksum example that performs background communication and dispatches user notifications to the main thread is available in Documentation:PersistenceMapperWEBAPIClient.

Contents