Export to PDF
- 12 minutes to read
Export From Preview (Visual Studio, WinForms, WPF)
You can export a report from Visual Studio Preview tab, WinForms Print Preview, and WPF Print Preview. Expand the drop-down list with export formats and select PDF File.
Specify export options in the invoked PDF Export Options dialog and click OK.
Export From Document Viewer (Web Platforms)
You can export a report from ASP.NET Web Forms Document Viewer, ASP.NET MVC Document Viewer, and ASP.NET Core Document Viewer. Specify export options in the Export Options dialog, expand the Export To drop-down list in the toolbar, and select PDF.
Export in Code
Use the XtraReport.ExportToPdf or XtraReport.ExportToPdfAsync methods to export a report to PDF format. Specify the path/stream to which the report should be exported as the first argument in these methods. If you specify only the path/stream, the report is exported to PDF format with the default options. To change the default options, do one of the following:
- Create a PdfExportOptions object, specify export options for this object, then pass the object to the XtraReport.ExportToPdf or XtraReport.ExportToPdfAsync methods as the second argument.
- Open a report in the Visual Studio Designer and change the export options in the Properties panel.
Export a Large Report
To export a large report in code, use the PdfStreamingExporter class instead of the XtraReport.ExportToPdf/XtraReport.ExportToPdfAsync method calls. You can use the PdfStreamingExporter class together with CachedReportSource (WinForms/WPF) or CachedReportSourceWeb (Web platforms).
Example
using DevExpress.XtraPrinting;
// ...
XtraReport1 report = new XtraReport1();
PdfExportOptions pdfOptions = report.ExportOptions.Pdf;
// Specify the pages to export.
pdfOptions.PageRange = "1, 3-5";
// Specify the quality of exported images.
pdfOptions.ConvertImagesToJpeg = false;
pdfOptions.ImageQuality = PdfJpegImageQuality.Medium;
// Specify the PDF/A-compatibility.
pdfOptions.PdfACompatibility = PdfACompatibility.PdfA3b;
// The following options are not compatible with PDF/A.
// The use of these options will result in PDF validation errors.
//pdfOptions.NeverEmbeddedFonts = "Tahoma;Courier New";
//pdfOptions.ShowPrintDialogOnOpen = true;
// (Optional) You can specify the security and signature options.
//pdfOptions.PasswordSecurityOptions
//pdfOptions.SignatureOptions
// (Optional) You can add metadata and attachments,
// to produce a ZUGFeRD-compatible PDF.
//pdfOptions.AdditionalMetadata
//pdfOptions.Attachments
// Specify the document options.
pdfOptions.DocumentOptions.Application = "Test Application";
pdfOptions.DocumentOptions.Author = "DX Documentation Team";
pdfOptions.DocumentOptions.Keywords = "DevExpress, Reporting, PDF";
pdfOptions.DocumentOptions.Producer = Environment.UserName.ToString();
pdfOptions.DocumentOptions.Subject = "Document Subject";
pdfOptions.DocumentOptions.Title = "Document Title";
// Check the validity of PDF export options
// and return a list of any detected inconsistencies.
IList<string> result = pdfOptions.Validate();
if (result.Count > 0)
Console.WriteLine(String.Join(Environment.NewLine, result));
else
{
report.CreateDocument();
if (ExportOptionsTool.EditExportOptions(pdfOptions, report.PrintingSystem)
== DialogResult.OK) {
report.ExportToPdf("result.pdf", pdfOptions);
// ...
}
}
PDF Document Versions
The PDF export engine produces the following PDF document versions:
- PDF 1.4 (default)
- Supported in Adobe Acrobat version 5.0 or later.
- PDF 1.6
- Adobe Acrobat 7.0 or later. Used if you enable Password Security and set Encryption Level to AES128 or ARC4.
- PDF 1.7
- Adobe Acrobat 9.0 or later. Used if you enable Password Security and set Encryption Level to AES256.
Export Options
The following options are available in the PDF Export Dialog invoked from Visual Studio Preview tab, WinForms Print Preview, and WPF Print Preview, and in the Export Options dialog of the Document Viewer (Web platforms):
- Page Range
- Export Editing Fields To AcroForms
- PDF/A Compatibility
- PDF/UA Compatibility
- File Size Optimization
- Password Security
- Digital Signature
- Document Options
The following option is available in the Export options dialog of the Document Viewer (Web platforms):
The following options are available in the Properties panel of the Report Designer (Visual Studio, WinForms, WPF, and Web):
- Page Range
- Export Editing Fields To AcroForms
- Export Bookmarks
- PDF/A Compatibility
- PDF/UA Compatibility
- File Size Optimization
- Password Security
- Document Options
- Show Print Dialog On Open
Page Range
The Page Range option specifies the range of pages that should be exported to a PDF file. For example, the “1,3,5-12” range exports the first, third, and all pages from the fifth to 12th.
Export Editing Fields to AcroForms
Enable the Export Editing Fields To AcroForms option to convert a report’s editing fields to interactive forms in the exported PDF file.
Export Bookmarks
Set the Export Bookmarks property to false to exclude bookmarks from the exported PDF file.
PDF/A Compatibility
Use the Pdf/A Compatibility option to make the exported PDF file compatible with the PDF/A specification. Set the option to one of the following values:
- PDF/A-1a (based on PDF/A-1b with conformance for accessibility based on the tagged document structure)
- PDF/A-1b (ISO 19005-1)
- PDF/A-2a (based on PDF/A-2b with conformance for accessibility based on the tagged document structure)
- PDF/A-2b (ISO 19005-2:2011)
- PDF/A-3a (based on PDF/A-3b with conformance for accessibility based on the tagged document structure)
- PDF/A-3b (ISO 19005-3:2012)
When the option is set to the default value (None), the exported PDF file conforms to ISO 32000-1:2005.
You can use the screen reader to vocalize the content of a PDF document’s elements. For tagged PDF documents (PDF/A-1a, PDF/A-2a, and PDF/A-3a), you can specify custom text that the screen reader can vocalize instead of an element’s default content. Refer to the following topic for more information: AccessibleDescription.
When you create a PDF/A compatible document, you can add additional metadata to the exported PDF file. Refer to the code example below that exports a simple report to a PDF/A-3b (ISO 19005-3) file. The exported file meets the ZUGFeRD specification used for electronic invoices in Germany.
Limitations
If a report contains the XRPdfContent control, you cannot export this report to PDF with the PDF/A option enabled. If you enable this option, the exception is raised when you export the report to PDF.
The following PDF export options are not supported for PDF/A compatible documents:
- Password Security
- Never Embedded Fonts
- Attachments (not supported only for PDF/A-1a, PDF/A-1b, PDF/A-2a, and PDF/A-2b)
- Show Print Dialog On Open
- Export Editing Fields to AcroForms (not supported only for PDF/A-1a and PDF/A-1b)
If you export a report to a PDF/A compatible document in code, use the Validate method to check whether the specified export options can be used for PDF/A compatible documents.
PDF/UA Compatibility
Use the Pdf/UA Compatibility option to make the exported PDF file compatible with the PDF/UA specification. If you set this option to PDF/UA1, the resulting file meets the ISO 14289 standard that defines the structure and tagged PDF features for use in assistive technologies.
You can specify the role of a UI element in the exported document for the screen reader. You can define the role of the following controls:
You can use the screen reader to vocalize the content of a PDF document’s elements. For a tagged PDF document, which conforms to the PDF/UA standard, you can specify custom text that the screen reader can vocalize instead of an element’s default content. Refer to the AccessibleDescription topic for more details.
A series of localization strings in the PreviewStringId enumeration with the Accessibility prefix allow you to localize the report control name for the screen reader.
Limitations
- The Never Embedded Fonts export option is not supported for PDF/UA compatible documents.
- If a report contains the XRPdfContent control, you cannot export this report to PDF with the PDF/UA option enabled. If you enable this option, the exception is raised when you export the report to PDF.
- If a report contains editing fields or the XRPdfSignature control, the PDF document generated from this report does not comply with the PDF/UA requirements.
File Size Optimization
Use the options below to decrease the size of the exported PDF file.
Image Quality
Enable the Convert Images To JPEG option to convert all images to JPEG. An image is converted to JPEG if the size of a JPEG image is smaller than the original image size. When the option is enabled, you can use the Image Quality option to change the image quality and the Rasterization Resolution option to specify the image resolution.
Never Embedded Fonts
Use the Do Not Embed These Fonts (Never Embedded Fonts in the Document Viewer) to specify fonts that should not be embedded to the exported PDF file.
Password Security
Use the Password Security options to specify an open password and permissions to copy, print, and use screen readers for the exported PDF file. To encrypt the content of the PDF file, set encryption level to one of the following algorithms:
- 128-bit AES (Advanced Encryption Standard) - the default algorithm;
- 256-bit AES (Advanced Encryption Standard);
- 128-bit ARC4 (Alleged Rivest Cipher 4).
Important
PDF passwords are stored in report definitions as plain text. Ensure that only trusted parties have access to report definition files.
Digital Signature
You can sign a report with an X.509 certificate when you export it to PDF. The specified signature information is saved to the document’s PDF Signature Options.
The XRPdfSignature control can visualize the document’s signature in the exported PDF file.
To sign the exported PDF document in the Web Document Viewer, use one of the following options:
- Sign the document in the Web Document Viewer’s UI
- Implement the IPdfSignatureOptionsProviderAsync interface to register available signature options. Select a signature from the Signature drop-down list in the Export to PDF section.
- Customize the exported document
- Override the CustomizeExportDocumentOnFinish method to retrieve and sign the exported document.
The following example shows how to sign a document exported to PDF:
Document Options
Use Document Options to specify information that should be embedded as Document Properties in the exported PDF file.
Show Print Dialog On Open
Enable the Show Print Dialog On Open option to invoke a print dialog when users open the exported PDF file. Do not use this option in web applications because most modern browsers disable scripts in PDF.
Tip
Review the following web application examples that export a report to PDF and print it in a browser without a preview:
- How to print/export XtraReport in an ASP.NET WebForms application without showing a report preview
- How to print/export XtraReport in an ASP.NET MVC application without showing a report preview
- How to Print and Export a Report in the ASP.NET Core Application without the Document Viewer
- How to print and export DevExpress reports without previewing them on a web page in an Angular application with an ASP.NET Core backend
- How to Print and Export a Report in a React Application without Displaying the Report
Limitations
- EMF and WMF images cannot be exported. Only EMF+ is available.
- The PDF/A-1b standard does not support transparent images. In PDF/A-1b compatible files, an alpha channel in images is ignored.
- The background of the exported PDF file is filled with the color assigned to the PageColor property. Set this property to Transparent if you add a background image to the exported PDF file.
In Adobe Reader, hyperlinks for the exported PDF file work only if the Create links from URLs option is enabled.
- OpenType Variable fonts (TrueType and CFF flavored), and OpenType SVG fonts are not supported.
- DevExpress’s wordwrap algorithm does not support additional characters such as soft and hard hyphens, zero-width spaces, and word joiners.
The Exported PDF File Differs From the Print Preview: Troubleshooting
A reporting application uses the Windows GDI+ API to draw the Print Preview. The PDF export engine utilizes another API to generate a PDF file from a report. Since the two APIs use different algorithms to process characters, the exported PDF file might differ from the report’s Print Preview.
Missed Characters in the Exported PDF File
If a font you use in a report does not contain a glyph for a character, this character may not be displayed in PDF file. Make sure that the system contains a font with missing glyphs to avoid this issue. Refer to the following article for information no how to install fonts to different systems: Use Custom Fonts in Reporting.
Inconsistent Line Breaks
The GDI+ API and the reporting PDF export engine use different algorithms to process line breaks. If you use Chinese, Japanese, or Korean characters in a report, line breaks might be displayed differently in the Print Preview and exported PDF file.
To resolve this issue, set the UseGdiPlusLineBreakAlgorithm property to true to use the GDI+ line break algorithm when a report is exported to PDF.
Post-Process PDF Files
You can post-process the resulting PDF files with the help of a dedicated DevExpress library: PDF Document API. This product helps you edit, merge, split, password-protect, and digitally sign PDF files.
You may also use PDF Document API to generate PDF documents from scratch. If that code-only approach suits your requirements, you don’t need to construct a report in the designer at all.
PDF Document API works in desktop and web applications that target a variety of platforms (Windows Forms, WPF, ASP.NET Web Forms, ASP.NET MVC, ASP.NET Core, Blazor, MAUI) and operating systems (Windows, Linux, macOS).
You need a license for the DevExpress Office File API Subscription or DevExpress Universal Subscription to use the library in production code.
If you haven’t yet done so, download our fully-functional 30-day trial version to try out DevExpress controls and libraries in your projects: