Asynchronous Mode

• Oct 08, 2023
• 4 minutes to read

WinForms Dashboard Designer and Dashboard Viewer can perform data processing and rendering tasks asynchronously. It means that end users can interact with a dashboard while time-consuming operations are performed in a different thread.

Note

Web Dashboard and WPF Dashboard Control always work asynchronously.

Async Mode Switch

To switch to asynchronous mode, set the Dashboard Viewer’s or Designer’s AsyncMode property to true :

Important

Do not switch modes until data loading is completed.

In asynchronous mode, data operations are performed in a background thread and do not lock the UI thread. Note that the synchronous API methods and events operate in asynchronous mode in the same manner as before. To leverage the new capabilities, use the asynchronous API described in the next section.

Asynchronous Events

Asynchronous events are raised from a background thread and are otherwise identical to the synchronous events.

Handle asynchronous events to retrieve data in the background and do not freeze the application waiting for the time-consuming task to finish.

Initialized

In asynchronous mode, the Initialized event indicates that you can safely access the dashboard items and allows you to retrieve dashboard item data, manage filters and a dashboard state. Handle the following events to perform these operations:

• DashboardViewer.Initialized
• DashboardDesigner.Initialized

When the Initialized event occurs, you can safely call the data access methods - GetItemData , GetUnderlyingData , GetAvailableFilterValues.

AsyncDataLoading and AsyncValidateCustomSqlQuery

Data loading can take a significant amount of time. In asynchronous mode, handle the DashboardViewer.AsyncDataLoading and DashboardViewer.AsyncValidateCustomSqlQuery events to perform time consuming data access operations. These events are raised in the data loading threads and do not affect UI performance.

Asynchronous event handlers should not directly access controls and other objects created in the UI thread. When switching to async mode, refactor your code to move these operations outside the event handler.

Note

Dashboard Designer

The DashboardDesigner.AsyncDataLoading and DashboardDesigner.DataLoading events in asynchronous mode may occur multiple times while you design a dashboard and change the dashboard object model. To improve performance, do not call time-consuming methods in the event handler.

Tip

To fill the DashboardObjectDataSource with data in asynchronous mode, do not call the Fill method. Handle the AsyncDataLoading event, as illustrated in the code snippet below:

• C#
• VB.NET

private void dashboardViewer1_AsyncDataLoading(object sender, DataLoadingEventArgs e) {  
   if (e.DataId == "objectDataSource") {  
      e.Data = GetData();  
   }  
}

Private Sub dashboardViewer1_AsyncDataLoading(ByVal sender As Object, ByVal e As DataLoadingEventArgs) Handles dashboardViewer1.AsyncDataLoading  
   If e.DataId == "objectDataSource" Then  
      e.Data = GetData()  
   End If  
End Sub

Asynchronous Methods

Asynchronous methods can be divided in three groups:

• methods that load external data;
• methods that obtain dashboard data;
• methods indirectly related to loaded data.

Load Data

The methods return the async Task object. You can perform a task asynchronously with the await keyword. If you do not use the await keyword, a call to the asynchronous method executes its synchronous counterpart.

The SetMasterFilterAsync, ClearMasterFilterAsync, PerformDrillDownAsync, PerformDrillUpAsync, SetRangeAsync methods are based on the SetDashboardStateAsync method. They operate with the dashboard state and do not validate their parameters against the current data as opposed to the synchronous methods.

Methods in the current section can take a cancellation token as a parameter.

Get Data

The methods return the generic async Task object - Task<T> , where T is the return type of their synchronous counterparts.

These methods do not block UI and return the result when the dashboard item is loaded and ready to provide data. When all data are loaded, these methods have no advantage over synchronous counterparts.

Get Loaded Data

The methods return the async Task object. Methods in the current section perform the action (change the layout, invoke the dialog) only after the dashboard item loads data. Their synchronous counterparts perform the actions immediately.

See Also

Migrate WinForms Dashboard Application to Asynchronous Mode