PdfDocument Class

Namespace:
GemBox.Pdf
Assembly:
GemBox.Pdf.dll

Represents a root class in the GemBox.Pdf implementation of the PDF Document Structure as specified in the PDF Specification ISO 32000-1:2008, section '7.7 Document Structure'.

public sealed class PdfDocument : PdfObject, IDisposable
Public NotInheritable Class PdfDocument
    Inherits PdfObject
    Implements IDisposable
Inheritance:
System.Object
PdfDocument
Implements
System.IDisposable

Constructors

PdfDocument()

Initializes a new instance of the PDF document.

public PdfDocument()
Public Sub New

Properties

AssociatedFiles

(Optional; PDF 2.0) An array of one or more PdfFileSpecifications which denote the associated files for this PdfDocument.

For unencrypted wrapper documents for an encrypted payload document the AssociatedFiles property is required and shall include a reference to the PdfFileSpecification for the encrypted payload document.

public PdfAssociatedFileCollection AssociatedFiles { get; }
Public ReadOnly Property AssociatedFiles As PdfAssociatedFileCollection
Property Value
PdfAssociatedFileCollection

An array of one or more PdfFileSpecifications which denote the associated files for this PdfDocument.

AuthorSignature

Gets or sets the certifying signature (also known as an author signature) (PDF 1.5) whose AuthorPermission in any of the Locks shall indicate the author's specification of which changes to the document shall be prevented by the consumer applications.

public PdfSignature AuthorSignature { get; set; }
Public Property AuthorSignature As PdfSignature
Property Value
PdfSignature

The certifying signature (also known as an author signature) (PDF 1.5) whose AuthorPermission in any of the Locks shall indicate the author's specification of which changes to the document shall be prevented by the consumer applications.

Exceptions
System.InvalidOperationException

The document's author signature can be set to null only (so consumer applications won't prevent the author's disallowed changes but will instead mark the author's signature as invalid if any of the disallowed changes were done after the author signed the document). To set a non-null value, use the Sign(PdfSigner) method with a PdfSigner whose AuthorPermission is not null.

See Also

CloseStream

Gets or sets a value indicating whether to close the stream of the PDF file currently associated with the PdfDocument when closing or disposing the PdfDocument.

This option is ignored if Close() or Dispose() is not called.

Setting this option to false has the same effect as not calling Close() nor Dispose().

Default value: true.

public bool CloseStream { get; set; }
Public Property CloseStream As Boolean
Property Value
System.Boolean

true if the stream of the PDF file currently associated with the PdfDocument should be closed when closing or disposing the PdfDocument; otherwise, false.

EmbeddedFiles

(Optional; PDF 1.4) A name tree mapping name PdfStrings to PdfFileSpecifications for PdfEmbeddedFiles (see 7.11.4, "Embedded File Streams").

public PdfEmbeddedFileSpecificationTree EmbeddedFiles { get; }
Public ReadOnly Property EmbeddedFiles As PdfEmbeddedFileSpecificationTree
Property Value
PdfEmbeddedFileSpecificationTree
Remarks

This property is a shortcut to the property Names.EmbeddedFiles.

See Also

Form

(Optional; PDF 1.2) The document’s interactive form (AcroForm) dictionary (see 12.7.2, "Interactive Form Dictionary").

public PdfInteractiveForm Form { get; }
Public ReadOnly Property Form As PdfInteractiveForm
Property Value
PdfInteractiveForm

The document’s interactive form (AcroForm) dictionary.

See Also

Id

(Required if an Encrypt entry is present in the file trailer; optional otherwise; PDF 1.1) An array of two byte-strings constituting a file identifier (see 14.4, "File Identifiers") for the file.

Because the Id entries are not encrypted it is possible to check the Id key to assure that the correct file is being accessed without decrypting the file.

Although this entry is optional, its absence might prevent the file from functioning in some workflows that depend on files being uniquely identified.

public PdfDocumentIdentifier Id { get; }
Public ReadOnly Property Id As PdfDocumentIdentifier
Property Value
PdfDocumentIdentifier

The array of two byte-strings constituting a file identifier for the file.

See Also

Info

(Optional; shall be an indirect reference) The document’s information dictionary (see 14.3.3, "Document Information Dictionary").

public PdfDocumentInformation Info { get; }
Public ReadOnly Property Info As PdfDocumentInformation
Property Value
PdfDocumentInformation

The document’s information dictionary.

Exceptions
InvalidPdfDictionaryEntryException

Value is not according to PDF Specification ISO 32000-1:2008.

See Also

Metadata

(Optional; PDF 1.4; shall be an indirect reference) A metadata stream that shall contain metadata for the document (see 14.3.2, "Metadata Streams").

public override PdfXmlMetadataStream Metadata { get; }
Public Overrides ReadOnly Property Metadata As PdfXmlMetadataStream
Property Value
PdfXmlMetadataStream

A metadata stream that shall contain metadata for the document.

Overrides
See Also

Names

(Optional; PDF 1.2) The document's name dictionary (see 7.7.4, "Name Dictionary").

public PdfDocumentNames Names { get; }
Public ReadOnly Property Names As PdfDocumentNames
Property Value
PdfDocumentNames

The document's name dictionary.

See Also

Outlines

(Optional; shall be an indirect reference) The outline dictionary that shall be the root of the document’s outline hierarchy (see 12.3.3, "Document Outline").

public PdfOutlineCollection Outlines { get; }
Public ReadOnly Property Outlines As PdfOutlineCollection
Property Value
PdfOutlineCollection

The outline dictionary that shall be the root of the document’s outline hierarchy.

See Also

PageLayout

(Optional) Gets or sets the value specifying the page layout to be used when the document is opened.

Default value: SinglePage.

public PdfPageLayout PageLayout { get; set; }
Public Property PageLayout As PdfPageLayout
Property Value
PdfPageLayout

The value specifying the page layout to be used when the document is opened.

See Also

PageMode

(Optional) Gets or sets the value specifying how the document shall be displayed when opened.

Default value: UseNone.

public PdfPageMode PageMode { get; set; }
Public Property PageMode As PdfPageMode
Property Value
PdfPageMode

The value specifying how the document shall be displayed when opened.

See Also

Pages

(Required; shall be an indirect reference) The page tree node that shall be the root of the document’s page tree (see 7.7.3, "Page Tree").

public PdfPages Pages { get; }
Public ReadOnly Property Pages As PdfPages
Property Value
PdfPages

The page tree node that shall be the root of the document’s page tree.

See Also

Portfolio

(Optional; PDF 1.7) A PdfPortfolio that a conforming reader shall use to enhance the presentation of EmbeddedFiles stored in the PDF document. (see 12.3.5, "Collections").

public PdfPortfolio Portfolio { get; }
Public ReadOnly Property Portfolio As PdfPortfolio
Property Value
PdfPortfolio

A PdfPortfolio that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.

See Also

SaveOptions

Gets or sets the options used when saving the PdfDocument to a PDF file.

Default value: Default.

public PdfSaveOptions SaveOptions { get; set; }
Public Property SaveOptions As PdfSaveOptions
Property Value
PdfSaveOptions

The options used when saving the PdfDocument to a PDF file.

Exceptions
System.ArgumentNullException

Value is null.

SecurityStore

(Optional; PDF 2.0) Document-wide security-related information.

public PdfDocumentSecurityStore SecurityStore { get; }
Public ReadOnly Property SecurityStore As PdfDocumentSecurityStore
Property Value
PdfDocumentSecurityStore

Document-wide security-related information.

See Also

Version

(Optional; PDF 1.4) The version of the PDF specification to which the document conforms (for example, 1.4) if later than the version specified in the file’s header (see 7.5.2, "File Header"). If the header specifies a later version, or if this entry is absent, the document shall conform to the version specified in the header. This entry enables a conforming writer to update the version using an incremental update; see 7.5.6, "Incremental Updates".

public PdfVersion? Version { get; set; }
Public Property Version As PdfVersion?
Property Value
System.Nullable<PdfVersion>

The version of the PDF specification to which the document conforms (for example, 1.4) if later than the version specified in the file’s header (see 7.5.2, "File Header").

ViewerPreferences

(Optional; PDF 1.2) A viewer preferences dictionary (see 12.2, "Viewer Preferences") specifying the way the document shall be displayed on the screen. If this entry is absent, conforming readers shall use their own current user preference settings.

public PdfViewerPreferences ViewerPreferences { get; }
Public ReadOnly Property ViewerPreferences As PdfViewerPreferences
Property Value
PdfViewerPreferences

A viewer preferences dictionary specifying the way the document shall be displayed on the screen.

See Also

Methods

Clone()

Makes a deep clone of this PdfDocument instance.

The clone and this PdfDocument do not share any objects, thus the cloned PdfDocument is a deep clone of this PdfDocument.

public PdfDocument Clone()
Public Function Clone As PdfDocument
Returns
PdfDocument

A deep clone of this PdfDocument instance.

Close()

Closes the PDF file associated with this PdfDocument.

Any PdfDocument that is associated with the PDF file should be closed, otherwise memory and resource leaks might occur because PDF file stream might not be closed until the application exists.

public void Close()
Public Sub Close

ConvertToImageSource(ImageSaveOptions)

Converts single page specified in options of this PdfDocument instance to an System.Windows.Media.ImageSource instance.

public ImageSource ConvertToImageSource(ImageSaveOptions options)
Public Function ConvertToImageSource(options As ImageSaveOptions) As ImageSource
Parameters
options
ImageSaveOptions

The options used when converting a single page to an image.

Returns
System.Windows.Media.ImageSource

A new System.Windows.Media.ImageSource instance created from a single page specified in options.

See Also

ConvertToXpsDocument(XpsSaveOptions)

Converts this PdfDocument instance to an System.Windows.Xps.Packaging.XpsDocument instance.

public XpsDocument ConvertToXpsDocument(XpsSaveOptions options)
Public Function ConvertToXpsDocument(options As XpsSaveOptions) As XpsDocument
Parameters
options
XpsSaveOptions

The options used when converting to XML Paper Specification (XPS) document.

Returns
System.Windows.Xps.Packaging.XpsDocument

A New System.Windows.Xps.Packaging.XpsDocument instance created from this PdfDocument instance.

See Also

Dispose()

Closes the PDF file associated with this PdfDocument.

Any PdfDocument that is associated with the PDF file should be closed, otherwise memory and resource leaks might occur because PDF file stream might not be closed until the application exists.

public void Dispose()
Public Sub Dispose
Remarks

This method is used as a convenience so that PdfDocument instance can be used in a using block.

Load()

Loads the PdfDocument entirely from the PDF file.

PDF file remains open. If you want to close the PDF file, use Close() method.

public void Load()
Public Sub Load

Load(Stream)

Loads a PDF document from the specified stream and with the Default options.

public static PdfDocument Load(Stream stream)
Public Shared Function Load(stream As Stream) As PdfDocument
Parameters
stream
System.IO.Stream

The stream from which to load a PDF document.

Returns
PdfDocument

A loaded PDF document.

Exceptions
System.ArgumentNullException

stream is null.

System.ArgumentException

stream is not readable.

InvalidPdfPasswordException

PDF file is encrypted and the password is required to load a PDF document. Use Load(Stream, PdfLoadOptions) method and provide a valid Password.

Load(Stream, PdfLoadOptions)

Loads a PDF document from the specified stream and with the specified options.

public static PdfDocument Load(Stream stream, PdfLoadOptions options)
Public Shared Function Load(stream As Stream, options As PdfLoadOptions) As PdfDocument
Parameters
stream
System.IO.Stream

The stream from which to load a PDF document.

options
PdfLoadOptions

The options used for loading a PdfDocument from a PDF file.

Returns
PdfDocument

A loaded PDF document.

Exceptions
System.ArgumentNullException

stream is null or options is null.

System.ArgumentException

stream is not readable.

InvalidPdfPasswordException

PDF file is encrypted and the Password is invalid.

Load(String)

Loads a PDF document from a file with the specified path and with the Default options.

public static PdfDocument Load(string path)
Public Shared Function Load(path As String) As PdfDocument
Parameters
path
System.String

The path to a file from which to load a PDF document.

Returns
PdfDocument

A loaded PDF document.

Exceptions
System.ArgumentNullException

path is null.

InvalidPdfPasswordException

PDF file is encrypted and the password is required to load a PDF document. Use Load(String, PdfLoadOptions) method and provide a valid Password.

Load(String, PdfLoadOptions)

Loads a PDF document from a file with the specified path and with the specified options.

public static PdfDocument Load(string path, PdfLoadOptions options)
Public Shared Function Load(path As String, options As PdfLoadOptions) As PdfDocument
Parameters
path
System.String

The path to a file from which to load a PDF document.

options
PdfLoadOptions

The options used for loading a PdfDocument from a PDF file.

Returns
PdfDocument

A loaded PDF document.

Exceptions
System.ArgumentNullException

path is null or options is null.

InvalidPdfPasswordException

PDF file is encrypted and the Password is invalid.

Print()

Prints the document to the default printer.

public void Print()
Public Sub Print

Print(String)

Prints the document to the specified printer.

public void Print(string printerName)
Public Sub Print(printerName As String)
Parameters
printerName
System.String

Printer name.

Print(String, PrintOptions)

Prints the document to the specified printer according to specified options.

public void Print(string printerName, PrintOptions options)
Public Sub Print(printerName As String, options As PrintOptions)
Parameters
printerName
System.String

Printer name.

options
PrintOptions

Print options.

Save()

Save all the changes made to the current PDF document to the same location from where the PDF document was loaded or last saved.

This feature is also called incremental update.

Use SaveOptions to specify options used for saving the PdfDocument to a PDF file.

[ComVisible(true)]
public void Save()
<ComVisible(True)>
Public Sub Save
Exceptions
System.InvalidOperationException

PdfDocument is not associated with any PDF file and therefore its changes cannot be saved or the associated PDF file was loaded in a read-only mode. Use Save() with System.String or System.IO.Stream parameters instead to save the entire PdfDocument to a new PDF file.

See Also

Save(Stream)

Saves the entire PDF document to the specified stream.

Use SaveOptions to specify options used for saving the PdfDocument to a PDF file.

[ComVisible(false)]
public void Save(Stream stream)
<ComVisible(False)>
Public Sub Save(stream As Stream)
Parameters
stream
System.IO.Stream

The stream to which to save a PDF document.

Exceptions
System.ArgumentNullException

stream is null.

System.ArgumentException

stream is not writable.

Save(Stream, SaveOptions)

Saves the entire PDF document to the specified stream.

[ComVisible(false)]
public void Save(Stream stream, SaveOptions options)
<ComVisible(False)>
Public Sub Save(stream As Stream, options As SaveOptions)
Parameters
stream
System.IO.Stream

The stream to which to save a PDF document.

options
SaveOptions

The saving options which can be used to define settings for save operation.

Exceptions
System.ArgumentNullException

stream is null.

System.ArgumentNullException

options is null.

Save(String)

Saves the entire PDF document to a file with the specified path.

Use SaveOptions to specify options used for saving the PdfDocument to a PDF file.

[ComVisible(false)]
public void Save(string path)
<ComVisible(False)>
Public Sub Save(path As String)
Parameters
path
System.String

The path to a file to which to save a PDF document.

Exceptions
System.ArgumentNullException

path is null.

Save(String, SaveOptions)

Saves the entire PDF document to a file with the specified path.

[ComVisible(false)]
public void Save(string path, SaveOptions options)
<ComVisible(False)>
Public Sub Save(path As String, options As SaveOptions)
Parameters
path
System.String

The path to a file to which to save a PDF document.

options
SaveOptions

The saving options which can be used to define settings for save operation.

Exceptions
System.ArgumentNullException

path is null.

System.ArgumentNullException

options is null.

SetId(Guid)

Sets the Id to a specified System.Guid value. Both Creation and Modification will be set to the specified System.Guid value.

public PdfDocumentIdentifier SetId(Guid value)
Public Function SetId(value As Guid) As PdfDocumentIdentifier
Parameters
value
System.Guid

The System.Guid value to which Creation and Modification will be set.

Returns
PdfDocumentIdentifier

The document's Id.

Exceptions
System.InvalidOperationException

PdfDocument already has an Id. To modify the Id, use Modification property of the PdfDocument's Id.

System.ArgumentException

Value is System.Guid.Empty.

SetPortfolio()

Sets a new PdfPortfolio to the Portfolio property thus making the this PdfDocument a PDF Portfolio (a collection of EmbeddedFiles).

This method also clears EmbeddedFiles collection so that a new PdfPortfolio is empty.

public PdfPortfolio SetPortfolio()
Public Function SetPortfolio As PdfPortfolio
Returns
PdfPortfolio

A new PdfPortfolio set to the Portfolio property.

See Also

ToString()

Returns a System.String that represents this PdfDocument instance.

public override string ToString()
Public Overrides Function ToString As String
Returns
System.String

A System.String that represents this PdfDocument instance.

Overrides
System.Object.ToString()
Remarks

This method should be used primarily for debugging purposes and should be considered volatile (format of its return value might change in future versions).

Unload()

The method that does exactly the opposite of the Load() method.

References to all PdfIndirectObjects whose Values were already parsed from the PDF file associated with this PdfDocument are cleared so they can be parsed again when requested for the first time.

This method also resets all fields of the PdfDocument so they are recreated when requested for the first time.

The PdfDocument is, effectively, reset to the state when it was either last loaded from a PDF file or last saved to a PDF file.

Use this method if you are reading a very large PDF document (with thousands of pages) to free memory necessary for reading additional pages.

public void Unload()
Public Sub Unload

Implements

System.IDisposable

Extension Methods

Examples