PdfDocument Class

Namespace: Meziantou.Framework.Pdf
Assembly: Meziantou.Framework.Pdf.dll
Package: Meziantou.Framework.Pdf 1.0.7
Source: PdfDocument.cs
Available in package assets: net10.0net11.0

A PDF document: its pages, metadata and outline over the object model (ISO 32000-2).

public sealed class PdfDocument

Remarks

A document is read with PdfDocument.Open or created with the constructor, and written with PdfDocument.Save or, for a document that was read, appended to with PdfDocument.SaveIncremental. The high-level members (PdfDocument.Pages, PdfDocument.Information, PdfDocument.Outlines) read and write the objects of PdfDocument.Objects: changes made through either are visible through both.

A document supports one operation at a time; it is not thread-safe.

Constructors

Name	Description
PdfDocument()	Initializes a new instance of the `PdfDocument` class: an empty PDF 1.7 document without pages.

PdfDocument()

PdfDocument.cs

Initializes a new instance of the PdfDocument class: an empty PDF 1.7 document without pages.

public PdfDocument()

Properties

Name	Description
Catalog	Gets the document catalog (ISO 32000-2, 7.7.2).
EmbeddedFiles	Gets the files embedded in the document (ISO 32000-2, 7.11.4): the `/EmbeddedFiles` name tree of the catalog.
EncryptedPayload	Gets the encrypted payload of the document when it is an unencrypted wrapper document (ISO 32000-2, 7.6.7), or `null`: the embedded file whose relationship is `PdfAssociatedFileRelationship.EncryptedPayload` and that has an encrypted payload dictionary, the one the `/Collection` of the catalog names first.
Encryption	Gets or sets the encryption the document is saved with, or `null` to save it without encryption. A document read from an encrypted file has the encryption of the file, which a full save keeps unless it is replaced or removed; an incremental save cannot change it.
Form	Gets the interactive form of the document (ISO 32000-2, 12.7): its fields, to read, fill or flatten them.
Information	Gets the document information dictionary (ISO 32000-2, 14.3.3): title, author, dates.
IsEncrypted	Gets a value indicating whether the file the document was read from is encrypted (ISO 32000-2, 7.6).
IsRepaired	Gets a value indicating whether the cross-reference information of the file was wrong and was rebuilt by scanning the file. A repaired document cannot be saved incrementally.
Language	Gets or sets the natural language of the document (`/Lang` of the catalog, ISO 32000-2, 14.9.2): a BCP 47 tag such as `en-US`.
Objects	Gets the indirect objects of the document.
Outlines	Gets the top-level items of the document outline, the bookmarks (ISO 32000-2, 12.3.3).
PageLabels	Gets the page labels of the document (ISO 32000-2, 12.4.2): the labels viewers show instead of the page numbers, such as `i`, `ii` for the front matter.
Pages	Gets the pages of the document.
PdfAConformance	Gets or sets the PDF/A conformance level the document is saved with. The save checks what it can (no encryption, embedded fonts, a structure tree for the level A, the actions, the annotation appearances, the device color spaces) and writes the output intent (sRGB, unless the document has one) and the XMP identification; the content must follow the other rules of the level.
PdfUAConformance	Gets or sets the PDF/UA conformance level the document is saved with. The save checks the structure tree, the title, the language and the fonts, and writes the XMP identification and the viewer preferences; every content must be tagged or an artifact, and every figure must have an alternate description.
Permissions	Gets the operations the password the document was opened with allows: every operation for the owner password or a file that is not encrypted, the permissions of the file for the user password, and those of the recipient for a document encrypted for certificates. The library does not enforce them.
StructureTree	Gets the structure tree of the document (ISO 32000-2, 14.7): the logical structure of a tagged document.
Trailer	Gets the trailer dictionary (ISO 32000-2, 7.5.5): `/Root`, `/Info` and `/ID`. The writer computes the other entries.
Version	Gets or sets the version of the document: the version of the header, or of the `/Version` entry of the catalog when it is later.

Catalog

PdfDocument.cs

Gets the document catalog (ISO 32000-2, 7.7.2).

public PdfDictionary Catalog { get; }

Property value

PdfDictionary

EmbeddedFiles

PdfDocument.cs

Gets the files embedded in the document (ISO 32000-2, 7.11.4): the /EmbeddedFiles name tree of the catalog.

public PdfEmbeddedFileCollection EmbeddedFiles { get; }

Property value

PdfEmbeddedFileCollection

EncryptedPayload

PdfDocument.EncryptedPayload.cs

Gets the encrypted payload of the document when it is an unencrypted wrapper document (ISO 32000-2, 7.6.7), or null: the embedded file whose relationship is PdfAssociatedFileRelationship.EncryptedPayload and that has an encrypted payload dictionary, the one the /Collection of the catalog names first.

public PdfEncryptedPayload? EncryptedPayload { get; }

Property value

PdfEncryptedPayload?

Encryption

PdfDocument.cs

Gets or sets the encryption the document is saved with, or null to save it without encryption. A document read from an encrypted file has the encryption of the file, which a full save keeps unless it is replaced or removed; an incremental save cannot change it.

public PdfEncryption? Encryption { get; set; }

Property value

PdfEncryption?

Form

PdfDocument.cs

Gets the interactive form of the document (ISO 32000-2, 12.7): its fields, to read, fill or flatten them.

public PdfInteractiveForm Form { get; }

Property value

PdfInteractiveForm

Information

PdfDocument.cs

Gets the document information dictionary (ISO 32000-2, 14.3.3): title, author, dates.

public PdfDocumentInformation Information { get; }

Property value

PdfDocumentInformation

IsEncrypted

PdfDocument.cs

Gets a value indicating whether the file the document was read from is encrypted (ISO 32000-2, 7.6).

public bool IsEncrypted { get; }

Property value

bool

IsRepaired

PdfDocument.cs

Gets a value indicating whether the cross-reference information of the file was wrong and was rebuilt by scanning the file. A repaired document cannot be saved incrementally.

public bool IsRepaired { get; }

Property value

bool

Language

PdfDocument.cs

Gets or sets the natural language of the document (/Lang of the catalog, ISO 32000-2, 14.9.2): a BCP 47 tag such as en-US.

public string? Language { get; set; }

Property value

string?

Objects

PdfDocument.cs

Gets the indirect objects of the document.

public PdfIndirectObjectCollection Objects { get; }

Property value

PdfIndirectObjectCollection

Outlines

PdfDocument.cs

Gets the top-level items of the document outline, the bookmarks (ISO 32000-2, 12.3.3).

public PdfOutlineCollection Outlines { get; }

Property value

PdfOutlineCollection

PageLabels

PdfDocument.cs

Gets the page labels of the document (ISO 32000-2, 12.4.2): the labels viewers show instead of the page numbers, such as i, ii for the front matter.

public PdfPageLabelCollection PageLabels { get; }

Property value

PdfPageLabelCollection

Pages

PdfDocument.cs

Gets the pages of the document.

public PdfPageCollection Pages { get; }

Property value

PdfPageCollection

PdfAConformance

PdfDocument.cs

Gets or sets the PDF/A conformance level the document is saved with. The save checks what it can (no encryption, embedded fonts, a structure tree for the level A, the actions, the annotation appearances, the device color spaces) and writes the output intent (sRGB, unless the document has one) and the XMP identification; the content must follow the other rules of the level.

public PdfAConformance PdfAConformance { get; set; }

Property value

PdfAConformance

PdfUAConformance

PdfDocument.cs

Gets or sets the PDF/UA conformance level the document is saved with. The save checks the structure tree, the title, the language and the fonts, and writes the XMP identification and the viewer preferences; every content must be tagged or an artifact, and every figure must have an alternate description.

public PdfUAConformance PdfUAConformance { get; set; }

Property value

PdfUAConformance

Permissions

PdfDocument.cs

Gets the operations the password the document was opened with allows: every operation for the owner password or a file that is not encrypted, the permissions of the file for the user password, and those of the recipient for a document encrypted for certificates. The library does not enforce them.

public PdfPermissions Permissions { get; }

Property value

PdfPermissions

StructureTree

PdfDocument.cs

Gets the structure tree of the document (ISO 32000-2, 14.7): the logical structure of a tagged document.

public PdfStructureTree StructureTree { get; }

Property value

PdfStructureTree

Trailer

PdfDocument.cs

Gets the trailer dictionary (ISO 32000-2, 7.5.5): /Root, /Info and /ID. The writer computes the other entries.

public PdfDictionary Trailer { get; }

Property value

PdfDictionary

Version

PdfDocument.cs

Gets or sets the version of the document: the version of the header, or of the /Version entry of the catalog when it is later.

public PdfVersion Version { get; set; }

Property value

PdfVersion

Methods

Name	Description
CreateForm(PdfRectangle, PdfMatrix?, PdfTransparencyGroup?)	Creates a form XObject (ISO 32000-2, 8.10): a content painted with `PdfContentBuilder.DrawForm`, or the group of a soft mask.
CreateFormFromPage(PdfPage)	Creates a form XObject (ISO 32000-2, 8.10) whose content is the content of a page, to stamp it on other pages, as an overlay or an underlay (`PdfContentBuilder.DrawForm`). The page can be a page of another document: the objects it uses are copied, once per source document.
CreateTilingPattern(PdfRectangle, double, double, bool, PdfMatrix?)	Creates a tiling pattern (ISO 32000-2, 8.7.3).
GetXmpMetadata()	Gets the XMP metadata of the document (ISO 32000-2, 14.3.2): the `/Metadata` stream of the catalog.
Open(byte[], PdfReadOptions?)	Reads a document.
Open(Stream, PdfReadOptions?)	Reads a document from a stream. The stream is read to its end and is not closed.
Open(ReadOnlyMemory<byte>, PdfReadOptions?)	Reads a document.
Open(string, PdfReadOptions?)	Reads a document from a file.
OpenAsync(Stream, PdfReadOptions?, CancellationToken)	Reads a document from a stream. The stream is read to its end and is not closed.
OpenAsync(string, PdfReadOptions?, CancellationToken)	Reads a document from a file.
OpenSeekable(Stream, PdfReadOptions?)	Reads a document from a seekable stream without copying it to memory: the objects are read from the stream when they are first used, so that the memory does not grow with the size of the file, and a file can be larger than 2 GB.
RemoveXmpMetadata()	Removes the XMP metadata of the document.
Save(Stream, PdfSaveOptions?)	Writes the whole document: the objects reachable from the catalog, renumbered in the order they are reached.
Save(string, PdfSaveOptions?)	Writes the whole document to a file.
SaveAsync(Stream, PdfSaveOptions?, CancellationToken)	Writes the whole document to a stream.
SaveIncremental(Stream, PdfSaveOptions?)	Writes the original file followed by an incremental update (ISO 32000-2, 7.5.6): the objects that were added or changed, the free entries of the removed objects, a cross-reference section of the kind of the original file, and a trailer that points to the original one. The bytes of the original file are kept, so its signatures stay valid. When nothing changed, the original file is written as it is.
SaveIncrementalAsync(Stream, PdfSaveOptions?, CancellationToken)	Writes the original file followed by an incremental update (ISO 32000-2, 7.5.6).
SetEncryptedPayload(string, ReadOnlySpan<byte>, string, string?, PdfEmbeddedFileOptions?)	Makes the document an unencrypted wrapper document (ISO 32000-2, 7.6.7): embeds an encrypted PDF document as its encrypted payload. The pages of the document are what a reader without the cryptographic filter shows: add a page that explains how to open the payload. The document is saved as PDF 2.0 at least, without encryption.
SetXmpMetadata(ReadOnlySpan<byte>)	Sets the XMP metadata of the document (ISO 32000-2, 14.3.2): the `/Metadata` stream of the catalog, written without compression. The existing stream is updated, and left unchanged when it already has the packet, so that an incremental save writes no new object.
ToByteArray(PdfSaveOptions?)	Writes the whole document to an array.
UpdateXmpMetadata()	Updates the XMP metadata with the values of `PdfDocument.Information`: title, author, subject, keywords, producer, creator tool, dates and trapping. The other properties of the existing packet, such as custom schemas, are kept.
UpdateXmpMetadata(int)	Updates the XMP metadata with the values of `PdfDocument.Information`, and reserves whitespace in the packet so that an editor can update it in place. The other properties of the existing packet, such as custom schemas, are kept.

CreateForm(PdfRectangle, PdfMatrix?, PdfTransparencyGroup?)

PdfDocument.cs

Creates a form XObject (ISO 32000-2, 8.10): a content painted with PdfContentBuilder.DrawForm, or the group of a soft mask.

public PdfForm CreateForm(PdfRectangle boundingBox, PdfMatrix? matrix = null, PdfTransparencyGroup? group = null)

Parameters

boundingBox PdfRectangle: The bounding box of the form, in its own coordinate space: the content is clipped to it.
matrix PdfMatrix?: The matrix from the space of the form to the user space it is painted in; null for the identity.
group PdfTransparencyGroup?: The attributes of the transparency group of the form; null when it is not a group.

Returns

PdfForm The form.

CreateFormFromPage(PdfPage)

PdfDocument.cs

Creates a form XObject (ISO 32000-2, 8.10) whose content is the content of a page, to stamp it on other pages, as an overlay or an underlay (PdfContentBuilder.DrawForm). The page can be a page of another document: the objects it uses are copied, once per source document.

public PdfForm CreateFormFromPage(PdfPage page)

Parameters

page PdfPage: The page.

Returns

PdfForm The form: its bounding box is the visible region of the page (the crop box clipped to the media box), and its matrix is PdfPage.UserSpaceToDisplay, so that it is painted upright, with its lower-left corner at the origin and the size PdfPage.DisplaySize, whatever the rotation of the page. The annotations of the page are not part of it.

Exceptions

InvalidPdfContentException: A content stream of the page cannot be decoded.

CreateTilingPattern(PdfRectangle, double, double, bool, PdfMatrix?)

PdfDocument.cs

Creates a tiling pattern (ISO 32000-2, 8.7.3).

public PdfTilingPattern CreateTilingPattern(PdfRectangle cell, double xStep, double yStep, bool isColored = true, PdfMatrix? matrix = null)

Parameters

cell PdfRectangle: The bounding box of the cell, in the pattern space: the content of the cell is clipped to it.
xStep double: The horizontal spacing of the cells.
yStep double: The vertical spacing of the cells.
isColored bool: true when the cell sets its colors; false for a stencil painted with the color given when the pattern is set.
matrix PdfMatrix?: The matrix from the pattern space to the default coordinate space of the page; null for the identity.

Returns

PdfTilingPattern The pattern.

GetXmpMetadata()

PdfDocument.Metadata.cs

Gets the XMP metadata of the document (ISO 32000-2, 14.3.2): the /Metadata stream of the catalog.

public byte[]? GetXmpMetadata()

Returns

byte[]? The XMP packet, or null when the document has none.

Open overloads

Open(byte[], PdfReadOptions?)

PdfDocument.cs

Reads a document.

public static PdfDocument Open(byte[] data, PdfReadOptions? options = null)

Parameters

data byte[]: The content of the file.
options PdfReadOptions?: The options, or null for PdfReadOptions.Default.

Returns

PdfDocument The document. It keeps data: the array must not change while the document is used.

Exceptions

InvalidPdfContentException: The data is not a PDF document, or it cannot be recovered.
UnsupportedPdfFeatureException: The document uses a feature the library does not support.
PdfResourceLimitException: The document exceeds a limit of the options.
PdfPasswordException: The document is encrypted, and PdfReadOptions.Password is neither its user nor its owner password, or PdfReadOptions.Certificate is not a recipient.

Open(Stream, PdfReadOptions?)

PdfDocument.cs

Reads a document from a stream. The stream is read to its end and is not closed.

public static PdfDocument Open(Stream stream, PdfReadOptions? options = null)

Parameters

stream Stream: The stream.
options PdfReadOptions?: The options, or null for PdfReadOptions.Default.

Returns

PdfDocument The document.

Exceptions

InvalidPdfContentException: The data is not a PDF document, or it cannot be recovered.
UnsupportedPdfFeatureException: The document uses a feature the library does not support.
PdfResourceLimitException: The document exceeds a limit of the options.
PdfPasswordException: The document is encrypted, and PdfReadOptions.Password is neither its user nor its owner password, or PdfReadOptions.Certificate is not a recipient.

Open(ReadOnlyMemory<byte>, PdfReadOptions?)

PdfDocument.cs

Reads a document.

public static PdfDocument Open(ReadOnlyMemory<byte> data, PdfReadOptions? options = null)

Parameters

data ReadOnlyMemory<byte>: The content of the file. It must not change while the document is used.
options PdfReadOptions?: The options, or null for PdfReadOptions.Default.

Returns

PdfDocument The document.

Exceptions

InvalidPdfContentException: The data is not a PDF document, or it cannot be recovered.
UnsupportedPdfFeatureException: The document uses a feature the library does not support.
PdfResourceLimitException: The document exceeds a limit of the options.
PdfPasswordException: The document is encrypted, and PdfReadOptions.Password is neither its user nor its owner password, or PdfReadOptions.Certificate is not a recipient.

Open(string, PdfReadOptions?)

PdfDocument.cs

Reads a document from a file.

public static PdfDocument Open(string path, PdfReadOptions? options = null)

Parameters

path string: The path of the file.
options PdfReadOptions?: The options, or null for PdfReadOptions.Default.

Returns

PdfDocument The document.

Exceptions

InvalidPdfContentException: The data is not a PDF document, or it cannot be recovered.
UnsupportedPdfFeatureException: The document uses a feature the library does not support.
PdfResourceLimitException: The document exceeds a limit of the options.
PdfPasswordException: The document is encrypted, and PdfReadOptions.Password is neither its user nor its owner password, or PdfReadOptions.Certificate is not a recipient.

OpenAsync overloads

OpenAsync(Stream, PdfReadOptions?, CancellationToken)

PdfDocument.cs

Reads a document from a stream. The stream is read to its end and is not closed.

net10.0

public static Task<PdfDocument> OpenAsync(Stream stream, PdfReadOptions? options = null, CancellationToken cancellationToken = default)

net11.0

public static Task<PdfDocument> OpenAsync(Stream stream, PdfReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The stream.
options PdfReadOptions?: The options, or null for PdfReadOptions.Default.
cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

Task<PdfDocument> The document.

Exceptions

InvalidPdfContentException: The data is not a PDF document, or it cannot be recovered.
UnsupportedPdfFeatureException: The document uses a feature the library does not support.
PdfResourceLimitException: The document exceeds a limit of the options.
PdfPasswordException: The document is encrypted, and PdfReadOptions.Password is neither its user nor its owner password, or PdfReadOptions.Certificate is not a recipient.

OpenAsync(string, PdfReadOptions?, CancellationToken)

PdfDocument.cs

Reads a document from a file.

net10.0

public static Task<PdfDocument> OpenAsync(string path, PdfReadOptions? options = null, CancellationToken cancellationToken = default)

net11.0

public static Task<PdfDocument> OpenAsync(string path, PdfReadOptions? options = null, CancellationToken cancellationToken = default)

Parameters

path string: The path of the file.
options PdfReadOptions?: The options, or null for PdfReadOptions.Default.
cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

Task<PdfDocument> The document.

Exceptions

InvalidPdfContentException: The data is not a PDF document, or it cannot be recovered.
UnsupportedPdfFeatureException: The document uses a feature the library does not support.
PdfResourceLimitException: The document exceeds a limit of the options.
PdfPasswordException: The document is encrypted, and PdfReadOptions.Password is neither its user nor its owner password, or PdfReadOptions.Certificate is not a recipient.

OpenSeekable(Stream, PdfReadOptions?)

PdfDocument.cs

Reads a document from a seekable stream without copying it to memory: the objects are read from the stream when they are first used, so that the memory does not grow with the size of the file, and a file can be larger than 2 GB.

public static PdfDocument OpenSeekable(Stream stream, PdfReadOptions? options = null)

Parameters

stream Stream: The stream, positioned at the start of the file. It belongs to the caller: the document does not close it. It must stay open and unchanged while the document is used, and it must not be used by anything else meanwhile: the document moves its position.
options PdfReadOptions?: The options, or null for PdfReadOptions.Default.

Returns

PdfDocument The document.

Exceptions

ArgumentException: The stream cannot seek or cannot be read.
InvalidPdfContentException: The data is not a PDF document, or it cannot be recovered.
UnsupportedPdfFeatureException: The document uses a feature the library does not support.
PdfResourceLimitException: The document exceeds a limit of the options.
PdfPasswordException: The document is encrypted, and PdfReadOptions.Password is neither its user nor its owner password, or PdfReadOptions.Certificate is not a recipient.

Remarks

The errors of the stream (IOException, ObjectDisposedException) are not caught: they can occur whenever an object is first used.

Example

// The objects are read from the stream when they are first used: it stays open while the document is used
using var stream = File.OpenRead(path);
var document = PdfDocument.OpenSeekable(stream);
var text = document.Pages[0].ExtractText();

RemoveXmpMetadata()

PdfDocument.Metadata.cs

Removes the XMP metadata of the document.

public void RemoveXmpMetadata()

Save overloads

Save(Stream, PdfSaveOptions?)

PdfDocument.cs

Writes the whole document: the objects reachable from the catalog, renumbered in the order they are reached.

public void Save(Stream stream, PdfSaveOptions? options = null)

Parameters

stream Stream: The stream to write to. It is not closed.
options PdfSaveOptions?: The options, or null for PdfSaveOptions.Default.

Remarks

The file is written to the stream as it is serialized, through a buffer of bounded size: when the save fails, the stream may contain the beginning of the file.

Save(string, PdfSaveOptions?)

PdfDocument.cs

Writes the whole document to a file.

public void Save(string path, PdfSaveOptions? options = null)

Parameters

path string: The path of the file. An existing file is replaced.
options PdfSaveOptions?: The options, or null for PdfSaveOptions.Default.

Remarks

The file is written as the document is serialized; when the save fails, the incomplete file is deleted.

SaveAsync(Stream, PdfSaveOptions?, CancellationToken)

PdfDocument.cs

Writes the whole document to a stream.

net10.0

public Task SaveAsync(Stream stream, PdfSaveOptions? options = null, CancellationToken cancellationToken = default)

net11.0

public Task SaveAsync(Stream stream, PdfSaveOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The stream to write to. It is not closed.
options PdfSaveOptions?: The options, or null for PdfSaveOptions.Default.
cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

Task A task that completes when the document is written.

Exceptions

OperationCanceledException: The save was canceled.

Remarks

The document is serialized synchronously, on the calling thread, into blocks of memory, and the blocks are then written to the stream asynchronously. Cancellation is observed while the objects are serialized, between the objects, and while the blocks are written: the stream is untouched when the save is canceled before the first block is written, and may contain the beginning of the file otherwise. The data of the streams of a document read with PdfDocument.OpenSeekable that was not loaded is read from the stream of the document when it is written.

SaveIncremental(Stream, PdfSaveOptions?)

PdfDocument.cs

Writes the original file followed by an incremental update (ISO 32000-2, 7.5.6): the objects that were added or changed, the free entries of the removed objects, a cross-reference section of the kind of the original file, and a trailer that points to the original one. The bytes of the original file are kept, so its signatures stay valid. When nothing changed, the original file is written as it is.

public void SaveIncremental(Stream stream, PdfSaveOptions? options = null)

Parameters

stream Stream: The stream to write to. It is not closed.
options PdfSaveOptions?: The options, or null for PdfSaveOptions.Default. With PdfSaveOptions.UseObjectStreams, the objects of the update are written in object streams when the original file has cross-reference streams.

Exceptions

InvalidOperationException: The document was not read from a file, or its cross-reference information was rebuilt (PdfDocument.IsRepaired).

Remarks

The original file is copied to the stream without being buffered again, and the update is written through a buffer of bounded size: when the save fails, the stream may contain the beginning of the file.

SaveIncrementalAsync(Stream, PdfSaveOptions?, CancellationToken)

PdfDocument.cs

Writes the original file followed by an incremental update (ISO 32000-2, 7.5.6).

net10.0

public Task SaveIncrementalAsync(Stream stream, PdfSaveOptions? options = null, CancellationToken cancellationToken = default)

net11.0

public Task SaveIncrementalAsync(Stream stream, PdfSaveOptions? options = null, CancellationToken cancellationToken = default)

Parameters

stream Stream: The stream to write to. It is not closed.
options PdfSaveOptions?: The options, or null for PdfSaveOptions.Default.
cancellationToken CancellationToken: The token to monitor for cancellation requests.

Returns

Task A task that completes when the document is written.

Exceptions

InvalidOperationException: The document was not read from a file, or its cross-reference information was rebuilt (PdfDocument.IsRepaired).
OperationCanceledException: The save was canceled.

Remarks

The update is serialized synchronously, on the calling thread, and the original file and the update are then written to the stream asynchronously; the original file is not copied in memory. Cancellation is observed as for PdfDocument.SaveAsync.

SetEncryptedPayload(string, ReadOnlySpan<byte>, string, string?, PdfEmbeddedFileOptions?)

PdfDocument.EncryptedPayload.cs

Makes the document an unencrypted wrapper document (ISO 32000-2, 7.6.7): embeds an encrypted PDF document as its encrypted payload. The pages of the document are what a reader without the cryptographic filter shows: add a page that explains how to open the payload. The document is saved as PDF 2.0 at least, without encryption.

public PdfEncryptedPayload SetEncryptedPayload(string fileName, ReadOnlySpan<byte> data, string cryptographicFilter, string? version = null, PdfEmbeddedFileOptions? options = null)

Parameters

fileName string: The name of the payload file, such as document.pdf.
data ReadOnlySpan<byte>: The encrypted PDF document.
cryptographicFilter string: The name of the cryptographic filter the payload is encrypted with (/Subtype of the encrypted payload dictionary).
version string?: The version of the cryptographic filter, or null.
options PdfEmbeddedFileOptions?: The description and the dates of the payload file, or null: its MIME type is application/pdf and its relationship PdfAssociatedFileRelationship.EncryptedPayload, whatever the options say.

Returns

PdfEncryptedPayload The payload.

Exceptions

ArgumentException: fileName or cryptographicFilter is empty, or fileName is the name of another file of the document.
InvalidOperationException: The document already has an encrypted payload.

Example

// The wrapper is not encrypted: its pages tell a reader without the cryptographic filter how to open the payload
var wrapper = new PdfDocument();
wrapper.Pages.Add(PdfSize.A4).CreateContentBuilder()
    .DrawText("This document is encrypted: open it with a PDF 2.0 reader", PdfFont.GetStandardFont(PdfStandardFont.Helvetica), 12, 60, 700);
wrapper.SetEncryptedPayload("document.pdf", encryptedPdf, cryptographicFilter: "Standard");
var file = wrapper.ToByteArray();

// A reader finds the payload, and opens it with its password
var payload = PdfDocument.Open(file).EncryptedPayload;
var document = payload?.OpenDocument(new PdfReadOptions { Password = "password" });

SetXmpMetadata(ReadOnlySpan<byte>)

PdfDocument.Metadata.cs

Sets the XMP metadata of the document (ISO 32000-2, 14.3.2): the /Metadata stream of the catalog, written without compression. The existing stream is updated, and left unchanged when it already has the packet, so that an incremental save writes no new object.

public void SetXmpMetadata(ReadOnlySpan<byte> packet)

Parameters

packet ReadOnlySpan<byte>: The XMP packet.

ToByteArray(PdfSaveOptions?)

PdfDocument.cs

Writes the whole document to an array.

public byte[] ToByteArray(PdfSaveOptions? options = null)

Parameters

options PdfSaveOptions?: The options, or null for PdfSaveOptions.Default.

Returns

byte[] The content of the file.

UpdateXmpMetadata overloads

UpdateXmpMetadata()

PdfDocument.Metadata.cs

Updates the XMP metadata with the values of PdfDocument.Information: title, author, subject, keywords, producer, creator tool, dates and trapping. The other properties of the existing packet, such as custom schemas, are kept.

public void UpdateXmpMetadata()

UpdateXmpMetadata(int)

PdfDocument.Metadata.cs

Updates the XMP metadata with the values of PdfDocument.Information, and reserves whitespace in the packet so that an editor can update it in place. The other properties of the existing packet, such as custom schemas, are kept.

public void UpdateXmpMetadata(int padding)

Parameters

padding int: The number of whitespace bytes before the end of the packet; 2048 to 4096 are common values.

Exceptions

ArgumentOutOfRangeException: padding is negative.