API reference

An orientation map of the public API: the namespaces, the primary entry points, and the exception hierarchy.

Full generated reference is coming

The complete, member-by-member reference (DocFX, built from the library’s XML doc comments) is not wired up yet. This page is a hand-written orientation map so you can find the right type today: the public namespaces, the primary entry points, and the exception hierarchy. Every type listed here is verified against the current source under src/.

The namespaces at a glance

Rivoli PDF ships as three packages: Rivoli.Pdf.Core (the model, builders, layout), Rivoli.Pdf (rendering, save/load, security), and the optional Rivoli.Pdf.Html (HTML to PDF conversion). The public surface divides into a handful of namespaces:

Namespace	What lives here	Key types
Rivoli.Pdf	The root document type and the exception hierarchy	Document, PdfException and subtypes
Rivoli.Pdf.Model	The document tree: blocks, inlines, styling primitives	Section, Paragraph, Run, Span, Hyperlink, Table, List, ImageBlock, ContainerBlock, PageBreak, Style, Color, PageSize, Margin
Rivoli.Pdf.Builders	The high-level builder and the fluent extension methods	DocumentBuilder, AddHeading/H1–H6, AddParagraph, AddTable, AddImage
Rivoli.Pdf	Save/load/merge/split, the renderer, and save options	DocumentExtensions, PdfDocumentRenderer, PdfSaveOptions, PdfGlobalOptions, PdfVersion, PdfAMode, PdfMerger, PdfSplitter
Rivoli.Pdf.Security	Encryption and permissions	PdfSecuritySettings, PdfPermissions, PdfEncryptionAlgorithm
Rivoli.Pdf.Objects	The low-level PDF object model: build files object-by-object	PdfDictionary, PdfArray, PdfName, PdfString, PdfStream, PdfIndirectObject/Reference
Rivoli.Pdf (low-level)	Content-stream operators and the file writers	PdfContentStream, PdfDocumentWriter, StreamingPdfWriter

For a conceptual tour of how these fit together, start with The document model.

Primary entry points

Constructing a document

Document (namespace Rivoli.Pdf) is the root. Create it directly or with the Create factory, then add sections.

using Rivoli.Pdf;
using Rivoli.Pdf.Model;

var doc  = new Document();                       // empty
var doc2 = Document.Create("Title");             // title only
var doc3 = Document.Create("Title", "Author");   // title + author

doc3.DefaultPageSize = PageSize.A4;
doc3.DefaultMargin   = Margin.Standard;

Section section = doc3.AddSection();             // create + append (returns the section)

For a single fluent expression that sets page setup and structure together, use DocumentBuilder (namespace Rivoli.Pdf.Builders). See Working with the builder.

Adding content

Content goes onto a Section through the fluent extension methods in Rivoli.Pdf.Builders. The headings chain (returning Section); the Add* helpers add a block.

using Rivoli.Pdf.Builders;

section
    .H1("Quarterly Report")
    .AddParagraph("Prepared by the finance team.")
    .AddTable(t => t
        .Header("Quarter", "Revenue")
        .Row("Q1", "$1.2M")
        .Row("Q2", "$1.5M"));

section.AddImage("logo.png", width: 120);
section.AddPageBreak();

Every type is also a plain object you can construct and add directly (section.Add(new Paragraph(...))). The two styles interoperate freely; see the builder guide.

Saving, loading, merging, splitting

The verbs in Rivoli.Pdf.DocumentExtensions are the everyday I/O surface. SavePdf/SavePdfAsync are extension methods on Document; LoadPdf, MergePdfs, and SplitPdf are static helpers.

using Rivoli.Pdf;

document.SavePdf("out.pdf");                       // default PdfVersion.Version14
document.SavePdf("out.pdf", PdfVersion.Version17);
await document.SavePdfAsync("out.pdf");

Document loaded = DocumentExtensions.LoadPdf("in.pdf");

DocumentExtensions.MergePdfs("merged.pdf", "a.pdf", "b.pdf");
DocumentExtensions.SplitPdf("in.pdf", "pages.pdf", startPage: 2, count: 3);

enum PdfVersion { Version14, Version15, Version16, Version17 }. See the how-to recipes for each verb in context.

Advanced rendering, options, and security

For anything beyond a plain save (security, PDF/A, tagged output, CJK fonts, diagnostics), drive the PdfDocumentRenderer with a PdfSaveOptions.

using Rivoli.Pdf;
using Rivoli.Pdf.Security;

var renderer = new PdfDocumentRenderer("1.7");
renderer.RenderToFile(doc, "secure.pdf", new PdfSaveOptions
{
    EnableTaggedPDF = true,
    Language        = "en-US",
    SecuritySettings = new PdfSecuritySettings
    {
        UserPassword = "open-me",
        Algorithm    = PdfEncryptionAlgorithm.Aes256,
        Permissions  = PdfPermissions.Print | PdfPermissions.CopyContents,
    },
});
// or renderer.Render(doc, stream, options);

PdfDocumentRenderer exposes Render(doc, stream[, options]) and RenderToFile(doc, path[, options]).

PdfSaveOptions members

Member	Type	Purpose
PdfVersion	string?	Output version (e.g. "1.7"); falls back to the global default
EnableTaggedPDF	bool?	Emit a tagged (accessible) structure tree
IncludeXmpMetadata	bool?	Embed XMP metadata
PdfAMode	PdfAMode?	PDF/A conformance level (None, PdfA1b, PdfA1a)
SecuritySettings	PdfSecuritySettings?	Encryption, passwords, permissions
GenerateFileID	bool?	Emit a document /ID
Language	string?	Document language (e.g. "en-US"), required for PDF/A-1a
ProducerName	string?	The /Producer string
CjkFontPath	string?	Path to a CJK font for glyph coverage
CjkFontData	byte[]?	In-memory CJK font program (container-friendly); wins over CjkFontPath
Diagnostics	IPdfDiagnostics?	Hook for render diagnostics
PageDecorator	Action<PdfPageDecoratorContext>?	Per-page overlay hook (watermarks/stamps), invoked after body + header/footer painting

Compression and linearization

CompressionLevel, LinearizeForFastWebView, and SubsetFonts are not part of the public PdfSaveOptions surface. Content streams are already deflate-compressed internally.

Global defaults

PdfGlobalOptions (static) holds the fallbacks every render inherits: DefaultPdfVersion, DefaultEnableTaggedPDF, DefaultIncludeXmpMetadata, DefaultPdfAMode, DefaultLanguage, ProducerName, and CjkFontPath, plus ResetToDefaults().

Prefer per-call PdfSaveOptions

PdfGlobalOptions is a single process-wide mutable static, so its setters are [Obsolete]: mutating them while documents render concurrently is a data race. Configure each render with a per-call PdfSaveOptions instead. The getters (and ResetToDefaults()) remain supported: they back each option’s Effective* fallback and are safe to read.

Security types (Rivoli.Pdf.Security)

Type	Notes
PdfSecuritySettings	UserPassword, OwnerPassword, Algorithm, Permissions, EncryptMetadata
PdfEncryptionAlgorithm	None, Aes128, Aes256
PdfPermissions	Flags: None, Print, ModifyContents, CopyContents, ModifyAnnotations, FillForms, ExtractForAccessibility, AssembleDocument, PrintHighQuality, All

Exception hierarchy

All library exceptions descend from PdfException (namespace Rivoli.Pdf), so a single catch can cover the whole library while still letting you target specific failures.

Exception
└── PdfException                (Rivoli.Pdf: base for everything below)
    ├── PdfIOException          (read/write/stream failures)
    ├── PdfValidationException  (invalid model or option combination, e.g. PDF/A + encryption)
    ├── LayoutException         (layout could not be resolved)
    ├── PdfRenderException      (failure during rendering)
    └── PdfParseException       (failure parsing an input PDF on LoadPdf)
        └── PdfPasswordException (encrypted input, wrong/missing password)

try
{
    var doc = DocumentExtensions.LoadPdf("locked.pdf");
}
catch (PdfPasswordException)
{
    // prompt for a password
}
catch (PdfException ex)
{
    // any other library failure
    logger.LogError(ex, "PDF operation failed");
}

See also

• How-to guides: these entry points applied to real tasks.
• The document model: the shape of the tree you build.
• Working with the builder: choosing a construction style.
• The low-level API: the object model, content operators, and writers.
• FAQ & troubleshooting: runtime, platforms, determinism, maturity.