XPCollection Class
The collection of persistent objects that implements delayed loading and can serve as a data source for a data-aware control.
Namespace: DevExpress.Xpo
Assembly: DevExpress.Xpo.v19.2.dll
Declaration
Remarks
The XPCollection class represents a collection of persistent objects. When creating a collection, you need to specify the type of objects that will be stored in the collection (at runtime - by specifying the object’s type in the class’s constructor and at design time - via the XPCollection.ObjectClassInfo property).
The XPCollection component implements the IBindingList and ITypedList interfaces, so it can serve as a data source for a visual data-aware control. For instance, when a collection is bound to a grid control (for instance, the XtraGrid), its objects will be represented as records in the grid that can be edited. In this instance, the XPBaseCollection.BindingBehavior property allows you to specify whether adding new items to and/or removing existing items from the collection is allowed by the grid.
In most cases, a collection needs to be created to access objects of a specific type from a data store. The XPCollection class implements delayed loading, i.e., it’s populated with persistent objects from the data store on demand. For instance, you can create an XPCollection instance, that is marked to contain custom Person objects. The collection, however, will be populated with Person objects from a data store only when the collection’s contents is accessed. Consider the following example:
using DevExpress.Xpo;
using DevExpress.Data.Filtering;
public class Person : XPObject {
public Person() {
Name = "";
}
public string Name {
get { return fName; }
set { SetPropertyValue(nameof(Name), ref fName, value); }
}
string fName;
public bool IsMale {
get { return fIsMale; }
set { SetPropertyValue(nameof(IsMale), ref fIsMale, value); }
}
bool fIsMale;
}
// Create a collection that will retrieve Person objects whose IsMale field is set to false.
XPCollection xpCollectionPerson = new XPCollection(typeof(Person),
CriteriaOperator.Parse("IsMale==false"));
// The collection is not yet populated with objects from a data store.
// ...
// Read the number of objects in the collection.
// At this point, the collection will be populated with data.
int ctr = xpCollectionPerson.Count;
// ...
The XPBaseCollection.Criteria and XPBaseCollection.Filter properties specify filters that are applied when retrieving objects from a data store. Note that when an XPCollection is created using a constructor with the criteriaEvaluationBehavior parameter, it is loaded immediately.
For more information, see XPCollection.
Note
When designing ASP.NET applications, use the XpoDataSource component, rather than the XPCollection.
Example
The following example demonstrates how to implement a one-to-many relationship between persistent objects, so that child objects are considered a part of their owner (when an owner is deleted, its aggregated objects will be automatically deleted; similarly, when an object is saved its aggregated objects will also be saved).
A one-to-many relationship is set up using the AssociationAttribute attribute. The AggregatedAttribute attribute is used to implement aggregation.
In this example, a Person object can have multiple addresses that are stored in the Person.Addresses collection. Each address in this collection is represented by an Address persistent class. The Person.Addresses property is marked with the AssociationAttribute and AggregatedAttribute attributes.
If you run the code below as is, the console output will be:
7654 Amsterdam Ave, New York, NY 555 Harbor Way, Santa Barbara, CA
If you remove the Aggregated attribute, the output will change to:
7654 Amsterdam Ave, New York, NY 7654 Amsterdam Ave, New York, NY
using System;
using System.Collections.Generic;
using System.Linq;
using DevExpress.Xpo;
namespace ConsoleApplication1 {
public class Person : XPObject {
public string Name {
get { return fName; }
set { SetPropertyValue(nameof(Name), ref fName, value); }
}
string fName;
[Association("PersonAddresses"), Aggregated]
public XPCollection<Address> Addresses {
get { return GetCollection<Address>(nameof(Addresses)); }
}
}
public class Address : XPObject {
[Association("PersonAddresses")]
public Person Owner {
get { return fOwner; }
set { SetPropertyValue(nameof(Owner), ref fOwner, value); }
}
Person fOwner;
public string AddressInfo {
get { return fAddressInfo; }
set { SetPropertyValue(nameof(AddressInfo), ref fAddressInfo, value); }
}
string fAddressInfo;
}
class Program {
static void Main(string[] args) {
// Create a new instance of the Person class
Person person = new Person() { Name = "Andrew Smith" };
// Add an address for the person.
Address address = new Address() { AddressInfo = "7654 Amsterdam Ave, New York, NY" };
person.Addresses.Add(address);
// Save the created Person object. The contents of the Addresses collection will be saved as well.
person.Save();
// Reload the object to verify if changes were saved.
address.Reload();
Console.WriteLine(address.AddressInfo);
address.AddressInfo = "555 Harbor Way, Santa Barbara, CA";
person.Save();
// Reload the object to verify if changes were saved.
address.Reload();
Console.WriteLine(address.AddressInfo);
Console.ReadKey();
}
}
}