Creating an XPCollection

• Oct 29, 2020
• 5 minutes to read

In terms of XPO, the XPCollection represents a collection object which can be used to retrieve collections of persistent objects from a data store and bind them to UI controls with ease.

Your options for creating a collection object are:

• Create an XPCollection programmatically.
• Create a collection at design time. This option creates an XPCollection object on your form or component whose properties you configure manually. This strategy is useful if you intend to set XPCollection properties at runtime or if you simply prefer setting the properties in the Properties window. The procedure is described below.

To create an empty XPCollection, set the XPBaseCollection.LoadingEnabled property to false.

The sections below provide additional information on both these options.

Creating an XPCollection at Runtime

To retrieve all the objects of a particular type, all that you need to do is to pass the required object type and the Session object (if you don’t use the default session) as the constructor’s parameters as shown in the following code example.

C#

// Retrieves all the Person objects (including descendants) using the default session.
XPCollection collection = new XPCollection(typeof(Person));

VB.NET

' Retrieves all the Person objects (including descendants) using the default session.
Dim collection As XPCollection = New XPCollection(GetType(Person))

Note

To retrieve persistent objects using a custom Session, you also need to pass the session object to the collection’s constructor.

To customize the order of the contents and reduce the set of objects in the resulting collection object, you need to specify additional search, filter and sorting criteria. See Querying a Data Store and Creating Criteria for more information about creating and handling collections in code.

Creating an XPCollection at Design Time

To create the XPCollection object at design time, follow the steps below.

1. In the Solution Explorer window, click View Designer.
2. Click View on the toolbar, and then click Toolbox.
3. From the Data tab of the Toolbox, drag an XPCollection object onto your form or component.
4. Select XPCollection in the designer and then use the Properties window to set the session used to retrieve a collection in the corresponding property. You can select the session object from the list of sessions defined in your form or component. When the XPCollection is initialized, the Session property is pre-initialized with the default session (see Session.DefaultSession for details).

5. To define the type of persistent object to be retrieved by the collection, set the ObjectClassInfo property. You can select the object from a list of the persistent objects defined in your form or component. Session property modification resets the ObjectClassInfo property.

   Note

   By default, assemblies from project references are not loaded into the current application domain by Visual Studio. As a result, types declared in external assemblies are not added to the ObjectClassInfo combo box in the designer. To trigger loading types from a specific assembly, access any of these types in the form/component initialization code. An example is provided in the XPCollection.ObjectClassInfo topic.

6. If you want to specify the list of properties to be displayed in a bound control, set the DisplayableProperties property. By default, all object properties are included in the list.
7. You can set the DisplayableProperties property as a single unit. The list is comprised of property names separated by semicolons. The list of properties is recreated every time the ObjectClassInfo property is changed.
8. To set collection binding behavior in the bound UI control, set the corresponding property by selecting the options from the check list. The options selected are displayed in the BindingBehavior property as a string with option values separated by commas. The default property value is AllowNew, AllowRemove. See the definition of the XPBaseCollection.BindingBehavior for a list of available option values.
9. By default, the XPCollection does not include deleted objects. To override this behavior, you can set the SelectDeleted property to true.

10. You can specify the sort order of collection contents via the SortProperty collection which is accessible via the Sorting property. In the SortProperty Collection Editor you can specify the properties which control the sort order and sort order direction for each property.

    Note

    If collection options need to be set at runtime, you can configure collection object properties as dynamic properties. For more information, see Configuring Applications Using Dynamic Properties in the MSDN library.

11. By default, the XPCollection retrieves all the objects which match the search criteria. To override this behavior, you can set the value of the TopReturnedObjects property to specify the maximum number of objects retrieved.
12. If you want to rename the collection object, set its Name property.
13. If you want to change the visibility level of the collection object, set its Modifiers property.
14. You may also designate methods to handle collection-specific events on the Events tab in a way you typically do for the other objects.

You can now select the collection as a DataSource in a bound UI control, for example the standard DataGrid (see How to Bind an XPCollection and How to Bind an XPCollection to the LookUp for details).