PeachPDF

PdfGenerateConfig Class

The settings for generating PDF using PdfGenerator

public sealed class PdfGenerateConfig

Inheritance System.Object → PdfGenerateConfig

Properties
AllowLocalFileAccess	Whether the document may reach the local file system. Defaults to `true`, preserving the historical behavior in which `file:` references are read from disk and relative references resolve against the current working directory. Set to `false` when rendering untrusted input, or in a host with no meaningful file system (a browser/WebAssembly app). Two things then change: every `file:` resource request resolves to “not found”, and a NetworkLoader with no BaseUri of its own (DataUriNetworkLoader and MimeKitNetworkLoader are both in this category) no longer inherits the working directory as a base — so a relative reference goes unresolved rather than being turned into a `file:` URI and read from disk. This covers every resource the document asks for — `<img>`, `<link rel="stylesheet">`, CSS `url()`, SVG `<image href>`, and `@font-face src: url()` — because they all resolve through one place. A deny wins even over an explicitly configured FileUriNetworkLoader. It does not restrict the root document, which is an input rather than a fetch: an HTML string passed to `GeneratePdf`, or a file a FileUriNetworkLoader was explicitly constructed with, is still read.
AnimationProgress	Renders CSS animations (`animation` and `@keyframes`) as the single frame a PDF can hold. A document has no clock, so instead of playing, every animation is sampled at this position in <em>its own</em> run, from `0` (the start) to `1` (the end). `null`, the default, leaves animations unapplied, so an element renders with its ordinary style, as it did before this option existed.
Attachments	Files to embed in the generated PDF - for example the source data behind a report, or the supporting documents of an invoice. Each is listed in the PDF’s attachments panel and indexed in the catalog’s `/AF` array and `/Names /EmbeddedFiles` name tree. Empty by default, in which case nothing is embedded.
BrotliCompression	Off by default. When `true` and PdfVersion is Pdf20, PeachPDF compresses page content, fonts, embedded files and raster images’ pixel data with the PDF 2.0 `/BrotliDecode` filter instead of `/FlateDecode` - typically smaller output. The filter is not read by every PDF reader yet (PDFium, the engine behind Chrome’s and Edge’s viewers, and Acrobat show such a file as blank), so enable it only when you control the readers. Ignored (always off) for any other PdfVersion. Brotli comes from .NET’s own encoder, or from the encoder a host registers with `PeachDrawing.Text.Compression.BrotliCompression.SetCompressor`; with neither, PeachPDF falls back to `/FlateDecode` silently.
ColorOptions	Print color-management options - ICC output intent, black generation, and real ICC device-to-device color conversion (ConversionMode - see ColorOptions’s remarks). null (the default) behaves as OutputIntentProfile being unset - fine unless PdfXConformance requires one, in which case generation throws.
CompressContentStreams	Gets or sets whether PDF content streams are compressed with FlateDecode. Defaults to `true`. Set to `false` to produce human-readable PDF streams, which is useful for testing or debugging.
DefaultLanguage	A fallback language (e.g. `"en-US"`) used for language-dependent rendering — currently `hyphens: auto` automatic hyphenation and the Chinese and Japanese tailorings of `line-break` — only when the document itself declares none via `<html lang="...">`. A document’s own `lang` attribute always takes priority over this setting when present. Per the CSS Text spec, automatic hyphenation requires knowing the text’s language; PeachPDF never guesses one on its own, so a document with no `lang` and no DefaultLanguage set will not be automatically hyphenated. Set this when you know your content’s language out-of-band and want automatic hyphenation to apply anyway.
DownscaleImages	When set to `true` (the default), a raster image whose decoded pixel size is larger than its on-page display size is resized down before being embedded in the PDF, shrinking output file size with no visible quality loss. Set to `false` to always embed images at their full decoded resolution, as PeachPDF did before this option existed.
DownscaleQuality	The JPEG quality (0-100) used when DownscaleImages actually resizes an image that has no real alpha channel (and so would be JPEG-encoded anyway). Has no effect on full-resolution JPEG embeds, and never applies to images with real transparency - those stay on the lossless embed path regardless of downscaling, just resized. Defaults to `70`.
EnableInteractivePdfForms	When set to `true`, PeachPDF emits real, fillable AcroForm fields (text, checkbox, radio, select) for form elements whose resolved `-peachpdf-pdf-form-field` value requests one, instead of the default static box rendering. Defaults to `false` - an explicit, informed opt-in, exactly like EnableTaggedPdf.
EnableTaggedPdf	When set to `true`, PeachPDF emits a PDF/UA-style tagged structure tree (StructTreeRoot, MarkInfo, per-element structure elements and marked content) alongside the visual content, mapping the HTML element tree to standard PDF structure types (see the `-peachpdf-pdf-tag-type` CSS property for how the mapping is controlled). Defaults to `false` — tagging adds a real amount of extra object-model bookkeeping per page, so it is an explicit, informed opt-in.
EnableXmpMetadata	When set to `true`, PeachPDF emits an XMP metadata stream (the document catalog’s `/Metadata` entry) alongside the classic Document Information dictionary - useful for digital-asset-management/archival pipelines that read XMP directly. This is independent of PdfAConformance: a caller can opt into an XMP stream without requesting PDF/A conformance at all. Defaults to `false`. PdfAConformance being anything other than None forces an XMP stream to be written for that render regardless of this flag’s value (PDF/A requires one), without mutating this config object.
Encryption	Password protection and permissions for the generated PDF (AES-256, standard security handler revision 6). null (the default) leaves the document unencrypted. See PdfEncryptionOptions. A whole-document property: every `AddPdfPages`/`AddPages` call on one document must ask for the same protection. Cannot be combined with PdfAConformance or PdfXConformance, both of which forbid encryption - generation throws if it is.
FacturX	When set, the generated PDF becomes a Factur-X / ZUGFeRD hybrid e-invoice: the supplied invoice XML is embedded and the document is marked as a Factur-X invoice in its XMP metadata. See FacturXOptions for what PeachPDF does and does not do, and its requirements (a PDF/A-3 level in PdfAConformance). Defaults to `null` - not an e-invoice.
IgnoreAuthorStyleSheets	When set to `true`, the document’s own author style sheets (its `<style>` elements and `<link rel="stylesheet">` references) are ignored — only the user-agent default styles and any caller-supplied stylesheet (the `cssData` argument) are applied. Inline `style` attributes are not affected. Defaults to `false`.
ImageCompression	How an opaque PNG/BMP/GIF source is embedded - see ImageCompression for what each level does. Defaults to Auto.
JxlPassthrough	<b>Experimental, off by default.</b> When `true` and PdfVersion is Pdf20, an opaque, upright, non-animated gray or RGB JPEG XL image is embedded as its original bytes with the `/JXLDecode` filter instead of being decoded and recompressed. There is no published PDF filter for JPEG XL yet: the name and layout follow the only open-source design so far (an experimental PDFium decoder), so no shipping PDF reader opens such a file today. A JPEG XL with alpha, animation or CMYK always takes the normal raster path. Ignored for other PdfVersion values, and under Lossy (which asks for JPEG re-encoding).
ManualPageHeight	if the page size is undefined this allows you to set manually the page height in points
ManualPageWidth	if the page size is undefined this allows you to set manually the page width in points
MarginBottom	the bottom margin between the page end and the text
MarginLeft	the left margin between the page start and the text
MarginRight	the right margin between the page end and the text
MarginTop	the top margin between the page start and the text
MaximumDownscaleMultiplier	When DownscaleImages resizes an image, the resize target is the image’s on-page display size multiplied by this value, clamped to never exceed the image’s natural decoded size (downscaling never upscales). For example, an image displayed at 60x40 with a multiplier of `2.0` resizes to 120x80 - useful headroom for zooming or printing. Defaults to `1.0` (resize to exactly the display size).
MaxRasterPixels	The largest number of pixels a single rasterized region may have (see RasterizationDpi). A region that would exceed it is rendered at a lower resolution just large enough to fit. Defaults to 64 million pixels (about 256 MB of working memory for one region).
Media	The CSS media type the cascade matches `@media` rules against. Defaults to `"print"` (the appropriate media for paged output). Set to another value (e.g. `"screen"`) to render as that media type instead.
Metadata	Optional overrides for the generated PDF’s document-information metadata (title, author, subject, keywords, creator). When non-null, each non-null field overrides the corresponding value extracted from the HTML source; when null (the default) all metadata comes from the HTML.
MinContentWidth	When set to a positive number, sets the PixelsPerInch to fit the minimum content width
NetworkLoader	The resources to load network content for the renderer. If null is provided, then an implementation that loads only the default document and any resources with data: URIs is provided We ship with MimeKit (MHTML) and HttpClient based implementations that can be used instead.
PageOrientation	the orientation of each page of the generated pdf
PageSize	the page size to use for each page in the generated pdf
PdfAConformance	The PDF/A (ISO 19005) conformance level to target. Defaults to None - no PDF/A-specific work is done (see None for exactly what that means). See PdfAConformance for what each other level requires, including PDF/A-1’s restriction on transparency and the accessible “A” levels’ language requirement. Requesting any level other than None implicitly enables an XMP metadata stream for that render regardless of EnableXmpMetadata.
PdfVersion	The PDF version to target. Defaults to Pdf20 (ISO 32000-2), whose output compresses streams with Brotli unless BrotliCompression is turned off. Set it to Pdf17 for a PDF 1.x file that every reader opens. Requesting a PDF/A or PDF/X level while leaving this property alone picks the version that standard needs: PDF 2.0 for the PDF/A-4 levels and X6, and the PDF 1.4, 1.6 or 1.7 file of the earlier ones. Setting it explicitly to something the requested level cannot use - Pdf17 with PDF/A-4 or PDF/X-6, Pdf20 with any earlier level - throws.
PdfXConformance	The PDF/X (ISO 15930) print-production conformance level to target. Defaults to None - no PDF/X-specific work is done. See PdfXConformance for what each level requires, including the mandatory OutputIntentProfile and X1a’s CMYK-only content restriction. Mutually exclusive with PdfAConformance (archival and print-production are different documents) - generation throws if both are set to a non-`None` value on the same call.
PixelsPerInch	the amount of pixels per inch. We always render at 72 points per inch, so this is used to determine how many pixels a point is
PortableColorFilters	Whether CSS `brightness()`, `contrast()` and `invert()` (and an SVG `feColorMatrix`/`feComponentTransfer` that acts on each channel alone) are written as blend-mode layers every PDF reader composites itself, instead of as a PDF transfer function. Defaults to false.
PreferredColorScheme	The color scheme reported to `@media (prefers-color-scheme: ...)` queries. Defaults to Light; set to Dark to render the document’s dark-mode styles.
RasterAntiAliasing	Whether a bitmap PeachPDF rasterizes itself (see RasterizationDpi) is anti-aliased. Defaults to `true`. This is a single, graphics-wide switch: it governs every pixel PeachPDF’s own raster backend writes for a document — shape fills and strokes, images, and any glyph fill drawn while TextHinting routes text through the raster path — not text alone. Set to `false` to threshold every pixel to fully transparent or fully opaque instead of the usual smoothed, fractional-coverage edge.
RasterizationDpi	The resolution, in pixels per inch of <em>paper</em>, at which PeachPDF renders the effects a PDF cannot express as vector content (for example `filter: blur()`) into bitmaps before embedding them. Defaults to `300`, the print-quality convention: it stays sharp when a viewer is zoomed to several hundred percent or the file is printed. Valid values are 72 to 1200; anything else throws an System.ArgumentOutOfRangeException when generation starts.
ScaleToPageSize	When set to true, this renders the page and automatically scales PixelsPerInch to fit the page contents
ShrinkToFit	When set to true, sets the PixelsPerInch to fit the page contents only if the page contents is larger than the window
SnapBorderWidthsToCssPixels	When set to `true`, a length-valued `border-width` (and `outline-width` and `column-rule-width`) is snapped to whole CSS pixels the way CSS Values 4’s “snap a length as a border width” describes: a width above 0 and below 1px becomes 1px, and a width of 1px or more is rounded down to a whole number of pixels. This is what makes a `0.5px` border a visible 1px line in a browser. Unlike SnapBoxDecorationsToCssPixels it changes the used width and so the size of the box. A PDF has no device pixel, so the CSS pixel (0.75pt) is used. The keywords `thin`, `medium` and `thick` are left alone. Defaults to `false`.
SnapBoxDecorationsToCssPixels	When set to `true`, the rectangle each box’s decorations are painted on is snapped to whole CSS pixels (1px = 0.75pt), the way a browser does before it paints a box: every edge is rounded to the nearest pixel on its own, so a `1px` border covers exactly one device pixel of a viewer showing the page at 100% zoom instead of two half-covered ones (which reads as a wider, paler line), and the background, outline and shadows meet it on the same edges. Layout is unaffected; only what is painted moves, by at most half a CSS pixel (0.375pt), so text can sit that far off its box. The `overflow` clip of a box and the collapsed borders of a table are snapped with it. Not snapped: replaced elements (`<img>`, inline `<svg>`, `<iframe>`, `<math>`), a `<button>` or `<textarea>` in its default appearance, multi-column rules, `@page` margin boxes and page borders, text decorations, list markers and anything under a transform. An edge where a box is cut across a page or line break stays where it is. In PDFium the page size decides the result, not this option: it rounds the page up to a whole number of pixels and fills plain rectangles without anti-aliasing, so on A4 it draws a 1px rule as two rows with the option on or off. A page whose size is a whole number of CSS pixels (such as `794px 1123px`) is crisp there either way. The option helps viewers that anti-alias fills. Defaults to `false`: the exact fractional geometry is what a PDF can express, and what other CSS print engines write.
TextHinting	Whether the text PeachPDF draws into a bitmap (see RasterizationDpi) is fitted to the pixel grid by the font’s own hinting. Defaults to None, so output does not change unless it is asked for.
TextStemDarkening	Whether hinted text that PeachPDF draws into a bitmap is also made a little heavier at its stems, when its font has CFF outlines. Defaults to false. It has an effect only where TextHinting is not None.
TransparencyPolicy	What happens when a document that targets PDF/A-1 or PDF/X-1a/X-3 (all of which forbid transparency) uses something that needs it. Reject (the default) fails generation with an error naming the construct; Flatten renders the affected region into an opaque bitmap at RasterizationDpi instead (embedded as DeviceCMYK under PDF/X-1a). Has no effect at any other conformance level, which permit transparency.

Methods
SetMargins(int)	Set all 4 margins to the given value.