XRPdfContent Class
A control that renders PDF file content in a report.
Namespace: DevExpress.XtraReports.UI
Assembly: DevExpress.XtraReports.v24.2.dll
NuGet Package: DevExpress.Reporting.Core
Declaration
[DefaultBindableProperty("Source")]
public class XRPdfContent :
XRControl,
IComplexControlRemarks
The XRPdfContent control allows you to render PDF file content in two ways:
Default. Render each PDF file page as a separate report page.
Embed PDF content into a report.
Refer to the following documentation section for more details:
Embed PDF File Content into a Report.
Warning
The XRPdfContent export is unavailable in applications that use the System.Drawing.Common package v7 and higher in non-Windows environments.
Add the XRPdfContent Control to a Report
Design Time
Drop the XRPdfContent item from the Toolbox onto a band on the design surface.
You can also copy a PDF document from an external application and paste it in your report, or drag a document and drop it onto the design surface.
The dragged file’s content is assigned to the control’s Source property as binary data.
Runtime
Create an XRPdfContent class instance and add this instance to a report band’s Controls collection. Refer to the following sections for code samples:
Specify PDF Content
Use one of the following methods:
-
This data is stored in the report definition file. The source of this data does not need to be available when the report is rendered.
Specify a reference to a PDF document
The reference to the document is stored in the report definition file. The referenced document should be available when the report is rendered.
Specify Binary PDF Data
Design Time
Expand the XRPdfContent control’s smart tag, click the Source property’s ellipsis button, and select a PDF file.
When users save a report, the Source property value persists in the report definition file.
You can also use report parameters to conditionally specify the Source property value or bind the property to a data source field. Refer to the following section for details: Use Expressions.
Runtime
Assign a path to a PDF file to the control’s Source property.
using System.IO;
using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.Expressions;
// ...
// Create a report that has a Detail band and uses Landscape page orientation.
XtraReport report = new XtraReport(){
Landscape = true,
Bands = {
new DetailBand() {
Name = "DetailBand",
HeightF = 25,
}
}
};
// Create an XRPdfContent class instance.
XRPdfContent pdfContent = new XRPdfContent();
// Assign binary PDF content to the XRPdfContent's Source property.
pdfContent.Source = System.IO.File.ReadAllBytes("MasterDetailReport.pdf");
// Add the XRPdfContent control to the Detail band.
report.Bands[BandKind.Detail].Controls.Add(pdfContent);
Specify a Reference to a PDF Document
Design Time
Expand the XRPdfContent control’s smart tag, click the Source URL property’s ellipsis button, and select a PDF file.
To specify a PDF document location on the Web, assign a document URL to the Source URL property.
You can also use report parameters to conditionally specify the SourceUrl property value or bind the property to a data source field. Refer to the following section for details: Use Expressions.
When users save a report, the URL or path assigned to the Source URL property is included in the report definition file. The PDF document should be available at the specified location when a report is printed or rendered.
The SourceUrl property value takes precedence over the Source property value. If you specify both properties, XRPdfContent includes the content specified by SourceUrl. If the file specified in the SourceUrl property cannot be loaded, the binary data from the Source property is used.
Runtime
Assign a PDF file path or URL to an XRPdfContent class instance’s SourceUrl property.
using System.IO;
using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.Expressions;
// ...
// Create a report that has a Detail band and uses Landscape page orientation.
XtraReport report = new XtraReport(){
Landscape = true,
Bands = {
new DetailBand() {
Name = "DetailBand",
HeightF = 25,
}
}
};
// Create an XRPdfContent class instance.
XRPdfContent pdfContent = new XRPdfContent();
// PDF content is loaded from the MasterDetail Report.pdf file.
pdfContent.SourceUrl = "MasterDetail Report.pdf";
// Add the XRPdfContent control to the Detail band.
report.Bands[BandKind.Detail].Controls.Add(pdfContent);
Use Expressions
Design Time
Expand the XRPdfContent‘s smart tag and click the Expression property’s ellipsis button below the Source or Source URL property.
Use the invoked Expression Editor to create an expression that identifies the source of a PDF file.
Runtime
Create an ExpressionBinding class instance. Pass the Source or SourceUrl property name as the first constructor parameter and an expression string as the second parameter. Then, add this instance to the ExpressionBindings collection.
The code below creates an XRPdfContent control and adds it to a report’s Detail band. The sample then creates an expression that binds the control’s SourceUrl property to the report’s PdfParameter parameter.
using System.IO;
using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.Expressions;
// ...
// Create a report that has a Detail band and uses Landscape page orientation.
// The "PdfParameter" report parameter specifies the PDF file location.
XtraReport report = new XtraReport(){
Landscape = true,
Parameters = {
new DevExpress.XtraReports.Parameters.Parameter() {
Name = "PdfParameter",
Type = typeof(string),
Value = "MasterDetailReport.pdf",
Visible = true
},
},
Bands = {
new DetailBand() {
Name = "DetailBand",
HeightF = 25,
}
}
};
// Create an XRPdfContent class instance.
XRPdfContent pdfContent = new XRPdfContent();
// Create an expression that binds the XRPdfContent's SourceUrl property to the report's "PdfParameter" parameter.
pdfContent.ExpressionBindings.Add(new ExpressionBinding("SourceUrl", "?PdfParameter"));
// Add the XRPdfContent control to the Detail band.
report.Bands[BandKind.Detail].Controls.Add(pdfContent);
The code below creates an XRPdfContent control and uses an expression to bind the control’s Source property to the PdfData field.
using System.IO;
using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.Expressions;
// ...
// Create a report that has a Detail band and uses Landscape page orientation.
XtraReport report = new XtraReport(){
Landscape = true,
Bands = {
new DetailBand() {
Name = "DetailBand",
HeightF = 25,
}
}
};
// Create an XRPdfContent class instance.
XRPdfContent pdfContent = new XRPdfContent();
// Create an expression that binds the XRPdfContent's Source property to the data source's "PdfData" field.
pdfContent.ExpressionBindings.Add(new ExpressionBinding("Source", "[PdfData]"));
// Add the XRPdfContent control to the Detail band.
report.Bands[BandKind.Detail].Controls.Add(pdfContent);
Embed PDF File Content into a Report
Add the XRPdfContent control to a report, specify a PDF file location, and disable the control’s Generate Own Pages property.
Use Cases
Create a report with PDF file content and headers/footers that are printed on PDF file pages.
Print pictures, bar codes, page numbers, a report watermark, and other elements over the content of a PDF file.
Create a report document with paper kind that differs from the paper kind of the PDF pages. Refer to the following section for instructions: Fit PDF File’s Page Size to Report’s Page Size.
Append PDF file content to report content and add sequential numbering to all report pages. For this, add PDF file content as a subreport to your report as described in the following section: Fit PDF File’s Page Size to Report’s Page Size. Then, add page numbers to both the subreport and main report.
Design a pre-printed form and use the PDF file as a watermark.
If your PDF file contains one page, follow the steps below:
- Embed this page into a report’s Detail band.
- Remove the report’s margins to prevent duplication with PDF page margins.
- Adjust the page size to make it fit the entire Detail band.
If your PDF file contains multiple pages, do the following:
- Create a subreport for each of the pages. Follow the instructions in this section: Fit PDF File’s Page Size to Report’s Page Size. Use the XRPdfContent control’s PageRange property to specify the PDF file page that should be included into a subreport.
- Include each of these subreports in one report.
Fit PDF File’s Page Size to Report’s Page Size
A PDF file and a report to which you embed PDF file content might have different paper kind. PDF file pages can also be generated with double margins: page margins and report margins.
This section explains how to set the same paper kind for a report and its embedded PDF file and how to include only the PDF file’s page margins in the report. The main idea is to create a subreport that includes PDF pages in embedded mode, and then, add this subreport to the main report that contains initial content.
Create a blank report. Set the report’s Paper Kind property to the paper kind of the main report to which you want to embed PDF content.
Drop the XRPdfContent control from the Toolbox onto the created report’s Detail band, specify a PDF file source, and disable the control’s Generate Own Pages property.
Remove the report’s margins and adjust the XRPdfContent control size to make PDF content fit the entire Detail band.
Add the report as a subreport to your main report. Use the XRSubreport control with the Generate Own Pages property enabled.
The following image demonstrates the main report’s Preview:
Limitations
Report Layout
- PDF content is displayed as an image in Preview. Users cannot select text in PDF content. To allow users to select text, export the report to PDF.
- Search in PDF content and interactivity features, such as annotations and form fields, are not supported.
- Continuous page numbering is not supported. The XRPdfContent control inserts the PDF document as a separate page(s) of the report document. These pages are part of the entire document, but they cannot display other report controls such as XRPageInfo.
- You cannot add the XRPdfContent control to 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
- Form Fields in a PDF file are lost if the
XRPdfContentcontrol embeds the PDF file content into the report. As a solution to this problem, you can export the report to a PDF file and later merge the PDF file pages.
Linux and Azure
The XRPdfContent control uses the CreateBitmap method. This method does not work in Linux-based environments or certain Azure hosting plans. Add the DevExpress.Pdf.SkiaRenderer NuGet package to your solution and use the Skia rendering engine on these platforms:
- On Linux, add the SkiaSharp.NativeAssets.Linux NuGet package to the solution in addition to DevExpress.Pdf.SkiaRenderer.
- On Windows Azure, set the PrintingOptions.Pdf.RenderingEngine property to Skia.
Blazor WebAssembly
To use the XRPdfContent control in a WebAssembly application, do the following:
- Set the PdfPrintingOptions.RenderingEngine property to Skia.
- Add the SkiaSharp.NativeAssets.WebAssembly NuGet package to the project.
- Add the NuGet package DevExpress.Pdf.SkiaRenderer to the project.