XRSubreport Class
A control used to include the contents of one report in another report.
Namespace: DevExpress.XtraReports.UI
Assembly: DevExpress.XtraReports.v24.2.dll
NuGet Package: DevExpress.Reporting.Core
Declaration
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.
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:
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.
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:
The following code snippet specifies a REPX file as a subreport:
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.
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.
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
- Subreports should not contain PageHeader or PageFooter bands.
- Do not place anything in margin bands in subreports.
The XRSubreport.GenerateOwnPages property is not in effect when you place the XRSubreport control in the following 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.GenerateOwnPages setting is enabled, you cannot move the XRSubreport control to these bands.