Skip to main content

XRSubreport Class

A control used to include the contents of one report in another report.

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v24.1.dll

NuGet Package: DevExpress.Reporting.Core

Declaration

public class XRSubreport :
    SubreportBase

Remarks

The XRSubreport is a control that references another report. When the document is created from the main report, the XRSubreport control is replaced with the contents of the report that the XRSubreport references.

View Example: Use Subreports to Add a Chart

View Example: Reporting for WinForms - Master-Detail Report with a Subreport

Note

The XRSubreport control does not embed the referenced report into the main report. The referenced report should be available when the main report is rendered.

Add the XRSubreport Control to a Report

In the Report Designer, drop the XRSubreport item from the Toolbox onto the design surface:

XRSubreport Control Add From Toolbox

The following code snippet adds the XRSubreport control instance to a report.

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 DetailBand.
mainReport.Bands["DetailBand"].Controls.Add(subreport);

Reference a Report

Reference an XtraReport Class Instance

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

Note

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

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

XRSubeport Set Report Source

Tip

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 following code snippet specifies an XtraReport instance.

using DevExpress.XtraReports.UI;
// ...
XRSubreport detailReport = new DevExpress.XtraReports.UI.XRSubreport();
subreport.ReportSource = detailReport;

Reference a Report by Name or Path

Use the ReportSourceUrl property to specify the name of a report to later resolve to a report instance, or the path to a .repx file from which a report can be instantiated.

To resolve report names, implement a service with the IReportProvider interface. Designed as a cross-platform replacement for a report storage, this interface has a GetReport method to return a report instance by a unique name.

The following code snippet implements the MyReportProvider service:

using DevExpress.XtraReports.Services;
using DevExpress.XtraReports.UI;
// ...
    public class MyReportProvider : IReportProvider {
        XtraReport IReportProvider.GetReport(string id, ReportProviderContext context) {
            if (id == "MyDetailReport")
                return new DetailReport();
            else return new XtraReport();
        }
    }

The following code snippet registers the MyReportProvider service to resolve the XRSubreport report reference in the main report during PDF export:

using DevExpress.XtraReports.Services;
using DevExpress.XtraReports.UI;
using System.ComponentModel.Design;
using System.IO;
// ...
  XtraReport xtraReport = XtraReport.FromFile("main.repx");
  IReportProvider myReportProvider = new MyReportProvider();
  ((IServiceContainer)xtraReport).RemoveService(typeof(IReportProvider));
  ((IServiceContainer)xtraReport).AddService(typeof(MyReportProvider), myReportProvider);
  using (MemoryStream memoryStream = new MemoryStream()) {
      xtraReport.ExportToPdf(memoryStream);
  }

Note

The ReportSourceUrl property is not available in Visual Studio Report Designer. In ASP.NET Core web applications, use the Bind() method to specify the main report.

In the End-User Report Designer for WinForms, expand the XRSubreport smart tag and click the Report Source Url property’s ellipsis button to invoke the Open File dialog. Select a report file and click Open:

Open Report File

The following code snippet specifies a REPX file as a subreport:

xrSubreport1.ReportSourceUrl = @"C:\Reports\DetailReport.repx";

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

Access the Referenced Report

Double-click the XRSubreport control on the Report Designer design surface to open the referenced report in a new Design Panel.

Double-Click XRSubreport

This action is unavailable if you invoke the Report Designer using the ReportDesignTool in a single-document user interface. Review the following help topic for more information: Invoke a Default End-User Report Designer Form.

At runtime, you can handle the XRSubreport.BeforePrint event and use the ReportSource property to access the subreport instance. This method applies to reports referenced by both the ReportSource and ReportSourceUrl properties.

using DevExpress.XtraReports.UI;
// ...
private void Subreport_BeforePrint(object sender, System.ComponentModel.CancelEventArgs 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)
    });
}

Access Subreport Parameters

Subreport parameters can be bound to data fields, calculated fields, or parameters used in the main report. To specify bindings, populate the XRSubreport.ParameterBindings collection.

At design time, click Edit Parameter Bindings in the XRSubreport smart tag. In the invoked Parameter Binding Collection Editor select a subreport parameter in the ParameterName list. Select the main report’s field or parameter in the Binding list.

XRSubreport Edit Parameter Bindings

Watch Video: SubReport Parameter Binding

The following code snippet binds a subreport parameter to the data field in 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"));

XRSubreport Control Scenarios

  • 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 in the VS Report Designer.

  • 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.

Limitations

Implements

See Also