All docs
V19.2
19.2
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
18.2
The page you are viewing does not exist in version 18.2. This link will take you to the root page.
18.1
The page you are viewing does not exist in version 18.1. This link will take you to the root page.
17.2
The page you are viewing does not exist in version 17.2. This link will take you to the root page.

Asynchronous Mode

  • 5 min to read

WinForms Dashboard 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.

winforms-async-mode-show

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 after 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:

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:

private void dashboardViewer1_AsyncDataLoading(object sender, DataLoadingEventArgs e) {  
   if (e.DataSourceName == "Object Data Source 1") {  
      e.Data = GetData();  
   }  
} 

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.

Examples

See Also