Export to PDF

• Aug 03, 2020
• 5 minutes to read

This topic details the specifics of exporting a document to PDF (Portable Document Format).

Tip

See the following code examples illustrating how to export a report to PDF in code:

• How to export a report to PDF format
• How to use the digital signature options when exporting a report to PDF

PDF Document Versions

The PDF export engine produces PDF documents of the following versions depending on specified export options:

• A PDF 1.4 document is generated by default and is supported by the Adobe Acrobat version 5.0 or later.
• A PDF 1.6 document is generated if you enable encryption in PDF options and set the PdfPasswordSecurityOptions.EncryptionLevel property to PdfEncryptionAlgorithm.AES128 or PdfEncryptionAlgorithm.ARC4. This document version is supported by Adobe Acrobat 7.0 or later.
• A PDF 1.7 document is generated if you enable encryption in PDF options and set the PdfPasswordSecurityOptions.EncryptionLevel property to PdfEncryptionAlgorithm.AES256. This document version is supported by Adobe Acrobat 9.0 or later.

PDF Cross-Compatibility

PDF generation does not require installing third-party components on an end-user’s machine.

• When including Far-Eastern and Arabic fonts into PDF, make sure that the included fonts contain all necessary characters.

• Document hyperlinks will be active in PDF only if the Create links from URLs setting is enabled in Adobe® Reader installed on the target machine.

  To access this option in the program’s Edit menu, click Preferences and in the invoked dialog, switch to General.

  

The document pages’ background is filled with the color specified by the XtraReport.PageColor property. If you want to add a background image to the PDF file, set this property to Transparent.

The PDF options are provided by the PdfExportOptions class. These options can be accessed via a report’s ExportOptions.Pdf property and are detailed in the following sections.

PDF/A Options

The following PDF/A specifications are supported.

• PDF/A-1b (ISO 19005-1)
• PDF/A-2b (ISO 19005-2:2011)
• PDF/A-3b (ISO 19005-3:2012)

To make a document compatible with the PDF/A specification, use the following options.

• PdfExportOptions.PdfACompatibility
• PdfExportOptions.AdditionalMetadata

If the PdfExportOptions.PdfACompatibility property is set to PdfACompatibility.None (the default value), the resulting document will conform to the ISO 32000-1:2005 standard without any restrictions.

For a code sample, refer to the following example online: How to export a report to ZUGFeRD.

For the current versions of the library, consider the following restrictions associated with PDF/A compatibility.

• All PDF/A versions implicitly prohibit encryption.
• All fonts that are used in PDF/A documents should be embedded.
• The PDF/A-1b and PDF/A-2b standards do not support attachments.
• The PDF/A-1b standard does not support transparency, and the alpha channel in images will be ignored.

To check the validity of PDF export options, use the PdfExportOptions.Validate method that returns a list of any detected inconsistencies.

Document Options

• PdfExportOptions.DocumentOptions
• PageByPageExportOptionsBase.PageRange
• PdfExportOptions.ShowPrintDialogOnOpen

Security Options

• Use the PdfExportOptions.PasswordSecurityOptions property to protect the resulting PDF file from being read, copied, printed and/or edited by specifying passwords for these actions.

  Important

  PDF passwords are saved with report definitions in clear text. Make sure that only trusted parties have access to report definition files.

  It is also possible to enable text access to a document for screen reader devices.

• After specifying PdfExportOptions.PasswordSecurityOptions, use the PdfPasswordSecurityOptions.EncryptionLevel property to select the algorithm for encrypting content of a PDF file.

  This property returns a PdfEncryptionLevel enumeration value enabling you to select any of the following encryption algorithms:

  • 128-bit AES (Advanced Encryption Standard) - the default value;
  • 256-bit AES (Advanced Encryption Standard);
  • 128-bit ARC4 (Alleged Rivest Cipher 4).

• Use the PdfExportOptions.SignatureOptions to apply an X.509 certificate to the resulting PDF file and digitally sign the document.

  For a code sample, see How to use the digital signature options when exporting a report to PDF.

File Size Optimization

Use the following options to vary the quality of PDF-embedded images and in this way, control the resultant file size.

• PdfExportOptions.ImageQuality

• PdfExportOptions.ConvertImagesToJpeg

  When this option is enabled, you can use the PageByPageExportOptionsBase.RasterizationResolution property to define the image resolution.

To reduce the size of large documents (e.g., before sending them via e-mail), you can use the following option.

• PdfExportOptions.NeverEmbeddedFonts

As for the embedded fonts and PDF page content, they are always compressed in the resulting PDF file.

Current Limitations

At present, the following limitations apply to PDF export:

• Glyph Shaping does not work for non-embedded fonts.
• Support for right-to-left languages with non-embedded fonts requires that your application runs under full trust.
• Export of vector EMF and WMF images is not supported. The current export mechanism supports EMF+ only.

Export Editing Fields

Use the PdfExportOptions.ExportEditingFieldsToAcroForms option to specify whether to convert a report’s editing fields to AcroForms on PDF export.

PDF Export API

You can export a report to PDF using one of the following methods with or without the options listed above passed as parameters:

• XtraReport.ExportToPdf
• PrintingSystemBase.ExportToPdf
• LinkBase.ExportToPdf

If your report contains many thousands of pages, you can export it to the PDF format in streaming or multi-threaded streaming modes using the PdfStreamingExporter class.

Validating PDF Export Options

The following code illustrates how to use the PdfExportOptions.Validate method to check the validity of PDF export options.

Use this method to make sure that none of the specified options are mutually exclusive, e.g., when applying PDF/A options to a document (PdfExportOptions.PdfACompatibility).

In this example, the following inconsistencies will be detected.

• “PDF/A standard implicitly forbids showing the print dialog on opening a document.”
• “Encryption is not supported in a PDF/A document.”

C#

using DevExpress.XtraPrinting;
using DevExpress.XtraReports.UI;
using System;
using System.Collections.Generic;
// ...

using (XtraReport report = new XtraReport()) {
    PdfExportOptions options = new PdfExportOptions();
    options.PdfACompatibility = PdfACompatibility.PdfA1b;
    options.PasswordSecurityOptions.PermissionsPassword = "pwd";
    options.ShowPrintDialogOnOpen = true;
    IList<string> result = options.Validate();
    if (result.Count > 0)
        Console.WriteLine(String.Join(Environment.NewLine, result));
    else
        report.ExportToPdf("Result.pdf", options);
}

VB.NET

Imports DevExpress.XtraPrinting
Imports DevExpress.XtraReports.UI
Imports System
Imports System.Collections.Generic
' ...

Using report As New XtraReport()
    Dim options As New PdfExportOptions()
    options.PdfACompatibility = PdfACompatibility.PdfA1b
    options.PasswordSecurityOptions.PermissionsPassword = "pwd"
    options.ShowPrintDialogOnOpen = True
    Dim result As IList(Of String) = options.Validate()
    If result.Count > 0 Then
        Console.WriteLine([String].Join(Environment.NewLine, result))
    Else
        report.ExportToPdf("Result.pdf", options)
    End If
End Using