XtraReportBase.DataSource Property

Gets or sets an object that supplies data to the report.

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v21.2.dll

NuGet Package: DevExpress.Reporting.Core

Declaration

C#

[SRCategory(ReportStringId.CatData)]
public object DataSource { get; set; }

VB.NET

<SRCategory(ReportStringId.CatData)>
Public Property DataSource As Object

Property Value

Type	Description
Object	An object that stores or fetches data.

Remarks

At runtime, you can assign any object to the DataSource property. When the report attempts to retrieve data from the associated data source, the report expects the data source object to support one of the following interfaces:

• IList
• ITypedList
• IBindingList

If this requirement is not met, an exception is thrown that informs the user that an object assigned to the DataSource property cannot be used as a report’s datasource, because it does not implement any of the supported interfaces.

The DevExpress Data Library ships with proprietary data access components that work as a proxy between your data and the report layout. These components are serializable, so they are automatically saved in the REPX report layout definition, making them part of your report layout.

Data Source Types

You can assign the following objects to the DataSource property.

DevExpress Data Library Classes

• SqlDataSource
• JsonDataSource
• ObjectDataSource
• ExcelDataSource
• MongoDBDataSource
• EFDataSource
• FederationDataSource

Standard .NET Objects

Objects that implement the following interfaces:

• IList
• ITypedList
• IBindingList

Other .NET data providers:

• DataSet^[1]

How to Bind a Report to a Data Source

1. Assign the data object (an object of a supported type) to the report’s DataSource property.

   The following image illustrates how to assign the data source to a report when you edit a report in the Visual Studio Report Designer:

   

   To configure a new data source, click Add Report Data Source… This command launches the Data Source Wizard that guides you through the data source configuration.

2. Call the data object’s Fill or FillAsync method to retrieve data^[2].

   The FillAsync methods allow you to run other code (handle user interface events) while the data source is being populated. The Fill methods do not return control over your code execution until the data source is populated with data.

3. Specify the report’s DataMember property. You should do this each time you assign a new object to the report’s DataSource property.

   The following image illustrates how to select a data member when you edit a report in the Visual Studio Report Designer:

   

Parent Data Source

The report’s DataSource property specifies the parent data source. When you assign a data source to the report’s DataSource property, it may affect all report elements. Report elements to which a data source can be assigned (controls, bands, parameters, calculated fields) use the data source of the report that contains them (the parent report) if their DataSource property is not specified.

You can assign a different data source to the DetailReportBand to create a master-detail report, as described in the following help topic: Create a Master-Detail Report with a Detail Report Band.

Typically, you should explicitly specify the data source and data member for the following report controls:

• XRChart
• XRCrossTab
• XRSparkline

You can use the DataSourceManager.GetDataSourceAssignables method to obtain a collection of all report elements that can be bound to a data source.

Schema-Only Mode

You can use the DataSourceSchema property to specify a data source schema and bind report controls to data fields, even if the data is not available at the time you edit the report.

Manage Report Data Sources

You can add multiple data sources to a report:

A report stores the data sources in the ComponentStorage collection. The Field List window and the Data Source combobox in the Report Designer’s Properties panel display data sources contained in the ComponentStorage.

To display data in the report, you should assign a data source to the DataSource property of the report, DetailReportBand band, or a data-bound report component, and specify the DataMember property when applicable.

C#

var report = new MyReportClassName();
  var detailBand = report.Bands["DetailReport"] as DetailReportBand;
  detailBand.DataSource = DataSourceManager.GetDataSources<SqlDataSource>(report)
      .FirstOrDefault(ds=>ds.Name == "sqlDataSource1");
  detailBand.DataMember = "Employees";

VB.NET

Dim report = New MyReportClassName()
Dim detailBand = TryCast(report.Bands("DetailReport"), DetailReportBand)
detailBand.DataSource = DataSourceManager.GetDataSources(Of SqlDataSource)(report).
  FirstOrDefault(Function(ds) ds.Name = "sqlDataSource1")
detailBand.DataMember = "Employees"

The user can select a data source in the Data Source editor in the Report Designer’s Properties Window.

The DataSourceManager class contains static methods that allow you to retrieve data sources from a report, nested subreports, report controls that use their own data sources, and report parameters.

Expressions use dots to separate the names of different data items (data source, table, relation, field). Avoid using dots in data source names.

Example

The following code example illustrates how to bind a report to the Northwind database’s Products table and display product names:

Form1.cs

using System.Windows.Forms;
using System;
using DevExpress.DataAccess.Sql;
using DevExpress.DataAccess.ConnectionParameters;
using DevExpress.XtraReports.UI;

// ...
private SqlDataSource BindToData() {
    // Create a data source that retrieves data from an XML file.  
    XmlFileConnectionParameters connectionParameters =
        new XmlFileConnectionParameters(@"C:\Users\Public\Documents\DevExpress Demos 21.2\Components\Data\nwind.xml");
    SqlDataSource dataSource = new SqlDataSource(connectionParameters);

    // Build a query that retrieves product names.
    SelectQuery query = SelectQueryFluentBuilder
        .AddTable("Products")
        .SelectColumn("ProductName")
        .Build("Products");

    // Add this query to the data source.
    dataSource.Queries.Add(query);

    // Populate the data source with data.
    dataSource.Fill();

    return dataSource;
}

private XtraReport CreateReport() {
    // Create a new report instance.
    XtraReport report = new XtraReport();

    // Assign a data source to the created report.
    report.DataSource = BindToData();
    report.DataMember = "Products";

    // Add a detail band to the report.
    DetailBand detailBand = new DetailBand();
    detailBand.Height = 50;
    report.Bands.Add(detailBand);

    // Create a new label.
    XRLabel label = new XRLabel { WidthF = 300 };
    // Bind the created label to the ProductName data field.
    label.ExpressionBindings.Add(new ExpressionBinding("Text", "[ProductName]"));
    // Add the label to the detail band.
    detailBand.Controls.Add(label);

            return report;
}

private void exportButton_Click(object sender, EventArgs e) {
    // Export the report to DOCX and save the exported file to the application folder.
    XtraReport report = CreateReport();
    report.ExportToDocx(report.Name + ".docx");
}

private void printButton_Click(object sender, EventArgs e) {
    // Send the report to the default printer.
    XtraReport report = CreateReport();
    report.Print();
}

Form1.vb

Imports System.Windows.Forms
Imports System
Imports DevExpress.DataAccess.Sql
Imports DevExpress.DataAccess.ConnectionParameters
Imports DevExpress.XtraReports.UI

' ...
Private Function BindToData() As SqlDataSource
    ' Create a data source that retrieves data from an XML file.  
    Dim connectionParameters As New XmlFileConnectionParameters("C:\Users\Public\Documents\DevExpress Demos 21.2\Components\Data\nwind.xml")
    Dim dataSource As New SqlDataSource(connectionParameters)

    ' Build a query that retrieves product names.
    Dim query As SelectQuery = SelectQueryFluentBuilder.AddTable("Products").SelectColumn("ProductName").Build("Products")

    ' Add this query to the data source.
    dataSource.Queries.Add(query)

    ' Populate the data source with data.
    dataSource.Fill()

    Return dataSource
End Function

Private Function CreateReport() As XtraReport
    ' Create a new report instance.
    Dim report As New XtraReport()

    ' Assign a data source to the created report.
    report.DataSource = BindToData()
    report.DataMember = "Products"

    ' Add a detail band to the report.
    Dim detailBand As New DetailBand()
    detailBand.Height = 50
    report.Bands.Add(detailBand)

    ' Create a new label.
    Dim label As XRLabel = New XRLabel With {.WidthF = 300}
    ' Bind the created label to the ProductName data field.
    label.ExpressionBindings.Add(New ExpressionBinding("Text", "[ProductName]"))
    ' Add the label to the detail band.
    detailBand.Controls.Add(label)

            Return report
End Function

Private Sub exportButton_Click(ByVal sender As Object, ByVal e As EventArgs)
    ' Export the report to DOCX and save the exported file to the application folder.
    Dim report As XtraReport = CreateReport()
    report.ExportToDocx(report.Name & ".docx")
End Sub

Private Sub printButton_Click(ByVal sender As Object, ByVal e As EventArgs)
    ' Send the report to the default printer.
    Dim report As XtraReport = CreateReport()
    report.Print()
End Sub

Related GitHub Examples

The following code snippets (auto-collected from DevExpress Examples) contain references to the DataSource property.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

Reporting_how-to-create-a-hierarchical-report-t456484/CS/TreeViewReport/ChildReport.cs#L18

childReport.Parameters["Level"].Value = this.Parameters["Level"].Value;
childReport.DataSource = parentNode.Children;
subReport.ReportSource = childReport;

reporting-wpf-create-report-in-code/CS/RuntimeReportsApplication/MainWindow.xaml.cs#L35

// Create a detail report.
SqlDataSource ds = report.DataSource as SqlDataSource;
CreateDetailReport(report, ds.Queries[0].Name + "." + ds.Relations[0].Name);

Reporting_documentpreviewcontrol-how-to-create-a-drill-down-report-runtime-sample-t337482/CS/dxWPFApp/MainWindow.xaml.cs#L83

masterReport.Tag = "Master";
masterReport.DataSource = ds;
masterReport.DataMember = "Categories";

Create-a-Report-Bound-To-XPObjectSource/CS/Create a Report Bound to XPObjectSource/Form1.cs#L45

report.Bands.Add(DetailBand);
report.DataSource = CreateDataSource();
return report;

winforms-reporting-create-grid-based-report/CS/ConvertGridToReportExample/XtraReport1.cs#L20

ArrayList columnArrayList = new ArrayList();
this.DataSource = dSource;
this.DataMember = dMember;

VB.NET

snap-convert-snx-to-repx/VB/SnxToRepx/Converter/ReportGenerator.vb#L50

'Specify data settings
report.DataSource = options.DataSource
report.DataMember = options.DataMember

Reporting_how-to-create-a-hierarchical-report-t456484/VB/TreeViewReport/ChildReport.vb#L20

childReport.Parameters("Level").Value = Me.Parameters("Level").Value
childReport.DataSource = parentNode.Children
subReport.ReportSource = childReport

reporting-wpf-create-report-in-code/VB/RuntimeReportsApplication/MainWindow.xaml.vb#L35

' Create a detail report.
Dim ds As SqlDataSource = TryCast(report.DataSource, SqlDataSource)
CreateDetailReport(report, ds.Queries(0).Name & "." & ds.Relations(0).Name)

Reporting_documentpreviewcontrol-how-to-create-a-drill-down-report-runtime-sample-t337482/VB/dxWPFApp/MainWindow.xaml.vb#L78

masterReport.Tag = "Master"
masterReport.DataSource = ds
masterReport.DataMember = "Categories"

Create-a-Report-Bound-To-XPObjectSource/VB/Create a Report Bound to XPObjectSource/Form1.vb#L44

report.Bands.Add(DetailBand)
report.DataSource = CreateDataSource()
Return report

Implements

DataSource

Footnotes

1. DataSets are not serializable, and you should not use them in a report edited with the Web Report Designer.

2. If you use a DataSet, call the corresponding DataAdapter.Fill method or assign the DataAdapter to the report’s DataAdapter property.