Build from source
This page tells you how to build, run, test and package the project. To take part, also read CONTRIBUTING.md.
Prerequisites
| What | Version | Needed for |
|---|---|---|
| Windows | Windows 10 version 2004 (build 19041) or later, or Windows 11, x64 | The Windows app and its tests |
| .NET SDK | 9.0 | Everything |
| PowerShell | 7 (pwsh) |
scripts/build_publish.ps1 and scripts/build_msix.ps1 |
| Visual Studio 2022 | 17.12 or later (optional) | Opening PdfViewer.slnx |
wasm-tools workload |
.NET 9 | The web demo only |
android workload, Android SDK 35, JDK 17 |
.NET 9 | The Android app only |
| Windows SDK | any recent | The Microsoft Store package only |
The solution file is PdfViewer.slnx (the XML solution format).
Build and run
git clone https://github.com/ramanacr/pdf-viewer.git
cd pdf-viewer
dotnet build PdfViewer.slnx -c Release
dotnet run --project src/PdfViewer/PdfViewer.csproj
dotnet run --project src/PdfViewer/PdfViewer.csproj -- "samples/SampleDocument.pdf"
A developer build also contains PDFium as the reference renderer (see PDFium). The published app does not.
Run the tests
dotnet test tests/PdfEngine.Vector.Tests # engine: unit, fixture, PDFium-differential and fuzz tests
dotnet test tests/PdfEngine.Vector.Skia.Tests # Skia backend against Direct2D; the web and Android engine layer
dotnet test tests/PdfViewer.Tests # the viewer, with the PDFium oracle tests
dotnet test tests/PdfViewer.Tests -p:PdfiumRenderer=false # the viewer as published: no PDFium
More fuzzing, the benchmark and the corpus report:
$env:VECTOR_FUZZ_ITERATIONS=100000; dotnet test tests/PdfEngine.Vector.Tests --filter Fuzz
dotnet run --project eng/vectorpdf/tools/VectorPdf.Tool -c Release -- bench --pages 20
dotnet run --project eng/vectorpdf/tools/VectorPdf.Tool -c Release -- corpus <folder> --out report.jsonl --diff
The corpus runner reads files locally. It writes one JSON line per file (SHA-256, the result of both engines, fallback reasons, pixel difference). No document content leaves the machine. See eng/vectorpdf/corpus/README.md.
The sample document
samples/SampleDocument.pdf is the document that File → Open Sample Demo Document opens, and
the Microsoft Store screenshots show it. It has seven pages: a cover, the features, charts and
shapes, a table, a form, a page of text and a page of comments, with a bookmark for each. Code
makes it with the engine’s own API (PdfDocumentWriter, then PdfAnnotationEditor), in
eng/vectorpdf/tools/VectorPdf.Tool/SampleDocument.cs. Do not edit the PDF by hand. Change the
code and make the file again:
dotnet run --project eng/vectorpdf/tools/VectorPdf.Tool -c Release -- sampledoc --preview preview
- The command writes
samples/SampleDocument.pdf. The same code always writes the same bytes. --preview <folder>also renders each page to a PNG file (--dpi, 110 by default). Look at every page before you commit.- The app embeds the file (
src/PdfViewer/PdfViewer.csproj), so build the app again.tests/PdfViewer.Tests/SampleDocumentTests.cschecks the pages, outline, form and comments, and that the embedded copy is the same file.
Package the Windows app
Use PowerShell 7. The script stops under Windows PowerShell 5.1.
pwsh -ExecutionPolicy Bypass -File .\scripts\build_publish.ps1
The script writes these files to publish\:
| File | What it is |
|---|---|
PdfViewerSetup.exe |
The installer: Start menu and optional desktop shortcut, an uninstaller in Add or Remove Programs, and the optional components as tick boxes |
PdfViewer.exe |
The portable app: one x64 file. It needs the .NET 9 Desktop Runtime. |
System.Speech.dll |
The Read Aloud optional component |
sbom.cyclonedx.json, sbom.spdx.json |
The software bill of materials |
THIRD_PARTY_NOTICES.md |
The licences of what ships |
SampleDocument.pdf |
The sample document (File → Open Sample Demo Document). The app also carries it inside, see The sample document |
The script builds with -p:PdfiumRenderer=false, so the payload has no PDFium. It signs the app
and the installer when a signing certificate is present (see
eng/signing/README.md);
-NoSign builds unsigned. -DryRun publishes and checks the payload without an installer, as CI
does. The release gates (payload size, cold start, PDFium-free) are in
eng/releasegate/README.md.
Package for the Microsoft Store
scripts/build_msix.ps1 makes an MSIX package from the same app. It is self-contained and has
Read Aloud inside it. The Store signs and updates the package, so this version has no update
check, and its package manifest declares the .pdf association. The Store identity is in
eng/msix/identity.json. The Store listing is live:
apps.microsoft.com/detail/9N6QDM774R62.
pwsh -File .\scripts\build_msix.ps1 # with the identity in eng/msix/identity.json
pwsh -File .\scripts\build_msix.ps1 -TestIdentity # a local test package that cannot be submitted
The owner’s steps and all differences from the installer build are in Microsoft Store build.
Build the web demo and the Android app
- Web demo:
dotnet workload install wasm-tools, thendotnet run --project src/PdfViewer.Web. To serve the published site, see src/PdfViewer.Web/README.md. -
Web demo fonts (optional): the Noto fonts are not in the repository. The demo runs without them; text in scripts that only they cover (Arabic, Indic, Sinhala, Thai, CJK and others) is then not drawn. To download them as CI does, with Python 3.11 or later:
py -3 -I eng/webdemo/noto_fonts.py check py -3 -m venv .venv-noto py -3 -I eng/webdemo/noto_fonts.py requirements > noto-requirements.txt .venv-noto\Scripts\python -m pip install --require-hashes --no-deps -r noto-requirements.txt .venv-noto\Scripts\python -I eng/webdemo/noto_fonts.py build --cache ../noto-cache --out src/PdfViewer.Web/wwwroot/fonts/notoThe script downloads only the release archives pinned in
eng/webdemo/noto-fonts.json(github.com/notofonts, about 350 MB, kept in the cache folder), checks the size and SHA-256 of each archive and the SHA-256 of each file (it stops on a mismatch), slices the CJK faces with the pinned fontTools, and writes the files to the output folder, which git ignores. SetNOTO_FONTS_DIRto that folder to run the Noto tests intests/PdfEngine.Vector.Skia.Tests. - Android:
dotnet workload install android, thendotnet build src/PdfViewer.Android -f net9.0-android -c Release. See src/PdfViewer.Android/README.md.
Pack the engine libraries
dotnet pack src/PdfEngine.Abstractions/PdfEngine.Abstractions.csproj -o packages
dotnet pack src/PdfEngine.Vector/PdfEngine.Vector.csproj -o packages
dotnet pack src/PdfEngine.Vector.Skia/PdfEngine.Vector.Skia.csproj -o packages
A local pack has the version 0.0.0-dev. With the .NET 9 SDK it has only net9.0; to get
net10.0 as well, as the released packages have, pack with the .NET 10 SDK. See
Use the engine as a library.
Engine modes
Select the engine mode under View → Rendering Engine, or with the PDF_ENGINE_MODE
environment variable.
| Mode | What it does |
|---|---|
Auto / Hybrid |
The default. The vector engine draws every page, tile, print and export. Damaged or unsupported content is drawn by best effort, as PDFium draws it. |
Vector |
Strict mode for development and CI. Content that the engine classifies as unsupported is outlined in orange, and a page that fails is an error, not a blank page. |
Pdfium |
PDFium draws every page. Only in developer builds (PdfiumRenderer=true). The published app treats it as Auto. |
The status bar badge shows how the current page was drawn (⚡ Vector,
⚡ Vector (N approximated), ⚡ Vector (N unsupported) in strict mode, or ⚠ Unreadable page).
Its tooltip lists the reasons.
Other switches:
PDF_GPU_PRESENT=0turns off the shared GPU texture for zoomed detail tiles.PDF_VECTOR_HOST=wpfselects the earlier WPF drawing host.vectorpdf live <file.pdf>opens a window and measures frame times.
PDFium in developer and test builds
The published app has no PDFium. Developer and test builds (dotnet build, dotnet test, the
default PdfiumRenderer=true) keep a pinned release of Google PDFium as the oracle that the
engine is tested against.
- Release:
chromium/8021(154.0.8021.0) frombblanchon/pdfium-binaries, Windows x64, without V8 and XFA. - SHA-256:
ADAC8CE034015427B5DAA81F8EEDDFCC8E84BC2A9F036F007890FF18BD4388C4(eng/pdfium/version.json). - Script:
pwsh -ExecutionPolicy Bypass -File .\eng\pdfium\build.ps1downloads the archive, checks the hash, and copiespdfium.dllto the runtime folder of developer builds. - Licences:
eng/pdfium/LICENSEandeng/pdfium/licenses/.
Project layout
PdfViewer.slnx the solution
Directory.Build.props shared build settings; the app version comes from the v* git tag
assets/ icons
benchmarks/PdfViewer.Benchmarks/
docs/ this site; engine design and status in docs/pdf-viewer-vector-migration/
eng/
msix/ Microsoft Store manifest template and identity
pdfium/ PDFium for developer and test builds (the oracle)
releasegate/ payload-size, cold-start and PDFium-free release gates
signing/ code-signing notes
vectorpdf/ corpus tooling (vectorpdf), baselines, the git-ignored corpus
webdemo/ static server, Noto font pins and build script for the web demo
samples/ sample documents
scripts/ build_publish.ps1, build_msix.ps1, generate_sbom.ps1, signing scripts
src/
PdfEngine.Abstractions/ UI-neutral contracts and models (NuGet package)
PdfEngine.Vector/ the PDF engine in pure C# (NuGet package)
PdfEngine.Vector.Skia/ portable Skia renderer (NuGet package; web and Android)
PdfEngine.Vector.Direct2D/ Direct2D and DirectWrite renderer and printing (Windows app)
PdfEngine.Vector.Windows/ WPF fallback renderer (Windows app)
PdfEngine.Pdfium/ PDFium interop, the oracle of developer and test builds (not shipped)
PdfViewer.Core/ document session, render scheduler, caches, undo and redo
PdfViewer/ the WPF app
PdfViewer.Web.Engine/ UI-free engine layer of the web demo and the Android app
PdfViewer.Web/ the web demo (Blazor WebAssembly)
PdfViewer.Android/ the Android app (.NET for Android)
Installer/ the setup and uninstall program
tests/
PdfEngine.Vector.Tests/ engine tests
PdfEngine.Vector.Skia.Tests/ Skia backend, web and Android engine layer tests
PdfViewer.Tests/ viewer tests: view models, windows, services, release gates
Continuous integration
| Workflow | When | What it does |
|---|---|---|
ci.yml (job build-and-test) |
Every pull request and push to main; nightly |
Builds, downloads and checks the pinned Noto fonts for the Skia suite’s font tests, runs all test suites (with and without PDFium), the corpus report, benchmarks, SBOMs, a signed dry-run publish and the release gates. The nightly run adds deep fuzzing and the full corpus job. |
web-demo.yml |
Every pull request and push to main |
Builds the web demo with the Noto fonts. From main, deploys the GitHub Pages site: docs/ at the root and the demo under /demo/. |
android.yml |
Changes to the Android app or the code it uses | Builds the APK, checks that it asks for no permission, and uploads it as an artifact. |
packages.yml |
Every pull request and push to main; engine-v* tags |
Packs the three engine packages. An engine-v* tag publishes them to nuget.org through Trusted Publishing (no stored API key). |
npm.yml |
Pull requests that change the SDK, pushes to main; sdk-v* tags |
Packs the embed SDK as the npm package pdfviewer-embed. An sdk-v* tag publishes it to npmjs.com through Trusted Publishing, with provenance. |
release.yml |
v* tags |
Builds, signs and publishes a GitHub release of the Windows app. |
msix.yml |
v* tags |
Builds the Microsoft Store package and uploads it as an artifact. It publishes nothing. |
The main branch is protected: every change comes through a pull request, and the
build-and-test check must pass.
Releases and versions
- The Windows app: push a tag
v<major>.<minor>.<patch>(for examplev4.1.2). The app version comes only from these tags. - The engine packages: push a tag
engine-v<version>(for exampleengine-v0.1.0-preview.1). These tags do not change the app version and do not start an app release. - The embed SDK on npm: set
SDK_VERSIONinpdfviewer-embed.jsandversioninpackages/pdfviewer-embed/package.jsonto the same value, then push a tagsdk-v<version>(for examplesdk-v0.3.0). The workflow refuses a tag that does not match both.