Introduction
Aspose.PDF FOSS for .NET offers two levels of access to a PDF. The document model (Document, Page, and their collections) exposes individual pages and objects. The facades in the Aspose.Pdf.Facades namespace sit one level above it: each facade is built around a whole-document task, such as merging files, encrypting with a password, stamping every page, or pulling out the text.
Several facades share a bind, operate, save shape. You bind a PDF with BindPdf, whose overloads accept a file path, a Stream, or an open Document (PdfFileInfo accepts only a file path or a Document, and several facades also accept a byte[]). You then call the operation methods, and finally call Save. PdfExtractor and PdfConverter are bound the same way but have no Save: they hand their results back through their own methods. PdfFileEditor takes the input and the destination on every call, as file paths, streams, or byte arrays depending on the overload, and a few methods on other facades are stateless in the same way: they take a byte[] and return a new byte[]. The bound facades covered here implement IDisposable, so release them when you are done with a file.
The library is released under the MIT License. After reading this post you will know which facade to use to merge or split files, protect a document with a password, stamp pages, or extract text, images, and attachments, and which method names to look up in the API reference.
Key Features
Page-level editing with PdfFileEditor
PdfFileEditor works on pages across one or several PDFs. Concatenate merges multiple PDF documents into one, Extract pulls a page range out of a document, and Delete removes pages. Append adds pages from a source PDF to an input PDF, and Insert places them at a given position.
Splitting has its own set of methods: Split, SplitFromFirst, SplitToEnd, SplitToBulks (which takes the page groups as an int[][]), and SplitToPages. For layout changes there are MakeBooklet, MakeNUp, AddMargins, and ResizeContents, plus AddMarginsPct and ResizeContentsPct for percentage-based values.
Encryption and permissions with PdfFileSecurity
PdfFileSecurity is bound to a PDF with BindPdf and writes the result with Save. EncryptFile takes a user password, an owner password, and the privileges to grant, and DecryptFile removes the encryption given the owner password. The basic ChangePassword overload replaces the passwords while preserving the existing privileges and AES-128 encryption, and other overloads can also override the privileges and key size.
SetPrivilege applies a DocumentPrivilege to the bound document by re-encrypting it with empty passwords and the given permissions. The Algorithm and KeySize enumerations select the encryption family and key strength. To read the permissions of an existing file, PdfFileInfo.GetDocumentPrivilege returns its document privileges.
Stamps, headers, footers, and page numbers with PdfFileStamp
PdfFileStamp decorates the pages of a bound document. AddStamp adds a facade Stamp, AddHeader and AddFooter take a FormattedText (or an image file or stream) and a margin, and AddPageNumber takes a FormattedText for the numbering style; call Save afterwards to write the result. AddWatermark, AddTextStamp, and AddImageStamp work differently: they are stateless methods that take the PDF as a byte[] and return the stamped PDF as a new byte[], without BindPdf or Save.
Extracting text, images, and attachments with PdfExtractor
PdfExtractor reads content out of a bound PDF. ExtractText walks every page and gathers the text, and GetText writes it to a stream. For page-by-page access, HasNextPageText reports whether another page is available and GetNextPageText writes that page’s text to a file path.
Images follow the same pattern with ExtractImage, HasNextImage, and GetNextImage. Embedded files are listed with GetAttachNames, selected with ExtractAttachment, and retrieved with GetAttachment.
Bookmarks, page geometry, and form fields
Three facades cover document structure. PdfBookmarkEditor creates bookmarks with CreateBookmarks, reads the outline with ExtractBookmarks, and moves it in and out of XML with ExportBookmarksToXML and ImportBookmarksWithXML. PdfPageEditor changes page geometry in two ways. RotatePages, ResizePages, and SetCropBox are stateless methods that take the PDF as a byte[] and return a new byte[]. For a bound document, page-size settings are queued through properties and applied with ApplyChanges.
FormEditor edits AcroForm fields. AddTextField and AddCheckBox create fields at a given page position, SetField assigns a value by field name, and RemoveField deletes a field.
Rendering pages to images and reading metadata
PdfConverter is bound to a Document and renders pages to image bytes. DoConvert initializes the iteration, HasNextImage reports whether another page remains, and GetNextImage renders it in a PdfConverterImageFormat (Png, Jpeg, Bmp, Tiff, or Gif). SaveAsTIFF writes all bound pages to a single TIFF file.
PdfFileInfo reads and writes document-level information. GetMetaInfo and SetMetaInfo work with custom metadata properties, GetPdfVersion reports the PDF version, and SaveNewInfo saves the modified information to a new PDF file.
Quick Start
Add the package to a .NET 8+ project:
dotnet add package Aspose.PDF.FOSSThen follow the same pattern for any bound facade:
- Create the facade, for example
PdfFileSecurity,PdfFileStamp, orPdfExtractor. - Call
BindPdfwith the file path, stream, or openDocumentyou want to work on. - Call the operation methods for your task, such as
EncryptFile,AddHeader, orExtractText. - Call
Saveon facades that modify the PDF (PdfExtractorandPdfConverterreturn their results through their own methods instead), and dispose the facade when you are done.
For multi-file page operations, skip the binding step and call PdfFileEditor methods such as Concatenate or Extract directly with your inputs and destination. Methods that take a byte[] and return a byte[], such as AddWatermark on PdfFileStamp or RotatePages on PdfPageEditor, need neither BindPdf nor Save. The following example uses two of them on PdfFileStamp:
using Aspose.Pdf.Facades;
byte[] input = File.ReadAllBytes("input.pdf");
var facade = new PdfFileStamp();
byte[] approved = facade.AddTextStamp(input, "APPROVED");
byte[] draft = facade.AddWatermark(input, "DRAFT");
File.WriteAllBytes("approved.pdf", approved);
File.WriteAllBytes("draft.pdf", draft);
Each call returns a new byte[] that is larger than the input, because the stamp or watermark is added to every page. AddTextStamp also accepts optional alignment, font size, and font name arguments, and AddWatermark accepts optional font size, rotation, and opacity arguments.
Supported Formats
| Format | Extension | Read | Write |
|---|---|---|---|
| ✓ | ✓ | ||
| TIFF | .tiff | ✓ | ✓ |
| JPEG | .jpg | ✓ | ✓ |
| BMP | .bmp | ✓ | ✓ |
| GIF | .gif | — | ✓ |
Open Source & Licensing
Aspose.PDF FOSS for .NET is released under the MIT License, which permits commercial use. The source is available at github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-.NET.