Bind a Report to an XPO Persistent Object
- 6 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
Create a new application or open an existing application. For more information, review the following help topic: Get Started with DevExpress Reporting.
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.
Add an XPO persistent object class. To do this, use the Data Model Wizard:
Generate a data model based on the existing Northwind SQL Server database:
The resulting data model appears as follows:
When the Data Model Wizard finishes, save the project to generate persistent object classes based on the generated model. Rebuild the solution.
Create a Report
Use the Report Wizard to create a report for an XPO persistent object. The wizard creates an XPObjectSource component. This component retrieves all the properties of the selected entity type. You can customize the property list and set up the component’s settings after you finish the wizard.
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 v24.2 Report item and click Add.
In the invoked Report Wizard, select Table Report and click Next to proceed.
On the next page, instead of selecting an existing connection, choose to specify the connection parameters:
Select the XPO data source and click Next.
The next wizard page lists your application project’s persistent object classes. Choose one entity type.
Specify whether the data connection should be available at runtime only:
Click Next. The following pages allow you to configure the report’s layout and appearance. These pages are optional. You can click Next on each page to omit specific steps or click Finish to generate the report.
Select data fields to display in the report.
Specify the report’s group fields.
Choose summary functions to calculate in reports.
Specify the report’s page settings.
Choose the report’s color scheme.
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.