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:

Property	Value
DashboardViewer.AsyncMode	true
DashboardDesigner.AsyncMode	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#

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

VB.NET

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

Method	Description
ReloadDataAsync	Reloads data in the data sources.
SetDashboardStateAsync	Applies the dashboard state to the loaded dashboard.
SetMasterFilterAsync	Selects required elements in the specified master filter item.
ClearMasterFilterAsync	Clears the specified master filter item.
PerformDrillDownAsync	Performs a drill-down for the required element.
PerformDrillUpAsync	Performs a drill-up in the specified dashboard item.
SetRangeAsync	Selects the required range in the specified Range Filter or Date Filter dashboard item.

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

Method	Description
GetItemDataAsync	Returns data displayed in the specified dashboard item.
GetAvailableDrillDownValuesAsync	Identifies values that can be used to perform drill-down in the specified dashboard item.
GetAvailableFilterValuesAsync	Gets values that can be selected in the current state of the master filter item.
GetEntireRangeAsync	Returns the visible range for the specified Range Filter or Date Filter dashboard item.

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

Method	Description
MaximizeDashboardItemAsync	Expands the specified dashboard item to the entire dashboard size.
RestoreDashboardItemAsync	Restores the item size if an item is expanded to the entire dashboard size (maximized).
ShowDataInspectorAsync	Invokes the Data Inspector dialog for the specified dashboard item.

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.