Skip to main content

XRSubreport Class

A control that is used to include a report’s content in another report.

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v22.1.dll


public class XRSubreport :


XRSubreport is a control that references another report - an XtraReport class instance or a report stored in a REPX or XML file. The referenced report content is included instead of the XRSubreport control.


XRSubreport does not embed the referenced report into the main report - the referenced report’s file or instance should be available to render the combined report.

See the Scenarios to Use the XRSubreport Control section for XRSubreport usage scenarios.

Add the XRSubreport Control to a Report

At design time, drop the XRSubreport item from the Toolbox onto the design surface.

Use the code sample below to add an XRSubreport control instance to a report at runtime.

using System.IO;
using System.Drawing;
using DevExpress.XtraReports.UI;
// ...
XRSubreport subreport = new XRSubreport() {
    BoundsF = new RectangleF(0, 100, 550, 25),
// "mainReport" is an XtraReport instance.
// Add subreport to the main report's DetailBand.

Reference a Report

Reference an XtraReport Class Instance

Assign the XtraReport class instance to the XRSubreport‘s ReportSource property.


The ReportSource property is not available in the Web Report Designer.

At design time, click the XRSubreport‘s smart tag and select the report from the ReportSource property’s drop-down list. The list contains reports from the project.


Rebuild the solution if the report is not listed in the ReportSource drop-down list or the ReportSource property does not retain its value.

The code sample below references an XtraReport instance.

using DevExpress.XtraReports.UI;
// ...
// Reference an XtraReport instance named "detailReport" to include its content into the main report.
subreport.ReportSource = detailReport;

Reference a Report from a File or Storage

Specify a URL or path in the XRSubreport‘s ReportSourceUrl property to reference a report that is stored as a REPX or XML file.


The ReportSourceUrl property is not available in Visual Studio Report Designer.
In the Web Report Designer, implement a report storage to allow users to specify the Report Source Url property.
In ASP.NET Core web applications, use the Bind() method to specify the main report.

In an End-User Report Designer, expand the Subreport control’s smart tag and click the Report Source Url property’s ellipsis button to invoke the Open File dialog. Specify the report file name and click Open.

The code sample below adds a reference to a report from a REPX file.

using DevExpress.XtraReports.UI;
// ...
// Reference a report from the report definition (REPX) file. The file is stored in the application's folder.
subreport.ReportSourceUrl = Path.Combine(Path.GetDirectoryName(typeof(ReportCreator).Assembly.Location), "DetailReport.repx");

The ReportSourceUrl property value takes precedence over the ReportSource value. If you specify both properties, the XRSubreport includes the report specified by ReportSourceUrl.

Access the Referenced Report

Double-click the XRSubreport control instance within a Report Designer to open the referenced report in a new Design Panel. This action is unavailable if you implement the Report Designer as a single-document user interface.

At runtime, handle the XRSubreport‘s BeforePrint event and use the ReportSource property to access the referenced report’s instance. This solution applies to reports that are referenced in the ReportSource and ReportSourceUrl properties.

using DevExpress.XtraReports.UI;
// ...
private void Subreport_BeforePrint(object sender, System.Drawing.Printing.PrintEventArgs e) {
    XRSubreport subreport = (XRSubreport)sender;
    XtraReport report = subreport.ReportSource;
    report.Bands["DetailBand"].Controls.Add(new XRLabel() {
        Text = " - ",
        BoundsF = new RectangleF(450, 0, 100, 25),
        Font = new Font(new FontFamily("Arial"), 9)

Use the Referenced Report’s Parameters

You can bind the parameters that are used as filter criteria in the referenced report to the main report’s data fields, calculated fields, or parameters. To do this, add items to the XRSubreport‘s ParameterBindings collection.

At design time, expand the XRSubreport‘s smart tag and click Edit Parameter Bindings. Click Add in the invoked Parameter Binding Collection Editor. Specify the referenced report’s parameter in the ParameterName property and the main report’s field or parameter in the Binding property.

Watch Video: SubReport Parameter Binding

The code sample below illustrates how to bind a parameter from the referenced report to a data field from the main report.

using System.IO;
using System.Drawing;
using DevExpress.XtraReports.Parameters;
// ...
// Bind the detail report's "prmCategory" parameter to the main report's "Categories.CategoryID" data field.
subreport.ParameterBindings.Add(new ParameterBinding("prmCategory", null, "Categories.CategoryID"));

Scenarios to Use the XRSubreport Control

  • Create hierarchical master-detail reports where a separate report displays nested data.

    The following help topic shows how to use the XRSubreport control to create master-detail reports: Create a Master-Detail Report with a Subreport.

  • Print the referenced report on separate pages.

    Enable the XRSubreport‘s GenerateOwnPages property. This allows the referenced report to generate its own pages and specify its own page size, margins, and orientation.

    The following help topic adds a report that uses the Landscape page orientation to a report that uses the Portrait page orientation: Merge Reports: Use Data-Driven Page Sequence.

  • Re-use report parts.

    Use XRSubreport to include reusable headers, footers, cover pages, or report sections.

    The following help topic demonstrates how to add a report to another report: Add a Report to the End/Beginning.

  • Generate a combined Table of Contents for the main report and referenced report.

    Use the XRSubreport‘s BookmarkParent property to specify the main report control whose bookmark is the parent of the referenced report’s bookmarks. Ensure that the XRTableOfContents.MaxNestingLevel property allows for the main report and referenced report’s cumulative nesting levels.

  • Create Side-by-Side Reports.

    Place XRSubreport instances side by side and reference reports that you want to compare against each other. The following tutorial describes how to create a report that shows two subreports side-by-side: Side-by-Side Reports. The following demo illustrates how to use XRSubreport in side-by-side reports: Employee Comparison Online Demo.



Online Example: Use Subreports to Add a Chart


See Also