XRSubreport Class
A control that is used to include a report’s content in another report.
Namespace: DevExpress.XtraReports.UI
Assembly: DevExpress.XtraReports.v20.2.dll
NuGet Packages: DevExpress.Reporting.Core, DevExpress.WindowsDesktop.Reporting.Core
Declaration
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 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.
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.
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 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.
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 following help topic shows how to use the XRSubreport control to create master-detail reports: Master-Detail Reports with Subreports.
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
- Referenced reports should not contain PageHeader or PageFooter bands.
- Do not place anything in margin bands in referenced reports.
The XRSubreport‘s GenerateOwnPages property is not in effect when you place the control in the following main report’s bands:
- Top Margin / Bottom Margin
- Page Header / Page Footer
- Group Header / Group Footer bands (if their RepeatEveryPage properties are enabled).
- Vertical Header / Vertical Detail / Vertical Total
If the XRSubreport‘s GenerateOwnPages property is enabled, you cannot move the control to these bands.
Tip
Online Example: Use Subreports to Add a Chart