XRPdfContent Class

A control that renders PDF file content in a report.

Namespace : DevExpress.XtraReports.UI

Assembly : DevExpress.XtraReports.v25.2.dll

NuGet Package : DevExpress.Reporting.Core

Declaration

C#
VB.NET

csharp

[DefaultBindableProperty("Source")]
public class XRPdfContent :
    XRControl,
    IComplexControl

<DefaultBindableProperty("Source")>
Public Class XRPdfContent
    Inherits XRControl
    Implements IComplexControl

Remarks

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.

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 Binary PDF Data
Specify a Reference to a PDF Document

Specify PDF Content

Use one of the following methods:

Specify binary PDF data
Specify a reference to a PDF document

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.

C#
VB.NET

csharp

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

Imports System.IO
Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.Expressions
' ...
' Create a report that has a Detail band and uses Landscape page orientation.
Dim report = New XtraReport()
report.Landscape = True
Dim band = New DetailBand() With {.Name = "DetailBand", .HeightF = 25}
report.Bands.Add(band)
' Create an XRPdfContent class instance.
Dim pdfContent As 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.

C#
VB.NET

csharp

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

Imports System.IO
Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.Expressions
' ...
' Create a report that has a Detail band and uses Landscape page orientation.
Dim report = New XtraReport()
report.Landscape = True
Dim band = New DetailBand() With {.Name = "DetailBand", .HeightF = 25}
report.Bands.Add(band)
' Create an XRPdfContent class instance.
Dim pdfContent As New XRPdfContent()
' The 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.

C#
VB.NET

csharp

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

Imports System.IO
Imports DevExpress.XtraReports.UI
Imports 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.
Dim report = New XtraReport()
report.Landscape = True
Dim band = New DetailBand() With {.Name = "DetailBand", .HeightF = 25}
report.Bands.Add(band)
Dim reportParameter = New DevExpress.XtraReports.Parameters.Parameter() With {
    .Name = "PdfParameter",
    .Type = GetType(String),
    .Value = "MasterDetailReport.pdf",
    .Visible = True}
report.Parameters.Add(reportParameter)
' Create an XRPdfContent class instance.
Dim pdfContent As 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.

C#
VB.NET

csharp

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

Imports System.IO
Imports DevExpress.XtraReports.UI
Imports DevExpress.XtraReports.Expressions
' ...
' Create a report that has a Detail band and uses Landscape page orientation.
Dim report = New XtraReport()
report.Landscape = True
Dim band = New DetailBand() With {.Name = "DetailBand", .HeightF = 25}
report.Bands.Add(band)
' Create an XRPdfContent class instance.
Dim pdfContent As 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.

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.

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 XRPdfContent control 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 CreateDXBitmap 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.

Export

The RTF export method does not support multiple page settings within a single report. As a result, the XRPdfContent control with multiple page settings is cropped during export. To avoid this issue, use the Export to Docx - Single Page export mode.

Implements

IScriptable

Inheritance

Object MarshalByRefObject Component XRControl XRPdfContent