xtrareports-devexpress-dot-xtrareports-dot-ui-2eb0704b.md
A control used to include the contents of one report in another report.
Namespace : DevExpress.XtraReports.UI
Assembly : DevExpress.XtraReports.v25.2.dll
NuGet Package : DevExpress.Reporting.Core
public class XRSubreport :
SubreportBase
Public Class XRSubreport
Inherits SubreportBase
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.
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);
Imports System.IO
Imports System.Drawing
Imports DevExpress.XtraReports.UI
' ...
Dim subreport As New XRSubreport() With {.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)
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;
Imports DevExpress.XtraReports.UI
' ...
' Reference an XtraReport instance named "detailReport" to include its content into the main report.
subreport.ReportSource = detailReport
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();
}
}
Imports DevExpress.XtraReports.Services
Imports DevExpress.XtraReports.UI
' ...
Public Class MyReportProvider
Implements IReportProvider
Private Function IReportProvider_GetReport(ByVal id As String, ByVal context As ReportProviderContext) As XtraReport Implements IReportProvider.GetReport
If id = "MyDetailReport" Then
Return New DetailReport()
Else
Return New XtraReport()
End If
End Function
End Class
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);
}
Imports DevExpress.XtraReports.Services
Imports DevExpress.XtraReports.UI
Imports System.ComponentModel.Design
Imports System.IO
' ...
Private xtraReport As XtraReport = XtraReport.FromFile("main.repx")
Private myReportProvider As IReportProvider = New MyReportProvider()
DirectCast(xtraReport, IServiceContainer).RemoveService(GetType(IReportProvider))
DirectCast(xtraReport, IServiceContainer).AddService(GetType(MyReportProvider), myReportProvider)
Using memoryStream As New MemoryStream()
xtraReport.ExportToPdf(memoryStream)
End Using
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:
xrSubreport1.ReportSourceUrl = @"C:\Reports\DetailReport.repx";
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.
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)
});
}
Imports DevExpress.XtraReports.UI
' ...
Private Sub Subreport_BeforePrint(ByVal sender As Object, ByVal e As System.ComponentModel.CancelEventArgs)
Dim subreport As XRSubreport = DirectCast(sender, XRSubreport)
Dim report As XtraReport = subreport.ReportSource
report.Bands("DetailBand").Controls.Add(New XRLabel() With {.Text = " - ", .BoundsF = New RectangleF(450, 0, 100, 25), .Font = New Font(New FontFamily("Arial"), 9)})
End Sub
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.
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"));
Imports System.IO
Imports System.Drawing
Imports 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", Nothing, "Categories.CategoryID"))
Create hierarchical master-detail reports where a separate report displays nested data.
Print the referenced report on separate pages.
Re-use report parts.
Generate a combined Table of Contents for the main report and referenced report.
Create Side-by-Side Reports.
Subreports cannot contain PageHeader or PageFooter bands.
Do not place content in margin bands within subreports.
The XRSubreport.GenerateOwnPages property is ignored when the XRSubreport control is placed in the following bands:
The RTF export method does not support multiple page settings in a single report. As a result, the XRSubreport control with multiple page settings is cropped during export. To avoid this behavior, use Export to Docx - Single Page mode.
A subreport does not apply its own report-level properties when embedded in another report. Instead, it inherits the corresponding properties of the main report. For example, a subreport with RightToLeft and RightToLeftLayout enabled ignores those settings and follows the main report configuration.
Object MarshalByRefObject Component XRControl SubreportBase XRSubreport
See Also