XRSubreport Class

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

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v19.2.dll

Declaration

public class XRSubreport :
    SubreportBase
Public Class XRSubreport
    Inherits SubreportBase

Remarks

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's content is included instead of the XRSubreport control.

NOTE

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. You can add the XRSubreport control to bands or XRPanel or XRTableCell controls.

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 a subreport to the main report's DetailBand.
mainReport.Bands["DetailBand"].Controls.Add(subreport);

Reference a Report

Reference an XtraReport Class Instance

Assign the XtraReport class instance to the XRSubreport's 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 the report from the ReportSource property's drop-down list. The list contains reports from the project.

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 code sample below references an XtraReport instance.

using DevExpress.XtraReports.UI;
// ...
// Reference an XtraReport instance named "detailReport" to include its content in 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.

NOTE

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.

TIP

The DevExpress Channel provides the SubReport Parameter Binding video lesson.

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 Create a Master-Detail Report with Subreports topic shows how to use the XRSubreport control to create master-detail reports.

  • 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 Merge Reports: Use Data-Driven Page Sequence topic describes how to include a report that uses the Landscape page orientation in a report that uses the Portrait page orientation.

  • Re-use report parts.

    Use XRSubreport to include re-usable headers, footers, cover pages, or report sections.

    The Add a Report to the End/Beginning topic demonstrates how to append a report to another report.

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

    Use the XRSubreport's BookmarkParent property to specify the main report's control whose bookmark is parent to 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 Employee Comparison Online Demo illustrates how to use XRSubreport in side-by-side reports.

Limitations

TIP

Online Example: Use Subreports to Add a Chart

Implements

DevExpress.XtraPrinting.IBrickOwner
DevExpress.Utils.Serializing.Helpers.IXtraSupportDeserializeCollectionItem
DevExpress.Utils.Serializing.IXtraSerializable
DevExpress.Utils.Serializing.Helpers.IXtraSupportCreateContentPropertyValue
See Also