Skip to content

PDFStream.NET 1.0.0-rc.1: silent PDF printing for .NET - #1

Merged
glenntosco merged 52 commits into
mainfrom
feat/v1-library
Nov 21, 2026
Merged

glenntosco merged 52 commits into
mainfrom
feat/v1-library

Conversation

@glenntosco

@glenntosco glenntosco commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

PDFStream.NET 1.0.0-rc.1: silent PDF printing for .NET

A free, MIT-licensed .NET library that prints a PDF to a Windows printer with no dialog, no Adobe Reader and no licence key. PDFium renders the pages; the Windows print system sends them. Package, assembly and namespace are all PDFStream.NET (using PDFStream.NET;).

Release

This branch prepares the first release, 1.0.0-rc.1 (a prerelease; 1.0.0 follows once the remaining release-checklist rows are verified). Install with dotnet add package PDFStream.NET --prerelease. It is not published on nuget.org yet; the owner publishes it after this PR is merged.

What this branch adds

  • PdfPrinter.Print(path | Stream | byte[], PrintOptions, CancellationToken) returning a PrintResult (status, plain-language message, pages printed). It does not throw managed exceptions for bad input or printer problems.
  • Options: page ranges, copies, duplex, colour (bool?, null keeps the printer's setting), scaling, paper source, password, print-to-file.
  • Pre-flight printer checks (paused, "Use Printer Offline", not available, pending deletion, stopped spooler) so a held job is not reported as printed.
  • Filled-in PDF form fields print (see limits below).
  • Double-click PDFStream.NET.TestPrint sample (dry run by default), usage guides, troubleshooting, SECURITY.md, CI workflow, release checklist.
  • Targets net8.0-windows and net10.0-windows; PDFium comes from the bblanchon.PDFium.Win32 dependency.

Verified

  • Full suite on the latest commit: 477/477 (net10) and 452/452 (net8), x64, none skipped. The form, engine and real-print classes also pass on x86 (run on the previous commit; the commits after it change docs, comments and one test).
  • Real prints to Microsoft Print to PDF are checked for page count and non-blank output.
  • A throwaway app using the package from a local feed printed 2 pages on win-x64 and win-x86.

Not verified yet (do not merge on the assumption these work)

  • The CI run for the release commits is in progress on this PR; an earlier CI run on this branch passed.
  • arm64, Windows service, scheduled task, IIS and physical/duplex printers: every manual row in docs/release-checklist.md is "Not run".
  • Microsoft documents System.Drawing.Printing as unsupported in Windows services. Service printing is unproven.

Known limits (documented in docs/usage.md, docs/troubleshooting.md, SECURITY.md)

  • Form pages: if three or more form pages share one indirect /Contents array, later pages can also print the fields of earlier pages (status Ok). Flatten such PDFs first. A test pins this behaviour.
  • A crafted PDF with inline inherited values can grow memory by about 600 MB (measured: 1.2 MB PDF, 100 form pages). Print PDFs you do not trust in a separate worker process.
  • Form printing uses an Experimental PDFium function (FPDF_ImportPagesByIndex), tested only on PDFium 160.0.8165.
  • PDFium runs in-process: a native fault from a hostile PDF ends the process.

Notes

  • The repository history was rebuilt before this PR so it contains only the final design document, not earlier drafts. About 650 KB of the diff is third-party licence text and tests.

Scaffold the solution (library and xUnit v3 tests, net8.0-windows and
net10.0-windows) and add the internal PDF engine seam with a PDFium
implementation.

- PDFium 160.0.8165 from bblanchon.PDFium.Win32 (win-x64, win-x86,
  win-arm64), called through our own cdecl P/Invoke declarations.
  PDFiumCore and its fork were rejected: no FPDF_RenderPage binding.
- One process-wide lock around every PDFium call; documents own their
  native buffer through a SafeHandle.
- Load statuses tell a missing password from a wrong one; owner-only
  PDFs open without a password.
- Test fixtures are built by PDFsharp pinned to 6.2.4 (MIT; later
  versions are AGPL).
- THIRD-PARTY-NOTICES.md lists PDFium and every library compiled into
  it, with full licence texts.
Public Print overloads for a path, a stream and a byte array: options, load, page range, printer settings, job, with every failure returned as a result. Also: blank custom result messages fall back to the standard text, reversed page ranges with overflowing numbers are InvalidPageRange, and the spooler, too-large page and withdrawn-job texts are reworded.
Seven tests print through Microsoft Print to PDF into a temporary file under a 60 second limit, re-open the output with the library's own engine and check page count and non-blank pages, including a check that the vector path was used. Adds docs/release-checklist.md with the manual checks and a record row per check.
The package now carries LICENSE, THIRD-PARTY-NOTICES.md and the README (as
the nuget.org package page), plus tags and the project and repository
address. Authors, copyright and the MIT licence expression were already set
in Directory.Build.props. No SourceLink or symbol package.

pdfium.dll stays a NuGet dependency (bblanchon.PDFium.Win32) rather than
being copied into this package: a separate consumer app built and published
for win-x64, win-x86 and win-arm64 on net8.0-windows and net10.0-windows got
the right-architecture pdfium.dll next to its exe every time, and the x64
and x86 builds printed for real.

LangVersion is pinned to 12.0 instead of "latest": C# 12 is the newest
version the .NET 8 SDK supports, and the .NET 10 SDK builds it too.

THIRD-PARTY-NOTICES.md now states what was checked for the x86 and arm64
PDFium binaries: identical licence files, VERSION and build settings apart
from target_cpu, and binaries byte for byte equal to the NuGet package's.
On every push and pull request: install the .NET 8 and 10 SDKs, build,
run the tests for net8.0-windows and net10.0-windows through Microsoft
Testing Platform from the repository root, pack and check the NuGet
package, and publish the test-print sample as one self-contained win-x64
exe. Two report-only steps show whether Microsoft Print to PDF exists on
the runner and list every skipped test with its reason, so tests that skip
for lack of the printer are visible. Telemetry of the .NET CLI and the
Testing Platform is switched off. Artifacts only: nothing is published and
no secrets are used.
README gets real install and usage sections and an honest status (1.0
release candidate, manual release checklist not complete, not on NuGet yet,
images in 1.1). New docs/usage.md (every option, every status with its exact
message, PagesPrinted, copies, passwords, printing to a file, threads),
docs/services-and-iis.md (the account must see the printer, IIS app pools,
32/64-bit, concurrency) and docs/troubleshooting.md organised by message.
CONTRIBUTING.md documents the build and test commands and their Testing
Platform quirks.

The XML docs of PdfPrinter now describe concurrency accurately (the lock is
held per engine call, so jobs interleave at page level) and
PrintOptions.OutputFile warns that Print to PDF finishes the file after
Print returns. The design spec records the settled PagesPrinted and
printer-state rules and the NuGet ID check; the release checklist records
the net8.0-windows real-print runs.
The README and the services guide say that printing from a Windows service,
a scheduled task and IIS are on the release checklist, but the checklist had
no IIS row. It now has one (an ASP.NET Core app printing to a printer the app
pool identity can see), not run. The README no longer lists paper trays among
the unverified checklist items, because the checklist has no tray row.
PDFium's two page-drawing calls never draw form-field widgets, so a filled-in
form printed blank while the result said Ok. The first time a page with widget
annotations is drawn, the engine now shows it to a form-fill environment (which
builds missing appearances, and rebuilds them when the form asks for it with
NeedAppearances), pins the page's visible box on the page (flattening otherwise
turns an inherited MediaBox into US Letter), flattens it with FLAT_PRINT in its
private copy of the document and loads the page again. Both print paths then
draw the fields, the device-context path stays vector, fields without the Print
flag stay off the paper, and pages without widgets are untouched.

The document handle owns the form environment and its FPDF_FORMFILLINFO block
and releases environment, document, then the native blocks. A page that cannot
be prepared is drawn as before, so preparing never fails a print.

Tests: hand-written form fixtures (filled text field, ticked checkbox,
non-printing field, NeedAppearances, no /AcroForm, inherited attributes, crop
box, /Rotate 90, ordinary annotations with and without an appearance), pixel
checks on both paths against a raw PDFium reference, exact-pixel regression for
form-less pages, failing-flatten seam, and a real print to Microsoft Print to PDF.
Docs: form fields and the XFA limitation in usage.md and troubleshooting.md.
PrintOptions.Color becomes bool? with default null, which leaves the printer's
colour setting untouched; true and false still force colour or black and white.
A plain bool defaulting to true forced colour on every printer and would have
frozen that choice into the 1.0 API (ruling R19).

PrinterLocator only sets DefaultPageSettings.Color when a value is given; its
Apply step becomes internal so the tests can run it on real printer settings.
Tests: leaving Color out keeps mono settings mono and returns the driver's own
default; false forces black and white; true forces colour. The usage guide and
the design notes' API sketch and first-user defaults say the same.
The installed-printer list is read before the queue check, and with the Print
Spooler stopped that read throws or returns an empty list, so users got the
generic "printer unavailable" or "printer not found" instead of the spooler
message the docs promise.

A list read that fails with RPC_S_SERVER_UNAVAILABLE (1722, directly, wrapped,
or as its HRESULT) now gives the spooler message. Any other failure, and a named
printer that is not in the list, asks the status probe whether the local
spooler answers: OpenPrinter with no name opens the local print server, needs
no printer, never goes over the network and adds no package. Only a 1722 answer
counts as stopped; a genuinely missing printer with a running spooler stays
PrinterNotFound, and a check that throws counts as running.

Tests: fake catalogs that throw Win32Exception(1722), a wrapped 1722 and other
errors, not-found with the spooler stopped and running, and the real check on
this machine. Troubleshooting says what is detected, what is not, and that a
really stopped spooler has not been tried.
PDFium runs in-process without a sandbox: a malformed or hostile PDF that hits
a native memory fault ends the whole process (a Windows service simply stops)
and .NET cannot catch it. The usage guide gains a "Security and limits" section
saying so, recommending a separate worker process for untrusted PDFs, and
explaining that the engine lock is held while a page is drawn (one hung driver
stalls every print in the process) and that cancellation is checked between
pages only. The services guide points at it.

The "never throws" wording in the PdfPrinter XML docs, the usage guide and the
README now says it never throws managed exceptions for bad input or printer
problems, and points at that section.

SECURITY.md: report privately through GitHub's private vulnerability reporting
on this repository, supported versions, and PDFium fixes arriving through
updates of the bblanchon.PDFium.Win32 dependency.
The CI sample is one self-contained exe that bundles pdfium.dll and the .NET
runtime, but carried no licence notices. The sample project now copies LICENSE
and THIRD-PARTY-NOTICES.md, linked from the repository root, into its build and
publish output, excluded from the single-file bundle so they sit next to the exe.

THIRD-PARTY-NOTICES.md says that the self-contained sample also carries the
.NET runtime (Microsoft.NETCore.App.Runtime.win-x64, MIT; its own third-party
notices apply, and its licence text is the same as the System.Drawing.Common
one already reproduced) and that any application that redistributes
pdfium.dll must carry the PDFium section of the notices. The README sentence
about the sample says the same, and no longer claims it runs on a machine with
nothing installed: it is win-x64 only, unsigned (SmartScreen may warn) and
extracts pdfium.dll to a temporary folder on first run.

Checked by publishing the sample as ci.yml does into a folder outside the
repository (exe, LICENSE and THIRD-PARTY-NOTICES.md, both identical to the
repository root) and by running the CI package check on a fresh pack.
The job gets timeout-minutes: 30, so a stuck print or test run fails instead of
holding a runner for the six-hour default, and a concurrency group per workflow
and ref cancels a run that a newer push to the same ref has superseded.
Permissions stay contents: read; nothing is published and no secrets are used.
…ssages

PrintResult and the usage guide said a failed job "is withdrawn" from the print
queue, while the message itself rightly says it "may have been withdrawn": the
print system, not the library, removes an aborted job. Both now say "may have
been withdrawn" and suggest checking the queue.

PagesPrinted's XML docs now say it counts pages times copies when the library
repeats the document in software, and pages only when the driver makes the
copies.

PrintResult.Message no longer claims to be safe to show to any end user: an
UnknownError message may end with the text of an internal exception, so the docs
(PrintResult, usage guide, README example) say to log it rather than show it in a
public web page.
The .NET runtime pack's LICENSE.TXT and System.Drawing.Common's are the same
licence text but not the same bytes (they differ in line endings), so the
notices no longer say "byte for byte". SECURITY.md no longer points at a PDFium
bug-tracker link that was not checked.
Measured while checking the report: PDFium's form engine builds the missing
appearance of a field that has a value but no stored appearance even when the
form does not say /NeedAppearances, so after flattening the value prints. A new
fixture option and a test on both print paths pin this, and the usage guide's
form-field section now says so instead of implying only NeedAppearances forms
get appearances built.
Flattening a form page in place gave a page that inherits its /Resources
from the page tree an empty /Resources of its own, which hid the inherited
fonts, images and XObjects: that content vanished from the paper while the
print still reported Ok.

A page with form fields is now copied to the end of PDFStream's in-memory
document with FPDF_ImportPagesByIndex (same document as source and
destination), which writes the inherited Resources, MediaBox, CropBox and
Rotate onto the copy. The fields are flattened into the copy, and the copy
is drawn in place of the page. The page count stays as read at load time,
so the copy is never reachable by index. Any failure, or a copy whose size
differs from the page, draws the page as it is.

FPDF_FFLDraw was not used: it draws only into a bitmap, so the
device-context path would no longer be vector.

Tests: marks drawn through inherited resources (a form XObject, an image and
a Type3 glyph) on both render paths, own-resource and form-less regressions,
a two-page document whose form page is second, one document drawn from two
threads at once on both paths, and copy failure, copy size and call-count
seams.
usage.md, the design notes and the CHANGELOG say that a page with fields is
copied (with everything it inherits) and the fields are flattened into the
copy, and what that costs. troubleshooting.md says what a page with all its
fields blank means.
ci.yml said seven real-print tests; there are eight since the form-field
print test. The release checklist rows and the CHANGELOG test counts now
come from the runs of 2026-11-21 (x64 and x86, both frameworks). Initials
stay blank for the maintainer.
The copy of a form page holds its own copies of the objects the page uses,
so optional-content groups become new objects that the catalog's layer
settings do not name: a layer the PDF switches off showed on the copy
(1656 dark pixels in a switched-off square on 513c191).

The copy is now used only if, before flattening, it draws exactly the same
pixels as the page (both rendered for printing at up to 72 dpi, at most one
million pixels, compared byte for byte). Otherwise the fields are flattened
into the page itself, as at b0405bf, which keeps its layers right. A page
with fields, switched-off layers and inherited /Resources remains the one
unsolved combination (documented).

Tests: a hidden-layer variant and test on both paths, an upper bound on the
ink the fields may add (so extra ink such as a leaked layer fails), and a
password-protected form PDF on both paths.
usage.md, troubleshooting.md, the design notes and the CHANGELOG say that the
copy is used only when it looks exactly like the page, that pages with
switched-off layers have their fields drawn into the page itself, and which
combination of features can still lose content, with a workaround. The
CHANGELOG's package and sample checks keep their 2026-11-20 date.
The CHANGELOG and the release checklist now carry the counts of the runs of
2026-11-21 after the layer check: 389 tests on net10.0-windows and 364 on
net8.0-windows, on x64 and x86, real-print tests 8 of 8.
The pixel budget of the copy-versus-page comparison capped only the area,
so a very wide and thin page (a hostile or damaged MediaBox) still got a
huge width: a 100000000 x 1 point form page was compared at 10000000 x 1
pixels (two 40 MB arrays), and wider pages could overflow the int array
size. NaN, infinite, zero and negative sizes were not rejected.

The comparison size is now computed in double from a size checked to be
finite and positive; each side is clamped to 4096 pixels before the area is
fitted to one million pixels, and the result is rounded down. A page so
small or so long and thin that a side would be under one pixel is not
compared. The render computes its buffer length in long and refuses
anything over 4 MB. Any failure in the comparison now means "could not
verify" and takes the existing fallback (fields flattened into the page
itself); it never throws and the page always prints.

Tests: the size computation for ordinary, very large, long and thin,
float.MaxValue and invalid sizes, and form pages of extreme sizes printed
through a print job, with every comparison render size checked against the
budget through a per-document test hook.
The owner decided the package is named PDFStream.net, the only name it
shows on nuget.org: PackageId and Title are PDFStream.net. The assembly
(PDFStream.dll) and the namespace (PDFStream) keep their name, as a comment
next to PackageId and the README say.

README (the nuget.org page) names the product PDFStream.net and installs
with "dotnet add package PDFStream.net". usage.md, services-and-iis.md,
CONTRIBUTING.md (consumer check with PackageReference PDFStream.net),
SECURITY.md, THIRD-PARTY-NOTICES.md, the design notes (package id decision,
nuget.org shows no PDFStream.net package on 2026-11-21) and the CHANGELOG
follow. The CI package check now requires exactly one
PDFStream.net.<version>.nupkg, reads PDFStream.net.nuspec and checks the id
and title; the artifact is PDFStream.net-nuget-package.

Checked: a pack outside the repository gives PDFStream.net.1.0.0-preview.nupkg
with id and title PDFStream.net, the CI check passes on it and fails on a
package packed with the old id, and a separate win-x64 net10.0-windows app
restoring PDFStream.net from a local feed into an empty cache printed a page
to Microsoft Print to PDF with OutputFile.
The CHANGELOG and the release checklist carry the counts of the last runs
of 2026-11-21: 415 tests on net10.0-windows and 390 on net8.0-windows, on
x64 and x86, real-print tests 8 of 8. One 32-bit net10.0-windows run had a
Print to PDF write timeout in one real-print test and passed on the re-run;
both are recorded.
…DFStream.net

The assembly is now PDFStream.net.dll and the C# namespace PDFStream.net (sub-namespaces follow), so developers write "using PDFStream.net;". The projects, the test project, the test-print sample and the solution carry the same name. Public type names are unchanged.
The workflow builds, tests, packs and publishes from the renamed projects, and the package-content check now expects PDFStream.net.dll for both frameworks.
README, usage guide, troubleshooting, services guide, security policy, contributing guide, release checklist, third-party notices and the design doc now say PDFStream.net, show "using PDFStream.net;" and use the renamed project paths. The changelog records the rename and the checks run after it. The GitHub repository URLs are unchanged.
A copy whose annotations were lost (PDFium's page copy drops a whole /Annots
array when one entry is a damaged reference) passed the pixel check, because
that check draws without the fields, and was flattened with nothing to do, so
the fields came out blank while the print reported success. Every other copy
failure (copy refused or missing from pdfium.dll, size changed, copy flatten
failed) also ended in blank fields.

A copy is now used only when it carries as many annotations as the page.
Any copy that cannot be used takes the same path as a copy that draws
differently: the fields are flattened into the page itself, as before the
copy existed. The page is drawn as it is only when that fails as well.
Each page with form fields was copied by its own FPDF_ImportPagesByIndex
call, and every call cloned everything the page can reach again, including
a /Resources dictionary that all pages share and the images in it. Drawing
40 form pages that share 8 MB of images grew private memory by about
290 MB (x64), and a 32-bit process printing 500 of them did not finish.

The first time a page with fields is drawn, the pages about to be drawn
(the pages of the print job, or every page) are scanned once for fields,
their missing appearances are built, and all pages with fields are copied
in one call, so what they share is cloned once. The same 40 pages now grow
memory by 14 to 17 MB, and the 500-page job prints in a 32-bit process.

The copy is made at most once per document and only for a PDF of at most
64 MB (the copy budget). A PDF over the budget, a page outside the planned
pages, or a failed copy takes the fallback of flattening the fields into
the page itself. Print jobs pass their page list to the document through
the new IPdfDocument.PlanToDraw, so only the printed pages are scanned.
Nothing recorded whether a form page printed from its copy, had its fields
flattened into itself, or was drawn as it is, so a PDFium update that made
every copy fail would only have shown as missing ink on some pages.

PdfiumDocument now reports, through an internal hook that is null in
production, how each page was prepared the first time it was drawn and,
for a form page that did not print from its copy, why (over the copy
budget, not planned, copy failed, size differs, annotations lost, draws
differently, flatten failed). Tests assert the branch for the key cases:
a plain form page, inherited resources, a damaged annotation reference, a
hidden layer, a missing or refusing copy function, a copy of another size,
a copy that cannot be flattened, nothing flattenable, the copy budget on
one and on many pages, pages sharing a content array, an unplanned page,
and every page of the 500-page job.
On a busy machine the real-print tests once timed out after 30 seconds
waiting for Microsoft Print to PDF to finish writing its file, in a test
without form fields. The wait is now 120 seconds, and a timeout names the
queue's status and attribute bits and the number of jobs in it, so a stuck
queue can be told apart from a slow one.
The experimental PDFium function form printing relies on, and what happens
without it, is now in SECURITY.md and the form section of usage.md. The
usage, troubleshooting and design docs describe the one copy of the pages
with fields, the 64 MB copy budget, the wider fallback to drawing fields
into the page itself, and a crafted PDF's memory use. The csproj comment,
CHANGELOG and README say exactly which package checks ran under which id
and when, and carry the test counts of the latest runs.
The cost bullet in usage.md now limits "at most about the size of the PDF"
to objects the pages share and points to the inline-value exception, the
memory bullet keeps only the measured case, the README no longer implies
that the printed form field was inspected, and the release checklist rows
carry the results of the latest full-suite runs.
…own limits

Three or more form pages that share one indirect /Contents array can also print the fields of earlier pages. The comments and the design doc no longer claim the pixel comparison catches this. Added to usage, troubleshooting, SECURITY (also the inline-inherited-values memory limit), CHANGELOG. Also: the first form page's longer uninterruptible engine call, a wrapped long line, README says what was last run and when, and a comment on the accepted reload-failure case.
Characterization test: with four form pages sharing one indirect /Contents array, page 3 also draws page 2's field (and page 4 pages 2 and 3), status Ok. A future fix must update this test and the docs.
@glenntosco

Copy link
Copy Markdown
Contributor Author

CI result on this repository (windows-latest): build, tests, package check and sample publish all passed.

  • net8.0-windows: 452 total, 451 passed, 1 skipped, 0 failed.
  • net10.0-windows: 477 total, 476 passed, 1 skipped, 0 failed.
  • The runner has Microsoft Print to PDF and a running Print Spooler, so the facade, form and real-print tests ran. The one skipped test needs the Microsoft XPS Document Writer, which this runner does not have.
  • The package was built as PDFStream.net.1.0.0-preview.nupkg and passed the package-content check.

Not covered by CI (see "Not verified yet" above): x86 and arm64 runs, a Windows service, scheduled task, IIS, physical and duplex printers.

@glenntosco glenntosco changed the title PDFStream.net 1.0 candidate: silent PDF printing for .NET PDFStream.net 1.0.0-rc.1: silent PDF printing for .NET Nov 21, 2026
…nd CI

The package id and title, the assembly (PDFStream.NET.dll), the root namespace, every C# namespace, the
folders, project files and solution, InternalsVisibleTo, the sample and the CI workflow now spell the name
PDFStream.NET, like SheetStream.NET. NuGet keeps the capitalisation of the first publish for good, so this
is settled before the first release. The CI package check now compares the package id, the manifest name, the
assembly file names and the repository URL case-sensitively, so a lowercase spelling cannot pass it. The
repository URL is https://github.com/P4Software/PDFStream.NET.
README, CONTRIBUTING, SECURITY, THIRD-PARTY-NOTICES and the docs now say PDFStream.NET and use the repository
address https://github.com/P4Software/PDFStream.NET. The CHANGELOG records the name decision under 1.0.0-rc.1
and keeps the earlier verification runs as a true record of the spelling used at the time (lowercase), with
the run made under the final name added. The README, the design document and the project comments no longer
tell the history of the spelling as if the earlier runs had used the final name.
@glenntosco glenntosco changed the title PDFStream.net 1.0.0-rc.1: silent PDF printing for .NET PDFStream.NET 1.0.0-rc.1: silent PDF printing for .NET Nov 21, 2026
@glenntosco
glenntosco merged commit e8cf1df into main Nov 21, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant