Skip to main content
A newer version of this page is available. .

Asynchronous Mode

  • 5 minutes to read

The PivotGridControl can perform data-aware operations asynchronously, in a background thread, so that the application is responsive while operations are in progress.

The time-consuming data operations are:

  • data retrieval from remote server
  • sorting
  • grouping
  • filtering
  • summary calculation.

The picture below demonstrates asynchronous operations - the window does not freeze and responds to user actions while the pivot grid recalculates the data.



If the Pivot Grid Control operates with a large dataset, data retrieval, sorting, and filtering may take a considerable amount of time. In a standard (synchronous) mode, the entire application would not respond to user actions until the Pivot Grid Control completes the operations, because the primary UI thread is busy. End-users may notice a small or considerable application freeze.

In asynchronous mode, only the Pivot Grid Control is frozen. The application responds to end-user actions, while the control processes data in a background thread. The Pivot Grid Control displays the loading panel to indicate that it is busy. Th control does not respond to user actions until the operation finishes.

Asynchronous Operations

End-User Operations

You can specify whether data-aware operations caused by end-user actions run synchronously or asynchronously. Set the PivotGridOptionsBehaviorBase.UseAsyncMode property to true and all operations initiated with UI becomes asynchronous.

Operations Run In Code

In code, you can perform both synchronous and asynchronous operations, regardless of the UI settings. All methods whose names end with …Async are asynchronous. It means that they start operation in a background thread and return control to the caller.

The Pivot Grid Control prevents an asynchronous method call while an asynchronous operation is in progress. You can check the PivotGridControl.IsAsyncInProgress property to determine whether an asynchronous operation goes on. The PivotGridControl.UserAction property indicates what operaton the user performs.


You can execute a data-aware operation asynchronously even if there is no special …Async method. Enclose the code that should be executed asynchronously in the PivotGridControl.BeginUpdate - PivotGridControl.EndUpdateAsync method pair. To ensure that the changes apply in case of an exception, wrap it in a try .. finally statement.


You cannot start a data-aware operation in code while another operation runs in a background thread.

Subsequent Actions and Operation Result

Each asynchronous method has an overload that allows you to specify custom actions after the asynchronous operation completes. Pass the AsyncCompletedHandler delegate that performs the required actions as the asyncCompleted parameter.

If the asynchronous method returns data (an operation result), you have to pass a delegate to get the data. The delegate’s result parameter returns an AsyncOperationResult instance. Use the AsyncOperationResult.Value property to obtain the operation result, and the AsyncOperationResult.Exception property to determine whether any exception occurs during operation.

Asynchronous Operation Execution

After an asynchronous operation starts, the Pivot Grid Control performs the following actions:

  1. closes all popup menus and windows, disables the UI and loses focus (if it has focus);
  2. raises the PivotGridControl.AsyncOperationStarting event;
  3. locks access to the pivot grid data through an API, displays a loading panel and runs background calculations.

After background calculations are finished, the Pivot Grid Control does the following:

  1. unlocks access to the pivot grid data through an API, hides the loading panel and activates the UI;
  2. raises the PivotGridControl.AsyncOperationCompleted event;
  3. performs internal handling of the operation result;
  4. executes a custom delegate.

How Events are Handled in Asynchronous Mode

In an asynchronous mode, custom painting events occur before the pivot grid is displayed. They are handled in the primary thread while the pivot grid performs background calculations. This behavior applies to the following events.

For thread safety, you cannot directly access event data while an asynchronous operation is being executed. Otherwise, an exception is thrown.

When handling custom painting events, use the pivot grid’s IThreadSafeAccessible.IsAsyncInProgress property to determine whether the pivot grid performs background calculations. If this property returns false, you can access event data. Otherwise, you should use a thread-safe event parameter to access it.

The event parameter’s ThreadSafeArgs property allows you to obtain a thread-safe event parameter. It provides read-only access to basic event parameter members and allows you to obtain event data when an asynchronous operation is in progress. Event parameter members that cannot be accessed during asynchronous operation do not have corresponding thread-safe event parameter members.


When handling custom painting events, you cannot use PivotGridControl members to access pivot grid data. Use the IThreadSafeAccessible interface members implemented by the PivotGridControl class instead. They allow you to obtain field and group collections, as well as text displayed in field value and data cells.

Member Tables

This section lists methods exposed by the Pivot Grid Control that perform operations asynchronously.

Data Binding

Method Description
PivotGridControl.RefreshDataAsync Reloads data from the control data source and recalculates summaries asynchronously.
PivotGridControl.RetrieveFieldsAsync Creates PivotGridField objects for all fields in a data source asynchronously.
PivotGridControl.SetDataSourceAsync Sets a data source for Pivot Grid Control and loads data asynchronously.
PivotGridControl.SetOLAPConnectionStringAsync Sets a connection string to a cube in an MS Analysis Services database, and loads data from the cube asynchronously.


Method Description
PivotGridControl.ChangeFieldSortOrderAsync Toggles the sort order of the specified field asynchronously.
PivotGridControl.ClearFieldSortingAsync Clears field sorting asynchronously in OLAP mode.
PivotGridControl.SetFieldSortingAsync Sets the specified sort order for the specified field asynchronously.

Layout Operations

Method Description
PivotGridControl.ChangeFieldExpandedAsync Expands or collapses all values of the specified field asynchronously.
PivotGridControl.CollapseAllAsync Collapses all columns and rows in a Pivot Grid Control asynchronously.
PivotGridControl.CollapseAllColumnsAsync Collapses all columns asynchronously.
PivotGridControl.CollapseAllRowsAsync Collapses all rows asynchronously.
PivotGridControl.CollapseValueAsync Collapses the specified column or row asynchronously.
PivotGridControl.ExpandAllAsync Expands all columns and rows in the Pivot Grid Control asynchronously.
PivotGridControl.ExpandAllColumnsAsync Expands all columns asynchronously.
PivotGridControl.ExpandAllRowsAsync Expands all rows asynchronously.
PivotGridControl.ExpandValueAsync Expands the specified column or row asynchronously.

Drill-Down Operations

Method Description
PivotGridControl.CreateDrillDownDataSourceAsync Returns a list of records used to calculate summary values for all cells asynchronously.

Control Update

Method Description
PivotGridControl.EndUpdateAsync Unlocks the Pivot Grid Control after the PivotGridControl.BeginUpdate method call, and starts an asynchronous update.