Table of Contents

Class HtmlToPdfOptions

Namespace
DocToolkit
Assembly
DocToolkit.Primitives.dll

Page setup, remote-image policy and fonts for one HTML to PDF conversion.

public sealed class HtmlToPdfOptions
Inheritance
HtmlToPdfOptions
Inherited Members

Examples

// One object when a conversion needs more than one of the three axes. Each property
// defaults to what the simpler overloads do, so setting only what you care about is safe.
byte[] pdf = await HtmlToPdfConverter.ConvertAsync(html, new HtmlToPdfOptions
{
    Page = PageSetup.Letter.WithMargins(36),
    // Fonts = new PdfFontOptions("Noto Sans", File.ReadAllBytes("NotoSans-Regular.ttf")),
    // RemoteImage = new RemoteImageOptions { AllowedHosts = ["cdn.example.com"] },
});

Remarks

This type exists because the three settings are independent and the overloads were not. Page setup and remote images already forced a (page, options) overload; fonts made a third axis, and one overload per combination is nine signatures that a fourth axis would turn into eighteen.

Wiring fonts into the old shape would have been worse than the gap it closed. They would have applied only when no page and no remote-image setting were in play - a setting that silently stops taking effect depending on unrelated configuration. That is not hypothetical: it is the bug HtmlToPdfConverterService already had and fixed, where naming a page quietly opted a call back out of remote fetching a consumer had enabled.

Every default matches the overload it replaces, so moving to this type cannot change behaviour: A4, no remote fetching, no supplied fonts. In particular RemoteImage being null is the offline guarantee, not an unset value waiting to be filled in.

Properties

Fonts

Fonts supplied for characters the PDF renderer cannot otherwise encode. null - the default - supplies none.

public PdfFontOptions? Fonts { get; init; }

Property Value

PdfFontOptions

Remarks

Supply fonts covering everything the documents use, not only the script that failed. They replace the host's own fallbacks rather than adding to them, so too few is worse than none - see PdfFontOptions.

Page

Paper size and margins. Defaults to A4.

public PageSetup Page { get; init; }

Property Value

PageSetup

Remarks

A4 rather than Letter deliberately. A document that does not describe its own paper renders on whatever the reader's template chooses, which is the correctness defect 0.13.0 fixed.

RemoteImage

Bounds applied when remote images are fetched. null - the default - fetches nothing.

public RemoteImageOptions? RemoteImage { get; init; }

Property Value

RemoteImageOptions

Remarks

Leaving this null is the offline guarantee, not an omission: no socket is opened on that path at all. Supplying one opts in, and every bound on RemoteImageOptions then applies.

Edit this page