Bind a Report to an XPO Persistent Object

• Jul 20, 2021
• 7 minutes to read

This topic describes how to bind a report to XPO data at design time.

Create a Project and Prepare a Data Source

1. Create a new application or open an existing application.

2. Ensure your application project references the following assemblies:

   • DevExpress.Xpo

   • DevExpress.Data

   To add references to these assemblies, right-click the References item in the Solution Explorer and select Add Reference. In the invoked Reference Manager, switch to the Extensions tab, check the assemblies listed above, and click OK.

   

3. Add an XPO persistent object class. To do this, use the Data Model Wizard or the DevExpress ORM Persistent Object project item template.

   In this example, a data model is generated based on the Northwind database.

   

   Tip

   Save the project after you finish the Data Model Wizard to generate persistent object classes based on the generated model.

C#

using DevExpress.Xpo;

    public partial class Categories : XPLiteObject {
        int fCategoryID;
        [Key(true)]
        public int CategoryID {
            get { return fCategoryID; }
            set { SetPropertyValue<int>(nameof(CategoryID), ref fCategoryID, value); }
        }
        string fCategoryName;
        [Indexed(Name = @"CategoryName", Unique = true)]
        [Size(15)]
        public string CategoryName {
            get { return fCategoryName; }
            set { SetPropertyValue<string>(nameof(CategoryName), ref fCategoryName, value); }
        }
        string fDescription;
        [Size(SizeAttribute.Unlimited)]
        public string Description {
            get { return fDescription; }
            set { SetPropertyValue<string>(nameof(Description), ref fDescription, value); }
        }
        //...
        [Association(@"ProductsReferencesCategories")]
        public XPCollection<Products> ProductsCollection { get { return GetCollection<Products>(nameof(ProductsCollection)); } }
    }  

VB.NET

Imports DevExpress.Xpo

    Partial Public Class Categories
        Inherits XPLiteObject

        Private fCategoryID As Integer
        <Key(True)>
        Public Property CategoryID() As Integer
            Get
                Return fCategoryID
            End Get
            Set(ByVal value As Integer)
                SetPropertyValue(Of Integer)(NameOf(CategoryID), fCategoryID, value)
            End Set
        End Property
        Private fCategoryName As String
        <Indexed(Name := "CategoryName", Unique := True), Size(15)>
        Public Property CategoryName() As String
            Get
                Return fCategoryName
            End Get
            Set(ByVal value As String)
                SetPropertyValue(Of String)(NameOf(CategoryName), fCategoryName, value)
            End Set
        End Property
        Private fDescription As String
        <Size(SizeAttribute.Unlimited)>
        Public Property Description() As String
            Get
                Return fDescription
            End Get
            Set(ByVal value As String)
                SetPropertyValue(Of String)(NameOf(Description), fDescription, value)
            End Set
        End Property
        '...
        <Association("ProductsReferencesCategories")>
        Public ReadOnly Property ProductsCollection() As XPCollection(Of Products)
            Get
                Return GetCollection(Of Products)(NameOf(ProductsCollection))
            End Get
        End Property
    End Class

4. Rebuild the solution.

Create a Report

Use the Report Wizard to create a report for an XPO persistent object.

1. Select Add New Item in the PROJECT menu or press CTRL+SHIFT+A to invoke the Add New Item dialog. In this dialog, choose the DevExpress v21.1 Report item and click Add.

   

2. In the invoked Report Wizard, select a report type and click Next to proceed.

   

3. On the next wizard page, choose the XPO option and click Next.

   

4. The following wizard page lists your application project’s persistent object classes. Choose one entity type.

   

5. On the next page, specify whether to use an existing data connection from the Visual Studio Server Explorer or create a new data connection.

   

   5.1. To create a new data connection, select a supported data providers or define a custom connection string.

   Specify provider-specific connection options (for example, the authentication type and database name).

   

   5.2. Click Next on the following page to save the created connection string to the configuration file.

   

At this step, the wizard creates an XPObjectSource component. This component retrieves all the properties the chosen entity type includes. You can customize the property list and set up the component’s settings after you finish the wizard. Now, follow the steps in the next section to configure the report’s layout and appearance.

Design the Report

The following pages allow you to design the report. These pages are optional. You can click Next on each page to omit specific steps or click Finish to generate the report.

1. Select data fields to display in the report.

   

2. Specify the report’s group fields.

   

3. Choose summary functions to calculate in reports.

4. Specify the report’s page settings.

5. Choose the report’s color scheme.

6. Specify the report title and click Finish.

   

View the Result

After you finish the wizard, the Report Designer is invoked. It displays the generated report according to the settings you specified in the wizard.

The Field List reflects the data source structure.

Switch to the Preview tab to see the report’s document.

Customize Data Source Settings

You can customize the created XPObjectSource component’s settings. To do this, select this component in the Report Explorer and switch to the Properties window.

These settings allow you to specify which data to retrieve from the data source.

Note

Group/filter combinations and complex expressions support depends on the data source.

Change the Connection Parameters

Use the ConnectionStringName property to change the connection string name only or the ConnectionString property to reconfigure a connection string. These properties are available in the Properties window.

You can also right-click the XPObjectSource component in the Report Explorer and choose Configure Connection… to invoke the wizard and reconfigure the connection string.

Change the Entity Type

Use the EntityType property to specify another persistent object class.

This reloads the Field List. It displays the fields that correspond to the the newly specified type. You can bind report elements to these fields.

Change the Property Set

XPO loads all the persistent properties that the specified entity type exposes. You can use the XPObjectSource component’s Properties property to customize the properties set.

Click the Properties property’s ellipsis button. This invokes the Properties Collection Editor.

You can specify the following options for the newly added properties:

• Name
  The name that you use to access the property in the report.

• PropertyExpression
  The entity’s persistent property or an expression that you can construct using several properties. The expression is calculated on the server.

• Group
  Indicates whether to use this property to group data that XPO retrieves from the server.

• Fetch
  Indicates whether to retrieve data for this property from the server.

Note

At least one property in the Properties collection must have the Fetch property set to true.

Use the Clear Properties command to clear the Properties collection and the Populate Properties command to add all the properties the entity type exposes.

The Field List contains the fields that correspond to the Properties collection’s properties. If this collection is empty, the Field List reflects the data source structure.

Retrieve Filtered Data

Use the XPObjectSource‘s Filter property to specify a filter expression for the data XPO retrieves from the data source.

Retrieve Sorted Data

Use the XPObjectSource‘s Sorting property to specify sort settings for the retrieved data.

The XPObjectSource supports multiple column sorting. You can also specify a sorting expression for the data XPO retrieves from the data source.

Retrieve Filtered Groups

Use the XPObjectSource‘s GroupFilter property to filter data on the server against values of the grouped properties.

Note

The GroupFilter property is available when the Properties collection in not empty and has at least one property with the Group flag set to true.

Limit the Retrieved Records’ Number

Use the following properties to limit the number of records XPO retrieves from the server:

• TopReturnedRecords
  Specifies the number of the top records in the data source XPO retrieves for the report.

• SkipReturnedRecords
  Specifies the number of top records in the data source XPO skips when it retrieves data for the report.

Note

The XPObjectSource does not process the zero value.

Specify Query Parameters

You can define parameters and use them in Properties, Filter, Sorting and GroupFilter expressions.

The following properties are available for each query parameter:

• Name
  Specifies the parameter’s name.
• Type
  Specifies the parameter value’s data type.
• Expression
  Determines whether the actual parameter value is static or generated dynamically.
• Value
  Specifies the query parameter’s actual value (a static or dynamically calculated). If the Expression option is enabled, you can assign a report parameter or an expression that can also include a report parameter.

You can set a parameter to a static value or generate it dynamically based on an associated expression.

• Specify a static value

  Choose a query parameter’s value type and set a static value to the Value property according to the selected type.

  

• Provide a dynamic value

  Activate the Expression checkbox for a parameter.

  

  The following three options are available to dynamically calculate the parameter’s actual value:

  • Select Expression Editor to construct an expression in the invoked Expression Editor.

  • Selecting New Report Parameter to create a new report parameter and map it to the query parameter. Ensure the report parameter’s type corresponds to the query parameter’s type.

  • Select an existing report parameter and map it to the query parameter.