Use the engine as a library
The PDF engine of PDF Viewer is also a set of NuGet packages for .NET 9 and .NET 10 (net9.0 and net10.0). It is pure C#.
It opens, reads, searches, edits and saves PDF files, and the Skia package draws pages on any
platform that SkiaSharp supports.
The packages are a preview (0.2.0-preview.1). The API can change before version 1.0.
Packages
| Package | Contents | Dependencies |
|---|---|---|
PdfEngine.Abstractions |
Contracts and models: documents, pages, geometry, render requests, text and search, annotations, forms, save options | none |
PdfEngine.Vector |
The engine: parser and repair, display lists, text extraction and search, annotations, forms, digital signatures, redaction, page organisation, saving | PdfEngine.Abstractions, CoreJ2K, System.Security.Cryptography.Pkcs |
PdfEngine.Vector.Skia |
A portable CPU renderer of the display list | PdfEngine.Vector, SkiaSharp 3.116.1 |
Install the renderer. It brings the other two packages:
dotnet add package PdfEngine.Vector.Skia --prerelease
To read text only, without drawing, install PdfEngine.Vector.
Minimal example
Open a PDF, print the text of page 1, search it, and save page 1 as a PNG:
using PdfEngine.Rendering;
using PdfEngine.Text;
using PdfEngine.Vector.Document;
using PdfEngine.Vector.Skia;
using PdfEngine.Vector.Text;
using SkiaSharp;
using var doc = await PdfVectorDocument.OpenAsync("input.pdf");
Console.WriteLine($"{doc.PageCount} pages");
var text = new PdfVectorTextService();
Console.WriteLine(await text.ExtractPageTextAsync(doc, 1));
foreach (SearchMatch match in await text.SearchTextAsync(doc, "invoice", new SearchOptions { MatchCase = false }))
Console.WriteLine($"page {match.PageNumber}: {match.ContextSnippet}");
using var renderer = new SkiaVectorRenderer();
using RenderedPage page = await renderer.RenderDisplayListAsync(
await doc.GetPageDisplayListAsync(1), new RenderRequest { PageNumber = 1, Dpi = 144 });
var info = new SKImageInfo(page.WidthPixels, page.HeightPixels, SKColorType.Bgra8888, SKAlphaType.Premul);
using var image = SKImage.FromPixelCopy(info, page.Pixels.Span, page.Stride);
using var png = File.Create("page1.png");
image.Encode(SKEncodedImageFormat.Png, 100).SaveTo(png);
PdfVectorDocument.OpenAsync also takes a byte[], a password, and resource limits
(PdfSecurityLimits) for untrusted input.
Platforms
- Windows and macOS: SkiaSharp brings its native library.
- Linux: also add
SkiaSharp.NativeAssets.Linux(3.116.1). - WebAssembly and Android: add the matching
SkiaSharp.NativeAssets.*package. The web demo and the Android app in the repository show how. - Fonts. Text in fonts that a PDF does not embed is drawn with installed fonts. A host
without installed fonts (for example a browser) passes its own
SkiaFontSource.
In a web page
To show PDF files in a web page without writing .NET code, use the web embed SDK: one
script, an API like the Adobe PDF Embed API, and the engine running in the reader’s browser.
It is also on npm as pdfviewer-embed.
Safety
- The engine has no JavaScript interpreter. Document scripts and launch actions are reported, never run.
- Parsing is bounded: object counts, recursion, decompression size and execution time have limits.
- The engine opens no network connection itself. A signature timestamp comes through a client
that your code supplies (
IPdfTimestampClient).
API reference
The generated API reference is at ramanacr.github.io/pdf-viewer/api/, with short guides. The XML documentation comments in the packages also show in your IDE.
More detail:
- PdfEngine.Vector.Skia README: design, feature coverage, parity with Direct2D and known gaps.
- Architecture and the engine design record.
Versions and releases
Package releases have their own git tags: engine-v0.1.0 gives version 0.1.0. The
packages.yml workflow publishes them to nuget.org through Trusted Publishing. A local
dotnet pack gives version 0.0.0-dev (see Build from source).
The package build uses the .NET 10 SDK, so each package has net9.0 and net10.0 assemblies. A
build with the .NET 9 SDK makes only net9.0. Each pack also runs package validation: the
net10.0 assemblies must have all the API of the net9.0 ones. From version 1.0, the pack also
compares the API with the last released package and fails on a breaking change.
Changes in 1.0
Version 1.0 changes the API of 0.2.0-preview.1. Update your code as follows.
Renamed types
| Before | After |
|---|---|
PdfEngine.Vector.Forms.PdfFieldBehaviour |
PdfEngine.Vector.Forms.PdfFieldBehavior |
PdfEngine.Vector.PdfA.PdfAFlavour |
PdfEngine.Vector.PdfA.PdfAFlavor |
PdfEngine.Vector.Forms.PdfFormFiller.Appearance (nested) |
PdfEngine.Vector.Forms.PdfDefaultAppearance (top-level) |
PdfEngine.Vector.Text.TextRect |
PdfEngine.Vector.Text.PdfTextRect |
PdfEngine.Vector.Parsing.MemoryByteSource |
PdfEngine.Vector.Parsing.PdfMemoryByteSource |
PdfEngine.Vector.Parsing.FileByteSource |
PdfEngine.Vector.Parsing.PdfFileByteSource |
PdfEngine.Vector.Parsing.MemoryRangeReader |
PdfEngine.Vector.Parsing.PdfMemoryRangeReader |
PdfEngine.Vector.Services.PdfNativeEngine |
PdfEngine.Vector.Services.PdfVectorEngine |
PdfEngine.Vector.Services.PdfNativeDocument |
PdfEngine.Vector.Services.PdfEditableDocument |
PdfEngine.Vector.Services.PdfNativeAnnotationService |
PdfEngine.Vector.Services.PdfAnnotationService |
PdfEngine.Vector.Services.PdfNativeAttachmentService |
PdfEngine.Vector.Services.PdfAttachmentService |
PdfEngine.Vector.Services.PdfNativeFormService |
PdfEngine.Vector.Services.PdfFormService |
PdfEngine.Vector.Services.PdfNativePageOrganizerService |
PdfEngine.Vector.Services.PdfPageOrganizerService |
PdfEngine.Vector.Services.PdfNativeRedactionService |
PdfEngine.Vector.Services.PdfRedactionService |
PdfEngine.Vector.Services.PdfNativeSaveService |
PdfEngine.Vector.Services.PdfSaveService |
PdfEngine.Vector.Services.PdfNativeSignatureService |
PdfEngine.Vector.Services.PdfSignatureService |
PdfEngine.Vector.Services.PdfNativeSafetyInspector |
PdfEngine.Vector.Services.PdfSafetyInspector |
PdfEngine.Vector.Services.PdfNativeSanitizer |
PdfEngine.Vector.Services.PdfSanitizer |
Renamed members
| Before | After |
|---|---|
PdfFormFiller.ParseDA |
PdfFormFiller.ParseDefaultAppearance |
PdfFormFiller.Appearance.ColourOps |
PdfDefaultAppearance.ColorOps |
PdfAConversionOptions.Flavour |
PdfAConversionOptions.Flavor |
PdfAReport.Flavour |
PdfAReport.Flavor |
PdfAValidator.ClaimedFlavour |
PdfAValidator.ClaimedFlavor |
PdfAValidator.Validate parameter flavour |
parameter flavor |
PdfPreflightProfile.DeviceIndependentColour |
PdfPreflightProfile.DeviceIndependentColor |
PdfPreflightProfile.ListSpotColours |
PdfPreflightProfile.ListSpotColors |
PdfStamps.RotatedBounds parameter centre |
parameter center |
Moved to a different namespace
| Type | Before | After |
|---|---|---|
SystemFontCatalog, SystemFontFace |
PdfEngine.Vector.Editing |
PdfEngine.Vector.Fonts |
PdfAnnotation, PdfAnnotationReader |
PdfEngine.Vector.Services |
PdfEngine.Vector.Annotations |
PdfTextStrings |
PdfEngine.Vector.Services |
PdfEngine.Vector.Objects |
Other changes
PdfFieldValidationException,PdfDataNotLoadedExceptionandPdfAConversionRefusedExceptionnow derive fromPdfVectorException. TheirKindis one of the newPdfVectorErrorKindvaluesFieldValidation,DataNotLoadedandConversionRefused. If youswitchonKindand the switch must cover every value (for example a switch expression without a default case), add these three values or a default case.PdfAConversionRefusedExceptionno longer derives fromInvalidOperationException. If you catchInvalidOperationExceptionaroundPdfAConverter.Convert, also catchPdfAConversionRefusedException.- If you catch
PdfVectorExceptionwhile you read a document that loads by HTTP ranges (PdfRangedDocument), letPdfDataNotLoadedExceptionthrough.PdfRangedDocumentcatches it, loads the missing bytes and tries again. PdfSignatureValidator.RevisionEndsreturnsIReadOnlyList<long>. Before, it returnedList<long>.- New:
PdfObjectResolver.DecodeStream(PdfStream)returns the decoded data of a stream. Use it instead of the stream decoder, which is now internal.
Types and members that are now internal
These were implementation details. They are not part of the 1.0 API:
- Parsing: the lexer, the parser and their tokens, the byte-range loading internals and the
cross-reference entries. The constructors and loaders of
PdfXrefTable,PdfObjectResolver,PdfPageTreeandPdfPageNodeare internal. Their read members stay public, for examplePdfObjectResolver.ResolveandPdfXrefTable.Trailer. - Streams:
PdfStreamDecoder,PdfDecodedStreamandPredictorDecoder. UsePdfObjectResolver.DecodeStream. - PDF functions, colour spaces (
PdfColorSpaceand its nested types), the graphics state and the content interpreter. - Fonts:
PdfFont, the font resolver, font program preparation, the standard 14 fonts tables andTrueTypeFontFile.SystemFontCatalog.Loadis internal. - PDF/A and XMP internals, the incremental writer, the page tree editor and other writing helpers.
- The paint observer (
IPdfPaintObserver,PdfPaintEvent,PdfPaintKind) andPdfVectorPage(useIPdfPage). - Security handlers:
Create,DecryptObjectandEncryptObject. You cannot derive your own security handler. SkiaJpeginPdfEngine.Vector.SkiaandIPdfVectorPageVisualinPdfEngine.Abstractions.
Licence and support
MIT. Report problems and ask questions in the issue tracker. Report security problems privately, as SECURITY.md says.