Migrating from PDFsharp

This maps the PDFsharp calls most programs use to their OnePDF equivalents for opening, reading, changing, saving and page operations. It is based on PDFsharp's public documentation (docs.pdfsharp.net, version 6.x) and its published API reference; check those for details of its behavior. OnePDF's API is smaller in some places and larger in others, so this is a map, not a drop-in replacement.

What OnePDF does differently

PDFsharp is first of all a library for creating PDF files: you draw with XGraphics, use XFont, XImage and MigraDoc. OnePDF reads, extracts, interprets into a device and edits existing files. It also draws text, images and shapes onto new or existing pages (content creation), and the separate package RecursiveAI.OnePdf.Layout is a layout engine in MigraDoc's place, with shaped text (see layout).

The differences that matter first

Opening

A wrong or missing password throws PdfPasswordException. PDFsharp's documentation notes that a file with an owner password cannot be opened for modification with the user password (open it in Import mode instead and copy the pages). OnePDF has no such split: either password opens the file, and doc.Permissions reports the flags without enforcing them. Honouring them is up to your application.

// PDFsharp: pages of an owner-protected file, opened with the user password
var import = PdfReader.Open(path, userPassword, PdfDocumentOpenMode.Import);
var output = new PdfDocument();
foreach (PdfPage page in import.Pages)
    output.AddPage(page);
output.Save("copy.pdf");
 
// OnePDF
using var import = PdfDocument.Open(path, new PdfOpenOptions { Password = userPassword });
using var output = PdfDocument.CreateEmpty();
output.ImportPages(import);
output.Save("copy.pdf");

Pages

OnePDF's page objects are read views; operations are methods of the document, and doc.Pages is rebuilt after each one (take pages again after calling an operation). Details of what each operation does to bookmarks, links, forms and the rest are in page-operations.md.

Merge

// PDFsharp
var output = new PdfDocument();
foreach (string file in files)
{
    var input = PdfReader.Open(file, PdfDocumentOpenMode.Import);
    foreach (PdfPage page in input.Pages)
        output.AddPage(page);
}
output.Save("merged.pdf");
 
// OnePDF
var inputs = files.Select(f => PdfDocument.Open(f)).ToList();
using (PdfDocument merged = PdfDocument.Merge(inputs))
{
    merged.SetInfo("Title", "Merged");
    merged.Save("merged.pdf");
}
foreach (var d in inputs) d.Dispose();

Merge carries more than the pages: bookmarks, named destinations the links use, form fields (with clashing names renamed), optional content, page labels and the structure tree of tagged files. PDFsharp's documentation says it does not write object streams, so files that contain them can grow when saved; OnePDF reads and writes them (PdfSaveOptions.UseObjectStreams).

Split

// PDFsharp: one file per page
for (int i = 0; i < input.PageCount; i++)
{
    var output = new PdfDocument();
    output.AddPage(input.Pages[i]);
    output.Save($"page-{i + 1}.pdf");
}
 
// OnePDF
IReadOnlyList<PdfDocument> parts = PdfDocument.Split(input, pagesPerPart: 1);
for (int i = 0; i < parts.Count; i++)
{
    parts[i].Save($"page-{i + 1}.pdf");
    parts[i].Dispose();
}
// or by ranges: PdfDocument.Split(input, [new PdfPageRange(0, 3), new PdfPageRange(3, 5)])

Each part holds the objects its pages reach. A resource dictionary shared by every page of the source (typical of slide decks) is copied whole into each part.

Metadata

Saving

An encrypted source never needs special handling for page operations: it is read with its password, and what you write is plain unless you ask for encryption.

Forms

PDFsharp's documentation describes limited AcroForm support. OnePDF reads field values and kinds (doc.Form, FindField), merges and renames fields when pages are imported, and draws fields with missing appearances (PdfAnnotation.GenerateAppearance). It also fills, resets and flattens fields with typed validation (forms).

Beyond what PDFsharp does

• Text extraction (PDFsharp's FAQ says it has no high-level text extraction): doc.ExtractText(); see the PdfPig guide for the API.
• Interpreting pages into a drawing device or a recorded display list (page.Interpret), which a renderer can replay.
• Repair of broken files and limits for hostile ones.

Things that behave differently and can change your output

• Imported pages are copied, not shared: a page imported twice becomes two pages with their own annotations, and nothing refers back to the source document.
• Inherited page attributes (/Resources, /MediaBox, /CropBox, /Rotate) are written into the imported page.
• ImportPages copies pages from a document you have open; there is no separate "import mode" document type, and the source is never changed.
• Deleting a page repairs bookmarks, links and destinations instead of leaving them dangling, and drops the structure tree of a tagged file (it would keep the deleted content reachable).