Migrating to FreePDF 7
FreePDF 7 follows the reviewed MIT PDFsharp/MigraDoc v7 Preview 1 API. It is a
major-version upgrade from 6.2.4. Keeping PdfSharp/MigraDoc namespaces and
assembly names does not make existing v6 binaries compatible.
Packages and rebuilding
Replace PDFsharp with io7.FreePDF, and PDFsharp-MigraDoc with
io7.FreePDF.Layout. The latter depends on the former. Windows applications on
the GDI or WPF builds replace PDFsharp-GDI/PDFsharp-MigraDoc-GDI with
io7.FreePDF.Gdi/io7.FreePDF.Layout.Gdi, and PDFsharp-WPF/PDFsharp-MigraDoc-WPF
with io7.FreePDF.Wpf/io7.FreePDF.Layout.Wpf (since 7.1). FreePDF 7.0.0 named
the layout package io7.FreePDF.MigraDoc; it was renamed before the first
NuGet release. Remove upstream
packages from the entire dependency graph, including transitive references,
and rebuild consumers. Do not load both implementations in one application:
they intentionally use the same assembly names.
Since 7.0.1, FreePDF assemblies are strong-named with io7's key (public key
token 77af05c50284aa70). 7.0.0 used empira's key (f94615aa0424f9eb), so
rebuild anything compiled against 7.0.0 and do not mix the two versions.
The packages contain the core, barcodes, charts, cryptography, document model,
PDF renderer and RTF renderer for their variant. Upstream's Quality, Snippets and
WPFonts helper assemblies are not shipped. The GDI and WPF packages keep upstream's
assembly names (PdfSharp-gdi, MigraDoc.Rendering-wpf and so on), so binding
redirects and reflection that name them keep working. The portable packages find
installed fonts without a font resolver; see Fonts. Test fixtures' fonts
are not product dependencies.
Common source changes inherited from v7
| v6 assumption | v7 migration |
|---|---|
Metadata dates and DocumentRenderer.PrintDate are DateTime |
Use nullable DateTimeOffset; choose an explicit offset when converting an old value. |
PdfDocument is a PdfObject and ICloneable |
Treat it as the document owner; rework casts, cloning and helpers that require the old base class. |
PdfDocument.Internals returns PdfInternals |
Its type is PdfDocumentInternals; recompile and check explicit type declarations. |
Legacy PdfSharp.Pdf.AcroForms types are the form model |
v7 exposes PdfForm through document.Catalog.GetAcroForm() or GetOrCreateAcroForm(). Since 7.1 its fields are found by name and filled through typed members, and document.Flatten() draws them into the pages; see Filling forms. |
| A one-argument dictionary getter has the old binary signature | Several getters gained optional arguments. Source calls can still compile while precompiled binaries require rebuilding. |
| Font, glyph, image and content-parser implementation types are unchanged | Review explicit references against the API report; Imaging/OpenType now have separate assemblies. |
| Standard-target helper types are stable | PdfSharp.SystemStringExtensions is removed in v7's Standard build; review direct calls to inherited helper types as well as the main PDF APIs. |
For example, document.Info.CreationDate = DateTimeOffset.UtcNow expresses a
known instant. Do not silently interpret a legacy DateTimeKind.Unspecified
value as UTC; preserve the application's intended timezone.
What real 6.2.4 applications hit
FreePDF compiled 26 public projects that use PDFsharp or PDFsharp-MigraDoc 6.2.4 against FreePDF 7 (method and results: consumer survey). 23 compiled with no new error. The breaks in the other three, and what to do:
| 6.2.4 code | With FreePDF |
|---|---|
elements.GetDateTime(key, DateTime default) returning DateTime |
Compiles again since 7.1: the overload returns the stored date as UTC, as 6.2.4 did. GetDateTime(key) returns DateTimeOffset?. |
new CString(), new CInteger(), new CReal(), or a subclass filled with an object initializer |
Compiles again since 7.1. |
document.SetPdfA() |
Compiles again since 7.1 and declares PDF/A-1b, which FreePDF's release checks validate. 6.2.4 declared PDF/A-1a without creating the tagged structure that level requires. Call it before adding pages; FreePDF refuses PDF/A settings after content exists. |
byte[] bytes = sequence.ToContent() |
ToContent() returns the content stream as a string with one character per byte. Use PdfSharp.Pdf.Internal.PdfEncoders.RawEncoding.GetBytes(sequence.ToContent()), as FreePDF does internally. |
DateTime created = document.Info.CreationDate |
Read document.Info.CreationDate?.UtcDateTime (or LocalDateTime). Assigning a DateTime still compiles. |
using PdfSharp.Snippets;, PdfSharp.Quality, PdfSharp.WPFonts |
These upstream helper assemblies are not shipped. Remove unused usings. PdfSharp.WPFonts embeds Microsoft's Segoe WP fonts, which FreePDF has no licence to redistribute: give your IFontResolver font files you are licensed to embed. |
Legacy forms (PdfSharp.Pdf.AcroForms, document.AcroForm.Fields["name"]) did not
appear in the survey, but some applications fill forms this way; see below.
Fonts
PDFsharp 6.2.4's portable build needs an IFontResolver before it can draw text,
on Windows as on Linux, macOS and in containers. FreePDF's portable packages use the
fonts installed on the machine when no GlobalFontSettings.FontResolver is set:
- FreePDF asks the Windows font table (
UseWindowsFontsUnderWindows,UseWindowsFontsUnderWsl2) and yourFallbackFontResolverfirst, then the folders added withGlobalFontSettings.AddFontDirectory, then the system's font folders (WindowsFontsfolders;~/.local/share/fonts,~/.fonts,/usr/local/share/fonts,/usr/share/fonts; macOSLibrary/Fontsfolders). - A common family that is not installed is replaced, and a warning is logged:
Arial and Helvetica by Liberation Sans or Arimo, Times New Roman by Liberation
Serif or Tinos, Courier New by Liberation Mono or Cousine, Calibri by Carlito,
Cambria by Caladea. These have the same widths, so line breaks match. Without
them FreePDF uses DejaVu or Noto fonts of the same kind, whose widths differ.
In a Debian or Ubuntu container,
apt-get install fonts-liberationprovides the first group. - Only TrueType fonts that FreePDF can embed are used: single-font
.ttfand.otffiles with TrueType outlines whose licence bits allow embedding a subset. Font collections (.ttc) and CFF.otffonts are skipped.
An application with its own IFontResolver behaves exactly as before. Set
GlobalFontSettings.UseSystemFonts = false before the first font is used to
require a font resolver as 6.2.4 did. Output depends on the fonts installed, so a
font resolver remains the way to identical output on every machine.
Filling forms
FreePDF carries the v7 form model (PdfSharp.Pdf.Forms). Since 7.1 a 6.2.4
form-filling program moves over with renames:
6.2.4 (PdfSharp.Pdf.AcroForms) |
FreePDF 7.1 (PdfSharp.Pdf.Forms) |
|---|---|
document.AcroForm |
document.Catalog.GetAcroForm() (null when the file has no form) |
form.Fields["name"], form.Fields["address.city"] |
The same; null when there is no such field. Also TryGetField and Count. |
PdfTextField: Text = "Ada" or Value = new PdfString("Ada") |
PdfFormTextField.Text = "Ada" |
PdfCheckBoxField.Checked |
PdfFormCheckBoxField.Checked |
PdfRadioButtonField.SelectedIndex |
PdfFormRadioButtonField.SelectedIndex, SelectedValue, Options |
PdfComboBoxField / PdfListBoxField: SelectedIndex |
PdfFormComboBoxField / PdfFormListBoxField: SelectedIndex, SelectedValue (export value), Options, ExportValues |
field.ReadOnly |
field.IsReadOnly |
form.Elements.SetBoolean("/NeedAppearances", true) |
Not needed: FreePDF draws the filled appearance. form.NeedAppearances remains for special cases. |
document.Flatten() (made the top-level fields read-only) |
document.Flatten() draws every visible field into its page and removes the form, so the values can no longer be edited or read as form data. Read values you still need before flattening. 7.0 threw InvalidOperationException here. |
FreePDF draws text and choice fields with the font, size, colour and alignment
of the field's default appearance (/DA, /Q) and the widget's border and
background. Check boxes and radio buttons switch to the on and off appearances
the form already contains, under whatever on-state name it uses. Limits:
- Text is written in the WinAnsi encoding of the form's font. Text outside it (for example Japanese) is left to the viewer through NeedAppearances; a PDF/A document refuses such a value, because PDF/A does not allow NeedAppearances.
- Centred and right-aligned text, line wrapping and automatic font sizes use the
font's
/Widths. Since 7.1.1, the twelve Latin standard fonts (and Arial, Times New Roman and Courier New) use Adobe's metrics when they list no widths; other fonts without widths use an estimate. - Saving a document opened in
Modifymode rewrites the file, which invalidates its signatures. Open a signed form withPdfDocumentOpenMode.Appendto fill it in; see Signed documents. Flatten()draws each visible widget's appearance where the widget sits and removes the form and its widgets; other annotations stay. Text and choice fields without an up-to-date appearance (for example a/Vwritten directly with NeedAppearances set) get one first. If a value cannot be drawn, such as Japanese text in a WinAnsi font,Flatten()throws and changes nothing.
Merging and splitting
6.2.4's way of merging, output.AddPage(input.Pages[i]) on documents opened with
PdfDocumentOpenMode.Import, works as it did. It copies page content and
annotations, but not the form, so the fields arrive as widgets that are no longer
a form; not the bookmarks; and a link to another page leads to a hidden copy of
that page, which also comes along when you split. Since 7.3, AppendPages and
ExtractPages keep all three:
| 6.2.4 | FreePDF 7.3 |
|---|---|
foreach (var page in input.Pages) output.AddPage(page); |
output.AppendPages(input); or output.AppendPages(input, startIndex, pageCount); |
A new document plus AddPage(input.Pages[i]) |
using var part = input.ExtractPages(i, 1); |
- Form fields with a widget on a copied page join the document's form and can be
filled or flattened, with the font, size and colour their own form gave them
(a form font whose name the document already uses for another font is added
under a new name). A field whose name is already used is renamed
name_2,name_3and so on;AppendPagesreturns the new names inRenamedFields. To merge filled forms into a file that cannot be edited, callFlatten()on the result. - Links, the GoTo actions of buttons, and bookmarks lead to the copied pages. Named destinations are written as the explicit destinations they name. A link or action that leads to a page that was not copied is removed; so is such a bookmark, unless it holds bookmarks that were kept. Links and bookmarks that lead elsewhere, such as a web address, are kept.
- Append each source in one call. Pages appended in separate calls are separate copies: a field with widgets in both becomes two fields, and links and bookmarks between them are removed.
- Signatures are copied as they are, but a signature cannot be valid in a new file; viewers report it as invalid. Sign the merged file.
- If copying fails on a damaged source, the document's pages, form and bookmarks are left as they were.
new PdfPageImportOptions { BookmarkTitle = "invoice.pdf" }puts the copied bookmarks under one bookmark that opens the first copied page;KeepBookmarks = falseleaves them out.- Fonts and images are shared between the copied pages and their annotations, and between repeated copies of the same source.
- Not carried: tags (the structure tree), page labels, optional content (layer) settings, XFA, named destinations as names, and fields without a widget on a copied page. JavaScript that refers to a renamed field by name is not updated.
- A PDF/UA document refuses copied pages, as it refuses
AddPage(page).
Signed documents
PDFsharp 6.2.4 always writes a new file, so saving a signed document after any
change breaks its signatures, and a signed document cannot be signed a second
time. Since 7.4, FreePDF has PdfDocumentOpenMode.Append for this:
using var document = PdfReader.Open("signed.pdf", PdfDocumentOpenMode.Append);
((PdfFormTextField)document.Catalog.GetAcroForm()!.Fields["name"]!).Text = "Ada Lovelace";
document.Save("signed-filled.pdf");
using var approved = PdfReader.Open("signed-filled.pdf", PdfDocumentOpenMode.Append);
DigitalSignatureHandler.ForDocument(approved, signer, options);
await approved.SaveAsync("approved.pdf");
To sign a form's empty signature field instead of adding a new one, name it (since 7.6):
DigitalSignatureHandler.ForDocument(approved, signer,
new DigitalSignatureOptions { FieldName = "Approval", Reason = "Approved" });
- Saving writes the original file byte for byte, then an incremental update with only the new and changed objects, their cross-reference section (a table or a stream, as the file uses) and a trailer that points back to the previous one. Object numbers and the page tree stay as they are in the file.
- The signatures in the file stay valid. A new signature covers the whole file, earlier signatures included.
- A signature in an existing field (
DigitalSignatureOptions.FieldName) is shown in that field's widget at its size, so leaveRectangleandPageIndexunset; the field keeps its name and flags, and the form gets no new field. A field lock (/Lock) is recorded in the signature (FieldMDP, as Acrobat and pyHanko record it), so validators lock its fields from then on. Required seed values (/SV) are checked: a required reason must be given asReason, or left empty where the field allows none (no reasons or a single "." listed), and requirements FreePDF cannot meet or check (a signing certificate, a digest method, a timestamp, a certification, revocation information, locking the document, a named appearance) makeForDocumentthrowNotSupportedException. Since 7.10, a required /SubFilter is checked against the signer's format (PdfSharpDefaultSigner.Format, orIDigitalSignerFormatfor a signer of your own), and a format the field does not list is refused the same way. A field that is already signed cannot be signed again, and one that an earlier signature locks is refused when saving. It works inModifymode too. - A save that would change more than the document's signatures permit throws
InvalidOperationExceptionbefore anything is written, and saving to a path leaves the file as it was. The message names the permission and the change. The document is then marked saved; open the file again to try a different change.- Signed signature fields cannot change, in any signed document: the field, the fields above it, its widget and everything they refer to (the signature, its lock, the appearance and its resources). They cannot be removed, renamed by moving them in the field tree, or moved to another page.
- Fields that a signature locks (FieldMDP, or the
/Lockof its signature field) are protected the same way. A/Lockwith/Palso limits later changes like a certification. - A certification signature (DocMDP, ISO 32000-1 12.8.2.2) with "no changes"
(P=1) permits only validation data (
PdfDocumentSecurityStore) and document time-stamps (PdfTimeStampSigner), as ISO 32000-2 12.8.2.2 allows since 7.10; before, it permitted no update at all. With "form filling and signing" (P=2) it permits filling in fields, adding signature fields and signing, and changing the document information; with P=3 also adding, changing and removing comments and other annotations. Page content, pages, bookmarks and other parts of the document cannot change under any level. - Without a certification, everything else can change, as before.
- Whether a validator accepts what you changed after a signature still depends on
the validator. Filling in fields and adding signatures are permitted changes for
an ordinary (approval) signature. Acrobat permits added comments and new visible
signature fields where the permissions allow them; pyHanko's default policy
reports any added comment, and after a certification it accepts only invisible
new signature fields (
DigitalSignatureOptions.Rectangleleft empty) and signing existing ones (DigitalSignatureOptions.FieldName). pyHanko accepts signing an existing field when the field is its own widget, as pyHanko and most tools make them; when its widget is a separate object, or it has several widgets or shares its appearance with another widget, pyHanko reports the earlier signatures as changed (its own signer refuses fields with several widgets and does not update a separate widget's appearance). After an ordinary signature, pyHanko also reports changes to pages, which no permission forbids and FreePDF saves; and after a signature that locks all fields, pyHanko counts signature fields added later as locked too, while FreePDF applies the lock to the fields the document had. - A document with no changes is saved as it was. Otherwise the document
information gets a new modification date (unless you set one) and FreePDF as
its producer, except under a P=1 certification, where it stays as it was. An update never adds a
/PageModeto the catalog (a full save makes a document with bookmarks open with them shown). Readingpage.Annotations,document.Outlines,document.ViewerPreferencesor a form field'sKidscreates them when the file has none, and saving writes that as a change, which a signed or certified document may refuse; read a field's kids withGetKids()instead. - An encrypted document keeps its encryption: the update's objects are encrypted
with the file's key (RC4 and AES-128/256 of the standard security handler), and
the original's passwords keep working. Open it with the owner password, or with
the user password and
PdfReaderOptions.AllowModifyWithoutOwnerPassword, as inModifymode; with that option, as inModifymode, the file's permission flags (printing, changing, commenting) are not enforced. The encryption, including its permissions, cannot be changed or removed inAppendmode, and an unencrypted document cannot be given a password. A changed save of a file that carries an integrity code over its encryption (PDF MAC, ISO/TS 32004; pyHanko adds one to AES-256 by default) is refused, because an update cannot extend the code. - Files whose cross-reference table names the wrong objects cannot be opened in
Appendmode; open those withModifyto save a new file. - Pages can be added, removed and moved, also when the page tree is nested (since 7.7). The update writes only the page tree nodes between the root and the pages that change: a page goes next to its neighbours in their node, preferring the node it was in, and a page at either end that has no such node goes into the root; a node left without pages is taken out of the tree. A page moved under another node keeps its media box, crop box and rotation, and a new page takes none from the node it goes into.
Repeatable API evidence
eng/Test-PublicApi.ps1 compares all eleven packaged assemblies for all four
target frameworks with hash-pinned MIT packages. Microsoft ApiCompat 10.0.100
also checks public parameter names. Any incompatible change from the published
MIT v7 Preview 1 contract fails the gate; there are no blanket suppressions.
Since 7.0.1, each comparison must also report exactly one CP0003 finding: the
public key token change from empira's f94615aa0424f9eb to io7's
77af05c50284aa70. Both tokens are pinned in the script, so a missing or
different identity change fails the gate as well.
The same audit produces v6.2.4 migration diagnostics as information, not a v6
compatibility promise. The initial net8.0 comparison reports 163 diagnostics;
one property can produce several diagnostics. See the full report in
research/api-6.2.4-to-7.0.0-net8.0.txt and CI artifacts for each target.
The legacy dictionary extension explicitly preserves the published method's nullable metadata across SDKs, including nullable dictionary values. Its compiler-generated extension marker is preserved as well.
Behaviour to verify in your application
Saving a document opened in Modify mode rewrites the file and does not
preserve existing digital signatures; open it in Append mode to keep them (see
Signed documents). Use a fresh document per concurrent operation; sharing a mutable document
between threads is unsupported. Retest pagination and font selection when
upgrading: reference output containing a known defect is not the correct output.
Documents name FreePDF, not PDFsharp, as their Producer and Creator (since
7.3.0; see the changelog). Code or tests that
recognise their own output by a Producer starting with "PDFsharp", or that compare
it with PdfSharpProductVersionInformation.Title, should expect "FreePDF".
The original installed-package workflows cover a multipage invoice, RTF, merge/stamp, attachments, AES-128/256, PDF/A-1b/2b/3b and SHA-256/384/512 signatures. They contain synthetic data and do not certify a customer's document.