XRSubreport Class

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

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v25.1.dll

NuGet Package: DevExpress.Reporting.Core

Declaration

C#

public class XRSubreport :
    SubreportBase

VB.NET

Public Class XRSubreport
    Inherits 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:

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

C#

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);

VB.NET

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)

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.

C#

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

VB.NET

Imports DevExpress.XtraReports.UI
' ...
' Reference an XtraReport instance named "detailReport" to include its content into the main report.
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:

MyReportProvider.cs

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();
        }
    }

VB.NET

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:

C#

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);
  }

VB.NET

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:

C#

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

VB.NET

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.

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.

C#

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)
    });
}

VB.NET

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

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.

Watch Video: SubReport Parameter Binding

The following code snippet binds a subreport parameter to the data field in the main report.

C#

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"));

VB.NET

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"))

XRSubreport Control Scenarios

• Create hierarchical master-detail reports where a separate report displays nested data.

  See the following help topic for more information: 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 to allow 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.

  See the following help topic for more information: 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, which 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 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:

  • Top Margin / Bottom Margin
  • Page Header / Page Footer
  • Group Header / Group Footer (if the band’s RepeatEveryPage option is enabled).
  • Vertical Header / Vertical Detail / Vertical Total

  If the XRSubreport.GenerateOwnPages option is enabled, you cannot move the XRSubreport control to these 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.

Implements

IScriptable

Inheritance

Object

MarshalByRefObject

Component

XRControl

SubreportBase

XRSubreport