Class PdfDocument

Namespace

MiPdf

Assembly

MiPdf.dll

A PDF document. Use Create() for new documents or Open(string, string?) to load existing files. Objects of opened files are loaded lazily; unchanged objects are written back as they are.

public sealed class PdfDocument : IDisposable

Inheritance

object

PdfDocument

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Properties

Attachments

The files embedded in the document (EmbeddedFiles name tree).

public IReadOnlyList<PdfAttachment> Attachments { get; }

Property Value

IReadOnlyList<PdfAttachment>

Catalog

The document catalog (/Root).

public PdfDictionary Catalog { get; }

Property Value

PdfDictionary

Conformance

PDF/A conformance to produce. When set, saving adds XMP metadata with PDF/A identification, an sRGB output intent and synchronizes the document information. Use PdfAChecker to find content that violates the standard (e.g. non-embedded fonts).

public PdfAConformance? Conformance { get; set; }

Property Value

PdfAConformance?

EncryptionRevision

Encryption revision of an encrypted document (2–6), 0 if not encrypted.

public int EncryptionRevision { get; }

Property Value

int

HasOutlines

True if the document has bookmarks.

public bool HasOutlines { get; }

Property Value

bool

IgnorePermissions

Allows changing or removing the encryption of a document that was opened with the user password only. The document's permissions are then not enforced by miPDFlib – the caller is responsible for respecting them (e.g. when the application itself created the document). Default false.

public bool IgnorePermissions { get; set; }

Property Value

bool

Info

Document information (title, author, ...).

public PdfDocumentInfo Info { get; }

Property Value

PdfDocumentInfo

IsEncrypted

True if the document is (or will be saved) encrypted.

public bool IsEncrypted { get; }

Property Value

bool

IsOpenedFromFile

True if the document was opened from existing PDF data.

public bool IsOpenedFromFile { get; }

Property Value

bool

IsOwnerAccess

True if the document was opened with the owner password (or is not encrypted). Without owner access the Permissions should be respected.

public bool IsOwnerAccess { get; }

Property Value

bool

IsTagged

True if the document is marked as tagged PDF (/MarkInfo /Marked true).

public bool IsTagged { get; }

Property Value

bool

Language

Default natural language of the document (/Lang), e.g. "de-AT". Required by PDF/UA.

public string? Language { get; set; }

Property Value

string

Outlines

The root of the bookmark tree (created on first access). Add top-level bookmarks with Outlines.AddChild.

public PdfOutline Outlines { get; }

Property Value

PdfOutline

PageCount

The number of pages.

public int PageCount { get; }

Property Value

int

PageLabels

The page labels (logical page numbers shown by viewers).

public PdfPageLabels PageLabels { get; }

Property Value

PdfPageLabels

PageLayout

Page layout used when the document is opened (/PageLayout); SinglePage if missing or unknown.

public PdfPageLayout PageLayout { get; set; }

Property Value

PdfPageLayout

PageMode

Panel shown when the document is opened (/PageMode); UseNone if missing or unknown. Creating the bookmark tree (first access of Outlines) sets UseOutlines.

public PdfPageMode PageMode { get; set; }

Property Value

PdfPageMode

Pages

The pages of the document in order.

public IReadOnlyList<PdfPage> Pages { get; }

Property Value

IReadOnlyList<PdfPage>

Permissions

The permissions granted to users of an encrypted document (all permissions if not encrypted).

public PdfPermissions Permissions { get; }

Property Value

PdfPermissions

StructureTree

The structure tree if tagging was enabled with EnableTagging(), otherwise null.

public PdfStructureTree? StructureTree { get; }

Property Value

PdfStructureTree

Trailer

The trailer dictionary (contains /Root, /Info, /ID, /Encrypt).

public PdfDictionary Trailer { get; }

Property Value

PdfDictionary

UAConformance

PDF/UA conformance to produce. Setting it enables tagging; saving adds the PDF/UA identification to the XMP metadata, sets DisplayDocTitle, the tab order of pages with annotations and tags annotations that are not in the structure tree yet. Use CheckPdfUA() to find remaining problems (e.g. untagged content, fonts that are not embedded, missing alternate text).

public PdfUAConformance? UAConformance { get; set; }

Property Value

PdfUAConformance?

Version

PDF version of the document, e.g. "1.7". Taken from the header or the catalog's /Version.

public string Version { get; set; }

Property Value

string

ViewerPreferences

Viewer preferences (/ViewerPreferences).

public PdfViewerPreferences ViewerPreferences { get; }

Property Value

PdfViewerPreferences

WasRepaired

True if the cross-reference information of the file was damaged and has been reconstructed.

public bool WasRepaired { get; }

Property Value

bool

XmpExtensions

Custom XMP schemas written with the metadata when Conformance or PDF/UA is set (e.g. Factur-X).

public IList<XmpExtensionSchema> XmpExtensions { get; }

Property Value

IList<XmpExtensionSchema>

Methods

AddAttachment(string, byte[], string?, string?, AttachmentRelationship, DateTimeOffset?)

Embeds a file. An existing attachment with the same name is replaced. For PDF/A-3 the file is also listed in the catalog's /AF array (associated file) with the given relationship.

public PdfAttachment AddAttachment(string fileName, byte[] data, string? mimeType = null, string? description = null, AttachmentRelationship relationship = AttachmentRelationship.Unspecified, DateTimeOffset? modificationDate = null)

Parameters

fileName string

File name shown in viewers, e.g. "invoice.xml".

data byte[]

File content.

mimeType string

MIME type, e.g. "text/xml" or "application/pdf" (required by PDF/A-3).

description string

Optional description.

relationship AttachmentRelationship

Relationship to the document (PDF/A-3 /AFRelationship).

modificationDate DateTimeOffset?

Modification date of the file (default: now).

Returns

PdfAttachment

AddObject(PdfObject)

Registers obj as indirect object and returns a reference to it.

public PdfReference AddObject(PdfObject obj)

Parameters

obj PdfObject

Returns

PdfReference

AddPage(PdfRectangle?)

Appends a new empty page (default A4 portrait).

public PdfPage AddPage(PdfRectangle? size = null)

Parameters

size PdfRectangle?

Returns

PdfPage

ApplyRedactions(RedactionOptions?)

Applies all Redact annotations (see MarkForRedaction(PdfPage, PdfRectangle, string?)).

public RedactionResult ApplyRedactions(RedactionOptions? options = null)

Parameters

options RedactionOptions

Returns

RedactionResult

CheckPdfA(PdfAConformance)

Checks the document against basic PDF/A rules (see PdfAChecker).

public IReadOnlyList<string> CheckPdfA(PdfAConformance conformance)

Parameters

conformance PdfAConformance

Returns

IReadOnlyList<string>

Remarks

If Conformance is set, the metadata and output intent written on saving are created first.

CheckPdfUA()

Checks the document against the machine-checkable PDF/UA rules (see PdfUAChecker). If UAConformance is set, the fixes that saving applies (metadata, tab order, annotation tags) are applied first, so the result reflects the document as it will be saved.

public IReadOnlyList<string> CheckPdfUA()

Returns

IReadOnlyList<string>

Create()

Creates a new, empty document.

public static PdfDocument Create()

Returns

PdfDocument

Dispose()

Releases the document: closes the file of a document that is read on demand (ReadFromFile).

public void Dispose()

EnableTagging()

Turns the document into a tagged PDF and returns its structure tree. Existing structure trees are continued. Afterwards the layout engine tags paragraphs, tables, images and barcodes automatically; custom drawing can be tagged with BeginTag(PdfStructureElement) or marked as artifact.

public PdfStructureTree EnableTagging()

Returns

PdfStructureTree

Encrypt(PdfEncryptionOptions)

Encrypts the document when it is saved next. Requires a full save (not incremental).

public void Encrypt(PdfEncryptionOptions options)

Parameters

options PdfEncryptionOptions

ExtractPages(IEnumerable<int>)

Creates a new document containing copies of the given pages (1-based page numbers).

public PdfDocument ExtractPages(IEnumerable<int> pageNumbers)

Parameters

pageNumbers IEnumerable<int>

Returns

PdfDocument

ExtractText(TextExtractionOptions?)

Extracts the text of all pages; pages are separated by form feeds ('\f').

public string ExtractText(TextExtractionOptions? options = null)

Parameters

options TextExtractionOptions

Returns

string

GetAttachment(string)

Returns the attachment with the given name, or null.

public PdfAttachment? GetAttachment(string name)

Parameters

name string

Returns

PdfAttachment

GetForm()

Returns the interactive form, or null if the document has none.

public PdfAcroForm? GetForm()

Returns

PdfAcroForm

GetImageReference(PdfImage)

Returns the image XObject for image, embedding it on first use.

public PdfReference GetImageReference(PdfImage image)

Parameters

image PdfImage

Returns

PdfReference

GetObject(int)

Returns the indirect object with the given number, or null.

public PdfObject? GetObject(int objectNumber)

Parameters

objectNumber int

Returns

PdfObject

GetObjectNumbers()

Enumerates the numbers of all indirect objects.

public IEnumerable<int> GetObjectNumbers()

Returns

IEnumerable<int>

GetOrCreateForm()

Returns the interactive form, creating an empty one if necessary.

public PdfAcroForm GetOrCreateForm()

Returns

PdfAcroForm

GetPage(int)

Returns the page at the 1-based pageNumber.

public PdfPage GetPage(int pageNumber)

Parameters

pageNumber int

Returns

PdfPage

GetPageLabel(int)

The label of page pageNumber (1-based), see GetLabel(int).

public string GetPageLabel(int pageNumber)

Parameters

pageNumber int

Returns

string

GetPdfAIdentification()

Reads the PDF/A identification (pdfaid:part / pdfaid:conformance) from the XMP metadata, or null if the document does not claim PDF/A conformance. Note: this is the claim of the document, not a validation.

public PdfAIdentification? GetPdfAIdentification()

Returns

PdfAIdentification

GetReference(PdfObject)

Returns the reference of an indirect object of this document, or null for direct objects.

public PdfReference? GetReference(PdfObject obj)

Parameters

obj PdfObject

Returns

PdfReference

GetXmpMetadata()

Returns the XMP metadata of the document, or null.

public byte[]? GetXmpMetadata()

Returns

byte[]

ImportObject(PdfObject)

Deep-copies an object (and everything it references) from another document into this one.

public PdfObject ImportObject(PdfObject obj)

Parameters

obj PdfObject

Returns

PdfObject

ImportPage(PdfPage, int?)

Copies a single page of another document.

public PdfPage ImportPage(PdfPage sourcePage, int? insertIndex = null)

Parameters

sourcePage PdfPage

insertIndex int?

Returns

PdfPage

ImportPageAsTemplate(PdfPage)

Converts a page of another (or this) document into a form XObject that can be drawn on any page, e.g. to use a PDF letterhead as background (canvas.DrawXObject(template, 0, 0)).

public PdfFormXObject ImportPageAsTemplate(PdfPage sourcePage)

Parameters

sourcePage PdfPage

Returns

PdfFormXObject

ImportPages(PdfDocument, IEnumerable<int>?, int?)

Copies pages of another document to the end of this document (or at insertIndex). Resources shared between the copied pages are copied only once. Links between copied pages are kept.

public IReadOnlyList<PdfPage> ImportPages(PdfDocument source, IEnumerable<int>? pageNumbers = null, int? insertIndex = null)

Parameters

source PdfDocument

The source document.

pageNumbers IEnumerable<int>

1-based page numbers to copy; all pages if null.

insertIndex int?

0-based position in this document; appended if null.

Returns

IReadOnlyList<PdfPage>

The new pages in this document.

InsertPage(int, PdfRectangle?)

Inserts a new empty page at the 0-based index.

public PdfPage InsertPage(int index, PdfRectangle? size = null)

Parameters

index int

size PdfRectangle?

Returns

PdfPage

Merge(IEnumerable<PdfDocument>)

Merges documents into a new document (pages in order).

public static PdfDocument Merge(IEnumerable<PdfDocument> documents)

Parameters

documents IEnumerable<PdfDocument>

Returns

PdfDocument

Merge(params string[])

Merges PDF files into a new document.

public static PdfDocument Merge(params string[] paths)

Parameters

paths string[]

Returns

PdfDocument

MovePage(int, int)

Moves a page from one 0-based position to another.

public void MovePage(int fromIndex, int toIndex)

Parameters

fromIndex int

toIndex int

Open(byte[], string?)

Opens a document from its bytes. The array is used directly, not copied: it must not be modified while the document is in use, nor while objects copied from it into other documents are (stream data is shared).

public static PdfDocument Open(byte[] data, string? password = null)

Parameters

data byte[]

password string

Returns

PdfDocument

Open(Stream, string?)

Opens a document from a stream, which is read from its current position to the end into memory. The stream is not closed. See Open(byte[], string?).

public static PdfDocument Open(Stream stream, string? password = null)

Parameters

stream Stream

password string

Returns

PdfDocument

Open(string, PdfOpenOptions)

Opens a document from a file, in memory or read on demand (ReadFromFile).

public static PdfDocument Open(string path, PdfOpenOptions options)

Parameters

path string

options PdfOpenOptions

Returns

PdfDocument

Open(string, string?)

Opens a document from a file; the whole file is read into memory (files larger than 2 GB are read on demand, see ReadFromFile). See Open(byte[], string?).

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

Parameters

path string

password string

Returns

PdfDocument

RedactText(string, StringComparison, RedactionOptions?)

Redacts every occurrence of text (see PdfRedactor).

public RedactionResult RedactText(string text, StringComparison comparison = StringComparison.Ordinal, RedactionOptions? options = null)

Parameters

text string

comparison StringComparison

options RedactionOptions

Returns

RedactionResult

RedactText(Regex, RedactionOptions?)

Redacts every match of pattern, e.g. IBANs or e-mail addresses.

public RedactionResult RedactText(Regex pattern, RedactionOptions? options = null)

Parameters

pattern Regex

options RedactionOptions

Returns

RedactionResult

RemoveAttachment(string)

Removes an attachment (and its /AF entry); returns false if it does not exist.

public bool RemoveAttachment(string name)

Parameters

name string

Returns

bool

RemoveEncryption()

Removes the encryption; the document is saved unencrypted. Requires owner access.

public void RemoveEncryption()

RemovePage(int)

Removes the page at the 0-based index.

public void RemovePage(int index)

Parameters

index int

ReorderPages(IEnumerable<int>)

Reorders the pages; order lists 0-based indexes of the current pages (may omit or repeat pages).

public void ReorderPages(IEnumerable<int> order)

Parameters

order IEnumerable<int>

ReplaceObject(PdfReference, PdfObject)

Replaces the indirect object behind reference.

public void ReplaceObject(PdfReference reference, PdfObject obj)

Parameters

reference PdfReference

obj PdfObject

Save(Stream, PdfSaveOptions?)

Saves the document to a stream.

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

Parameters

stream Stream

options PdfSaveOptions

Save(string, PdfSaveOptions?)

Saves the document to a file. The document is written to a temporary file in the same directory, which then replaces the target: the target may be the file the document was opened from, and a failed save leaves an existing file unchanged.

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

Parameters

path string

options PdfSaveOptions

SetXmpMetadata(byte[]?)

Sets (or with null removes) the XMP metadata stream.

public void SetXmpMetadata(byte[]? xmp)

Parameters

xmp byte[]

Split(int)

Splits the document into documents of at most pagesPerDocument pages.

public IEnumerable<PdfDocument> Split(int pagesPerDocument = 1)

Parameters

pagesPerDocument int

Returns

IEnumerable<PdfDocument>

ToArray(PdfSaveOptions?)

Saves the document and returns the bytes.

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

Parameters

options PdfSaveOptions

Returns

byte[]