XPServerCollectionSource Class

The data source for a GridControl and GridLookUpEdit controls that binds these controls to data in Server Mode.

Namespace: DevExpress.Xpo

Assembly: DevExpress.Xpo.v21.1.dll

NuGet Package: DevExpress.Xpo

Declaration

C#

public class XPServerCollectionSource :
    Component,
    ISupportInitializeNotification,
    ISupportInitialize,
    IListSource,
    IXPClassInfoAndSessionProvider,
    IXPClassInfoProvider,
    IXPDictionaryProvider,
    ISessionProvider,
    IObjectLayerProvider,
    IDataLayerProvider,
    IColumnsServerActions,
    IDXCloneable

VB.NET

Public Class XPServerCollectionSource
    Inherits Component
    Implements ISupportInitializeNotification,
               ISupportInitialize,
               IListSource,
               IXPClassInfoAndSessionProvider,
               IXPClassInfoProvider,
               IXPDictionaryProvider,
               ISessionProvider,
               IObjectLayerProvider,
               IDataLayerProvider,
               IColumnsServerActions,
               IDXCloneable

Remarks

Server mode allows a data-aware control to rapidly work with large datasets. Loading records in small portions on demand, and performing data-aware operations on the data server side are the key features of server mode. Currently, server mode is supported by the GridControl, SearchLookUpEdit and GridLookUpEdit controls.

The XPServerCollectionSource class can be used as a data source for a control in server mode (the control must support the server mode feature). In server mode, a data-aware control needs to be bound to a data source that implements the DevExpress.Data.IListServer interface. The XPServerCollectionSource component implements the IListSource interface, and returns the list implementing the IListServer interface via the IListSource.GetList method.

The XPServerCollectionSource object serves as a conduit of information between the control and a target data store. When the control needs to display a specific portion of data, it calls a certain method of the bound XPServerCollectionSource object. This method sends a corresponding request to the data store, and upon receiving the results, passes them back to the control. If any summary is defined within a control, it’s also calculated by the data store.

When creating an XPServerCollectionSource object, you need to provide descriptive information on the target data table (view) in the target data store. First, you need to create a specific object that identifies the data table’s name and its structure (the names and types of data fields that need to be obtained). You can do this using one of the following methods:

1. In code, declare a persistent class (an XPBaseObject descendant) that will correspond to the data table. See the Basics of Creating Persistent Objects for Existing Data Tables topic for further details.
2. Create a typed DataTable object corresponding to the target data table. You can create this DataTable by creating a typed DataSet using the VS Designer (see the Data->Add New Data Source… menu command).

After the descriptive object (a persistent object or a typed DataTable) has been created, supply its type to the XPServerCollectionSource object. At design time, you can use the XPServerCollectionSource.ObjectClassInfo property to assign the descriptive object’s type. At runtime, specify the descriptive object’s type via the XPServerCollectionSource‘s constructor using an objectClassInfo or objectType parameter.

Important

In server mode, a target data table must contain a single key field, and the descriptive object must contain a public property/field corresponding to the table’s key. If the data table doesn’t contain a key field or the key is composed of several columns, it cannot be used as a data source in server mode.

For information on how to enable server mode for a GridControl and GridLookUpEdit controls see the Large Data Sources: Server and Instant Feedback Modes section.

Note

Non-persistent properties can be displayed in the grid, but sorting, grouping, filtering and summaries are not supported for them (also, corresponding grid features are disabled for these properties by default). If non-persistent properties are used for calculated values, it is better to implement them using the PersistentAliasAttribute.

Example 1

In the following code, an XPServerCollectionSource object is initialized with a persistent object describing a target “Person.Contact” data table (this table is included in the AdventureWorks database that ships with MS SQL Server).

In the code, the Person_Contact persistent object is declared, and mapped to the “Person.Contact” data table using the PersistentAttribute attribute. It exposes specific public properties that match the data table’s fields.

To provide data on the Person_Contact object for the XPServerCollectionSource, first a corresponding XPClassInfo object is obtained. Then it’s passed to the XPServerCollectionSource’s constructor via an objectClassInfo parameter. This initializes the XPServerCollectionSource.ObjectClassInfo property.

C#

using DevExpress.Xpo;
using DevExpress.Xpo.Metadata;
using DevExpress.Data.Filtering;

public Form1() {
    // ...
    // Create an XPClassInfo object corresponding to the Person_Contact class.
    XPClassInfo classInfo = XpoDefault.Session.GetClassInfo(typeof(Person_Contact));
    // Create a filter that selects records which contain names starting with 'A' 
    // in the LastName column
    CriteriaOperator criteria = CriteriaOperator.Parse("[LastName] LIKE ?", "A%");
    //Create a data source.
    XPServerCollectionSource serverModeDS = new XPServerCollectionSource(
      XpoDefault.Session, classInfo, criteria);
}

// ...

// The persistent object that describes the "Person.Contact" table 
// in the AdventureWorks SQL database.
[Persistent("Person.Contact")]
public class Person_Contact : XPLiteObject {        
    [Key]
    public System.Int32 ContactID {
        get { return fContactID; }
        set { SetPropertyValue(nameof(ContactID), ref fContactID, value); }
    }
    System.Int32 fContactID;

    public string FirstName {
        get { return fFirstName; }
        set { SetPropertyValue(nameof(FirstName), ref fFirstName, value); }
    }
    string fFirstName;

    public string LastName {
        get { return fLastName; }
        set { SetPropertyValue(nameof(LastName), ref fLastName, value); }
    }
    string fLastName;

    //...
}

VB.NET

Imports DevExpress.Xpo
Imports DevExpress.Xpo.Metadata
Imports DevExpress.Data.Filtering

Public Sub New()
    InitializeComponent()
    ' ...
    ' Create an XPClassInfo object corresponding to the Person_Contact class.
    Dim classInfo As XPClassInfo = XpoDefault.Session.GetClassInfo(GetType(Person_Contact));
    ' Create a filter that selects records which contain names starting with 'A' 
    ' in the LastName column
    Dim criteria As CriteriaOperator = CriteriaOperator.Parse("[LastName] LIKE ?", "A%")
    ' Create a data source.
    Dim serverModeDS As XPServerCollectionSource = New XPServerCollectionSource( _
      XpoDefault.Session, classInfo)
End Sub

' ...

' The persistent object that describes the "Person.Contact" table 
' in the AdventureWorks SQL database.
<Persistent("Person.Contact")> _
Public Class Person_Contact
    Inherits XPLiteObject
    <Key()> _
    Public Property ContactID() As System.Int32
        Get
            Return fContactID
        End Get
        Set(ByVal value as System.Int32)
            SetPropertyValue(NameOf(ContactID), fContactID, value)
        End Set
    End Property
    Private fContactID As System.Int32

    Public Property FirstName() As String
        Get
            Return fFirstName
        End Get
        Set(ByVal value as String)
            SetPropertyValue(NameOf(FirstName), fFirstName, value)
        End Set
    End Property
    Private fFirstName As String

    Public Property LastName() As String
        Get
            Return fLastName
        End Get
        Set(ByVal value as String)
            SetPropertyValue(NameOf(LastName), fLastName, value)
        End Set
    End Property
    Private fLastName As String

    '...
End Class

Example 2

The following code shows how to initialize an XPServerCollectionSource object with a typed DataTable object.

It’s assumed that a project contains a DataSet class (AdventureWorksDataSet) which owns the target DataTable (_Person_ContactDataTable). In the code, first a XPClassInfo object corresponding to the data table is created. Then it’s passed to the XPServerCollectionSource object’s constructor via the objectClassInfo parameter, initializing the XPServerCollectionSource.ObjectClassInfo property.

C#

using DevExpress.Xpo;
using DevExpress.Xpo.Metadata;

// Create an XPClassInfo object corresponding to the _Person_ContactDataTable data table.
XPClassInfo classInfo = XpoDefault.Session.GetClassInfo(
  typeof(AdventureWorksDataSet._Person_ContactDataTable));
// Create a data source.
XPServerCollectionSource serverModeDS = new XPServerCollectionSource(
  XpoDefault.Session, classInfo);

VB.NET

Imports DevExpress.Xpo
Imports DevExpress.Xpo.Metadata

' Create an XPClassInfo object corresponding to the _Person_ContactDataTable data table.
Dim classInfo As XPClassInfo = XpoDefault.Session.GetClassInfo( _
  GetType(AdventureWorksDataSet._Person_ContactDataTable))
' Create a data source.
Dim serverModeDS As XPServerCollectionSource = New XPServerCollectionSource( _
  XpoDefault.Session, classInfo)

Implements

ISessionProvider

Inheritance

Object

MarshalByRefObject

Component

XPServerCollectionSource