Repository navigation
PDFStream.NET 1.0.0-rc.1: silent PDF printing for .NET - #1
Merged
Merged
Conversation
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.
Contributor
Author
|
CI result on this repository (windows-latest): build, tests, package check and sample publish all passed.
Not covered by CI (see "Not verified yet" above): x86 and arm64 runs, a Windows service, scheduled task, IIS, physical and duplex printers. |
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.0follows once the remaining release-checklist rows are verified). Install withdotnet 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 aPrintResult(status, plain-language message, pages printed). It does not throw managed exceptions for bad input or printer problems.bool?, null keeps the printer's setting), scaling, paper source, password, print-to-file.PDFStream.NET.TestPrintsample (dry run by default), usage guides, troubleshooting, SECURITY.md, CI workflow, release checklist.bblanchon.PDFium.Win32dependency.Verified
Not verified yet (do not merge on the assumption these work)
docs/release-checklist.mdis "Not run".System.Drawing.Printingas unsupported in Windows services. Service printing is unproven.Known limits (documented in docs/usage.md, docs/troubleshooting.md, SECURITY.md)
/Contentsarray, later pages can also print the fields of earlier pages (status Ok). Flatten such PDFs first. A test pins this behaviour.FPDF_ImportPagesByIndex), tested only on PDFium 160.0.8165.Notes