Version

Asynchronous Paging Data Source (xamDataGrid)

Topic Overview

Purpose

This topic provides instructions on how to create data sources that allow retrieving data from high-latency remote data stores using an asynchronous and paged access strategy.

Required background

The following topics are prerequisites to understanding this topic:

Topic Purpose

This is a group of topics providing an overview of the xamDataPresenter control.

This topic provides step-by-step instructions on how to add a basic xamDataPresenter to your page.

Introduction

Overview

AsyncPagingDataSourceBase is an abstract base class that can be used to build threaded asynchronous paging data sources that are specifically designed to work with the xamDataPresenter family of controls.

The primary responsibility of AsyncPagingDataSourceBase is to coordinate communication between Infragistics' asynchronous and paged VirtualDataSource classes and the xamDataPresenter family of controls which were designed to work in a synchronous non-paged fashion.

AsyncPagingDataSourceBase provides a bridge between the functionality contained in the VirtualDataSource class and the xamDataPresenter family of controls.

The VirtualDataSource class (and its related classes) contains the logic for issuing/predicting page requests and managing threads for asynchronous data access. They do not contain logic to access data using a specific backend protocol – instead they are designed to take care of the fundamental tasks associated with managing and predicting page requests as well as managing threads for asynchronous data access. This allows you to focus on the details of accessing a specific backend via its required protocol by providing derivations for the VirtualDataSource classes that contain the required data access code.

While there is no concrete implementation of AsyncPagingDataSourceBase shipped with the product, an open source reference implementation of an OData data source derived from AsyncPagingDataSourceBase is provided as a GitHub project (see the Sample Application section for more information).

Since the VirtualDataSource class (and its related classes) are not designed for a specific backend protocol, the GitHub project also includes reference implementations of derived VirtualDataSource-related classes (ODataVirtualDataSource, ODataVirtualDataSourceDataProvider and ODataVirtualDataSourceDataProviderWorker) which provide specialized OData-specific functionality.

To use the AsyncPagingDataSourceBase in your data source project you will need to add a reference to the following Nuget package:

  • Infragistics.WPF.DataGrids.Async

For more information on setting up the NuGet feed and adding NuGet packages, you can take a look at the following documentation: NuGet Feeds.

Usage

Summary

To create a concrete data source implementation you will need to provide derived implementations of AsyncPagingDataSourceBase as well as the VirtualDataSource class and its related classes.

For AsyncPagingDataSourceBase, simply derive from the abstract AsyncPagingDataSourceBase class and provide implementations for one or more virtual properties and methods as follows:

  • [required] Override the CreateUnderlyingDataSource method and provide an instance of a VirtualDataSource-derived class.

  • [optional] Override the CanFilter, CanGroup and CanSort properties as needed based on the capabilities of your backend data source. These virtual properties all return false by default.

Note
Note

Refer to the ODataDataSource class in the reference implementation project as an example of an AsyncPagingDataSourceBase derivation.

For VirtualDataSource and its related classes create derivations/implementations that provide the functionality required to access your specific backend:

Note
Note

Refer to the ODataVirtualDataSource class in the reference implementation project as an example of a VirtualDataSource derivation.

  • [required] Create a class that implements IDataSourceVirtualDataProvider.

Note
Note

Refer to the ODataVirtualDataSourceDataProvider class in the reference implementation project as an example of an IDataSourceVirtualDataProvider implementation.

Note
Note

Refer to the ODataVirtualDataSourceDataProviderWorker class in the reference implementation project as an example of an AsyncVirtualDataSourceProviderWorker derivation.

Integration with Data Presenter

The controls from the xamDataPresenter family are designed to work with the AsyncPagingDataSourceBase data source just like any other data source - simply set the control’s DataSource property to an instance of an AsyncPagingDataSourceBase derived class and use the control as you normally would.

There is one significant behavioral difference in the xamDataPresenter noticeable by the end user when using such a data source, and it relates to the fact that data is being accessed asynchronously.

Specifically, as the end user scrolls through records in the xamDataPresenter , the AsyncPagingDataSourceBase issues fetch requests to the backend store and returns immediately without waiting for the data to be returned. While this allows the xamDataPresenter UI to remain responsive, it cannot display the requested data until the backend processes the fetch requests and returns the page containing the requested data.

To provide a cue to the end user that a data fetch is pending, the xamDataPresenter temporarily renders "overlay elements" in the cells area of each record whose data is pending. Once the requested data is received, the control automatically removes the overlay elements and displays the actual data.

To maximize performance and leverage the extended capabilities (if available) of the backend data store, the xamDataPresenter delegates all sorting and filtering operations to the backend via the AsyncPagingDataSourceBase when possible, which eliminates the need for the xamDataPresenter to pull the entire dataset down over the server connection to perform those operations.

Keeping in mind the asynchronous nature of the AsyncPagingDataSourceBase data source, there will be occasions when you may want to query whether the xamDataPresenter is waiting for previously requested data to be returned. The following properties can be used to determine if there are any unsatisfied data requests pending:

Note
Note

This property only reflects the data fetching status of currently visible records. The property will return false even when there are records which are currently "out of view" and awaiting data as long as all "currently in view" records are not awaiting data.

Optimizing performance

You can optimize the performance of a xamDataPresenter which is using the AsyncPagingDataSourceBase data source with the following techniques:

  • Reduce the data returned over the server connection by limiting the number of fields for which data is fetched by setting the FieldsRequested property. By setting this property on the AsyncPagingDataSourceBase to a subset of the fields in the backend schema, you can improve the response time when fetching data from the remote data source. Alternatively you can define a custom field layout in the data presenter which will also result in a request for a subset of the schema fields and ultimately reduce the amount of data transferred over the server connection.

  • Set the size of the logical page (the number of records to fetch) when issuing a request to the backend to return a "page" of data. You can do this using the PageSizeRequested property. By default the page size is set to 200 records. Decreasing the page size can result in quicker fetch times since less data is being returned over the connection for each fetch, but this will result in an increased number of fetches when scrolling thru large amounts of data. The performance/responsiveness of the backend is another factor that can affect your choice of page size.

  • Set the maximum number of logical pages to retain in memory before a request is sent to the backend data source by setting the MaxCachedPages property. A larger cache will result in better performance when requesting pages of data that have already been "seen", at the expense of increased memory usage. The performance/responsiveness of the backend is another factor that can affect your choice of cache size.

Customize overlay elements

You can customize the color of the "overlay elements" (the elements shown by the xamDataPresenter control while waiting for data that has been requested but not yet delivered) by providing a brush with dedicated key.

The following example demonstrates how to customize the color of the overlay elements when using the xamDataGrid control:

In XAML:

<igDP:XamDataGrid>
    <igDP:XamDataGrid.Resources>
        <SolidColorBrush
            x:Key="{x:Static igDP:DataPresenterBrushKeys.DataPendingOverlayBrushKey}"
            Color="Yellow" />
    </igDP:XamDataGrid.Resources>
</Page.Resources>

Limitations

The following features are not supported when using the AsyncPagingDataSourceBase data source:

  • Hierarchical and non-homogenous data are not supported. Only flat homogeneous data is supported.

  • Editing as well as the addition and removal of records is not supported.

  • The xamDataPresenter’s filter dropdown does not include a list of unique data values from the associated column since the data source does not support the ability to query the backend for those unique values.

  • A FieldLayoutSettings.FilterUIType of LabelIcons is not supported it will always resolve to FilterRecord when using this data source since the unique data values that would normally be displayed in the filter dropdown when the label icon is clicked are not available as described in the previous bullet.

  • The following ComparisonOperators are not supported when filtering:

    • Match

    • DoesNotMatch

    • Like

    • NotLike

    • Top

    • TopPercentile

    • Bottom

    • BottomPercentile

  • The following SpecialFilterOperands are not supported:

    • BlanksOperand

    • AverageOperand

  • Grouping is not currently supported.

  • Since the xamDataPresenter optimizes filtering and sorting by delegating to the backend store via the data source, sorting and filtering is only supported for actual data values. Displayed values and unbound column values cannot be used to sort or filter.

Sample Application

Overview

To get more familiar with the usage of the AsyncPagingDataSourceBase component you can explore the sample in GitHub which consist of the following:

An ODataDataSource class which is a concrete implementation of an AsyncPagingDataSourceBase. It is designed to access data exposed via the industrial standard Open Data Protocol (OData) which exposes server-based data via a set of RESTful APIs.

The AsyncPagingDataSourceBase exposes the following properties:

  • FieldsRequested - Returns/sets the list of properties in the data schema to include when fetching data from a remote data source.

  • MaxCachedPages – Returns/sets the maximum number of fetched pages to cache locally.

  • PageSizeRequested – Returns/sets the desired page size (i.e., the number of records returned for each data request) when fetching data from a remote data source.

  • RecordCount – Returns the number of records in the remote data source. (read only)

The ODataDataSource class exposes the following public properties (in addition to those exposed by the AsyncPagingDataSourceBase base class):

  • BaseUri – Returns/sets the root Uri of the OData service endpoint from which to fetch data

  • EntitySet – Returns/sets the desired entity set (table) from which to fetch data. This EntitySet must be exposed by the service found at the location specified by the BaseUri.

  • TimeoutMilliseconds – Returns/sets the desired timeout (in milliseconds) to use when making requests via the OData API.

Note
Note

The BaseUri and EntitySet properties must both be set in order to start the data fetching process.

Location

You can find the ODataDataSource implementation class along with a sample application demonstrating its usage with the xamDataPresenter and a selectable list of several public accessible OData service endpoints, in a GitHub repository at this location:

Alternatively you can download the ODataDataSource implementation in a NuGet package.

Related Content

Topic

The following topic provides additional information related to this topic.

Topic Purpose

This topic explains how to bind the Data Presenter to an XmlDataProvider.

This topic explains how to bind the Data Presenter to a Collection.

This topic explains how to bind the Data Presenter to a DataSet.