Table of Contents

Class HtmlPdf

Namespace
NetPdf
Assembly
NetPdf.dll

The public entry point. Convert an HTML+CSS string to a PDF byte stream.

public static class HtmlPdf
Inheritance
HtmlPdf
Inherited Members

Remarks

The facade runs the full pipeline end to end: HTML → cascade → box tree → fragmentainer-aware layout (block / inline / flex / grid / table / multi-column / absolute) → pagination → paint → PDF bytes. Multi-page output, shaped and subset-embedded text, images, paged-media (@page + margin boxes + page counters), and visual parity (gradients, box/text shadows, 2D transforms, filters, borders, border-radius, clip-path, and static SVG) are all painted. Unsupported features emit a stable structured diagnostic rather than throwing or dropping content silently; see docs/diagnostics-codes.md.

Output is deterministic: identical input produces identical bytes, and no timestamp is read unless one is set. JavaScript in the input is ignored with an HTML-SCRIPT-IGNORED-001 diagnostic; see docs/compatibility-matrix.md for the full supported / not-supported feature list.

For typical synchronous use, call Convert(string, HtmlPdfOptions?). For ASP.NET or other async flows, use ConvertAsync(string, HtmlPdfOptions?, CancellationToken). For diagnostic-rich output (warnings, unsupported feature counts, timing breakdown), use ConvertDetailed(string, HtmlPdfOptions?).

Properties

Version

The package's informational version (e.g., 0.3.0-alpha, optionally suffixed with +<commit-sha> when built with Source Link / CI metadata). Sourced from AssemblyInformationalVersionAttribute, which MSBuild auto-populates from the package's VersionPrefix + VersionSuffix. The Semver-2.0 build-metadata suffix (+sha) is preserved for traceability; consumers that want only MAJOR.MINOR.PATCH-prerelease can split on '+'.

public static string Version { get; }

Property Value

string

Remarks

Note: Version reports the four-part assembly version (0.1.0.0), which loses the prerelease tag. The informational version is the correct field for human-facing display and prerelease awareness.

Methods

Convert(ReadOnlySpan<char>, HtmlPdfOptions?)

Convert HTML (as a span) to PDF synchronously. Lower-allocation overload for callers that already hold the input as a span.

public static byte[] Convert(ReadOnlySpan<char> html, HtmlPdfOptions? options = null)

Parameters

html ReadOnlySpan<char>
options HtmlPdfOptions

Returns

byte[]

Convert(string, HtmlPdfOptions?)

Convert HTML to PDF synchronously. Use this when no external resources are loaded (no ResourceLoader or FontResolver); otherwise prefer ConvertAsync(string, HtmlPdfOptions?, CancellationToken) to avoid sync-over-async.

public static byte[] Convert(string html, HtmlPdfOptions? options = null)

Parameters

html string

The HTML document string.

options HtmlPdfOptions

Conversion options. null uses defaults.

Returns

byte[]

The PDF bytes.

ConvertAsync(string, HtmlPdfOptions?, CancellationToken)

Convert HTML to PDF asynchronously. Use this when external resources may be loaded.

public static ValueTask<byte[]> ConvertAsync(string html, HtmlPdfOptions? options = null, CancellationToken ct = default)

Parameters

html string
options HtmlPdfOptions
ct CancellationToken

Returns

ValueTask<byte[]>

ConvertAsync(string, Stream, HtmlPdfOptions?, CancellationToken)

Convert HTML to PDF, writing the bytes to output as they're produced.

public static ValueTask ConvertAsync(string html, Stream output, HtmlPdfOptions? options = null, CancellationToken ct = default)

Parameters

html string
output Stream
options HtmlPdfOptions
ct CancellationToken

Returns

ValueTask

ConvertDetailed(string, HtmlPdfOptions?)

Convert HTML to PDF and return diagnostics, metrics, and timing alongside the bytes.

public static PdfRenderResult ConvertDetailed(string html, HtmlPdfOptions? options = null)

Parameters

html string
options HtmlPdfOptions

Returns

PdfRenderResult