Class HtmlToPdfConverter

Namespace

DocToolkit

Assembly

DocToolkit.dll

Converts HTML to PDF by pivoting through DOCX.

There is no permissive, NuGet-only, Linux-safe library that renders HTML to PDF directly: the only free renderers are browsers, and a browser is a native binary. Pivoting through DOCX keeps the whole chain pure managed. See learning-docs/dotnet-doc-libs/report.html.

public static class HtmlToPdfConverter

Inheritance

object

HtmlToPdfConverter

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

ConvertAsync(string, PageSetup, RemoteImageOptions, Stream, CancellationToken)

Converts html to a PDF laid out on page, fetching remote images under options.

public static Task ConvertAsync(string html, PageSetup page, RemoteImageOptions options, Stream destination, CancellationToken ct = default)

Parameters

html string

page PageSetup

options RemoteImageOptions

destination Stream

ct CancellationToken

Returns

Task

Remarks

The combination the other overloads cannot express: (html, page) always converts offline, and (html, options) always lays out on A4. Both silently discarded half of what a caller wanting Letter and an allow-list had asked for.

Exceptions

ArgumentNullException

Any argument is null.

ArgumentOutOfRangeException

options has a Timeout or MaxBytesPerImage that is not greater than zero.

ArgumentException

options' AllowedHosts contains a blank entry.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted.

ArgumentException

destination is not writable, or options' AllowedHosts contains a blank entry.

ConvertAsync(string, PageSetup, RemoteImageOptions, CancellationToken)

Converts html to a PDF laid out on page, fetching remote images under options.

public static Task<byte[]> ConvertAsync(string html, PageSetup page, RemoteImageOptions options, CancellationToken ct = default)

Parameters

html string

page PageSetup

options RemoteImageOptions

ct CancellationToken

Returns

Task<byte[]>

Remarks

The combination the other overloads cannot express: (html, page) always converts offline, and (html, options) always lays out on A4. Both silently discarded half of what a caller wanting Letter and an allow-list had asked for.

Exceptions

ArgumentNullException

Any argument is null.

ArgumentOutOfRangeException

options has a Timeout or MaxBytesPerImage that is not greater than zero.

ArgumentException

options' AllowedHosts contains a blank entry.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted.

ConvertAsync(string, PageSetup, Stream, CancellationToken)

Converts html and writes the PDF, laid out on page, to destination. Remote images are not downloaded.

destination is written, from its current position, and is not disposed, closed or sought. As with the other PDF paths it is handed to OfficeIMO's own writer rather than buffered whole.

public static Task ConvertAsync(string html, PageSetup page, Stream destination, CancellationToken ct = default)

Parameters

html string

The markup to convert.

page PageSetup

The page size, orientation and margins.

destination Stream

The stream the PDF is written to.

ct CancellationToken

Cancels the conversion and the write to destination.

Returns

Task

Exceptions

ArgumentNullException

Any argument is null.

ArgumentException

destination is not writable.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted or written.

ConvertAsync(string, PageSetup, CancellationToken)

Converts html to PDF bytes, laid out on page. Remote images are not downloaded.

Page setup reaches the PDF because this pivots through DOCX and OfficeIMO honours the document's w:sectPr - measured, and pinned by PageSetupOutputTests rather than assumed, since an OfficeIMO upgrade could revert it with every DOCX test still green.

public static Task<byte[]> ConvertAsync(string html, PageSetup page, CancellationToken ct = default)

Parameters

html string

The markup to convert.

page PageSetup

The page size, orientation and margins.

ct CancellationToken

Cancels the conversion.

Returns

Task<byte[]>

Examples

string html = "<h1>Invoice 2026-114</h1><p>Due on receipt.</p>";

// A4 portrait with one-inch margins is the default; PageSetup overrides it.
byte[] pdf = await HtmlToPdfConverter.ConvertAsync(
    html,
    PageSetup.A4.Landscape().WithMargins(36));

Exceptions

ArgumentNullException

html or page is null.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted.

ConvertAsync(string, RemoteImageOptions, Stream, CancellationToken)

Converts html and writes the PDF to destination, downloading and embedding images referenced by absolute http/https URLs, bounded by options.

destination is written, from its current position, and is not disposed, closed or sought - it belongs to the caller, and may be write-only and forward-only, such as an HTTP response body. The PDF is written straight through as the renderer produces it, so a failure part-way leaves whatever had already been produced on destination.

This still succeeds in an air-gapped or otherwise offline environment: an unreachable host is skipped, not fatal; see ConvertAsync(string, RemoteImageOptions, CancellationToken) for what options does and does not bound. This is still a composition of the other two converters, not a third conversion: the HTML stage builds the package, bounded by options, and the DOCX stage renders it.

public static Task ConvertAsync(string html, RemoteImageOptions options, Stream destination, CancellationToken ct = default)

Parameters

html string

The markup to convert.

options RemoteImageOptions

Bounds on the remote-image fetches this conversion is allowed to make.

destination Stream

The stream the PDF is written to.

ct CancellationToken

Cancels the conversion and the write to destination.

Returns

Task

Exceptions

ArgumentNullException

html, options or destination is null.

ArgumentOutOfRangeException

options has a Timeout or MaxBytesPerImage that is not greater than zero.

ArgumentException

destination is not writable, or options' AllowedHosts contains a blank entry.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted or written.

ConvertAsync(string, RemoteImageOptions, CancellationToken)

Converts html straight to PDF bytes, downloading and embedding images referenced by absolute http/https URLs, bounded by options.

This still succeeds in an air-gapped or otherwise offline environment: an unreachable host is skipped, not fatal; see ConvertAsync(string, RemoteImageOptions, CancellationToken) for what options does and does not bound. This method only composes that HTML stage with the DOCX-to-PDF render stage - the fetch itself happens there.

public static Task<byte[]> ConvertAsync(string html, RemoteImageOptions options, CancellationToken ct = default)

Parameters

html string

The markup to convert.

options RemoteImageOptions

Bounds on the remote-image fetches this conversion is allowed to make.

ct CancellationToken

Cancels the conversion, including any in-flight image fetch.

Returns

Task<byte[]>

Exceptions

ArgumentNullException

html or options is null.

ArgumentOutOfRangeException

options has a Timeout or MaxBytesPerImage that is not greater than zero.

ArgumentException

options' AllowedHosts contains a blank entry.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted.

ConvertAsync(string, bool, Stream, CancellationToken)

Converts html and writes the PDF to destination, optionally downloading and embedding images referenced by absolute http/https URLs.

destination is written, from its current position, and is not disposed, closed or sought - it belongs to the caller, and may be write-only and forward-only, such as an HTTP response body. The PDF is written straight through as the renderer produces it, so a failure part-way leaves whatever had already been produced on destination.

Passing true for allowRemoteImageDownload still succeeds in an air-gapped or otherwise offline environment; see ConvertAsync(string, bool, CancellationToken) for what this does and does not reach, including why it can never reach a private or internal host.

public static Task ConvertAsync(string html, bool allowRemoteImageDownload, Stream destination, CancellationToken ct = default)

Parameters

html string

The markup to convert.

allowRemoteImageDownload bool

Whether to fetch images named by absolute URLs.

destination Stream

The stream the PDF is written to.

ct CancellationToken

Cancels the conversion and the write to destination.

Returns

Task

Exceptions

ArgumentNullException

html or destination is null.

ArgumentException

destination is not writable.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted or written.

ConvertAsync(string, bool, CancellationToken)

Converts html straight to PDF bytes, optionally downloading and embedding images referenced by absolute http/https URLs.

Passing true for allowRemoteImageDownload still succeeds in an air-gapped or otherwise offline environment: the HTML stage refuses loopback, private and link-local hosts and caps every fetch at 10 seconds and 5 MB, and a host that cannot be reached simply leaves that image out of the result rather than failing the conversion. See ConvertAsync(string, bool, CancellationToken) for what this does and does not reach, including why it can never reach a private or internal host.

public static Task<byte[]> ConvertAsync(string html, bool allowRemoteImageDownload, CancellationToken ct = default)

Parameters

html string

allowRemoteImageDownload bool

ct CancellationToken

Returns

Task<byte[]>

Exceptions

ArgumentNullException

html is null.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted.

ConvertAsync(string, Stream, CancellationToken)

Converts html and writes the PDF to destination.

destination is written, from its current position, and is not disposed, closed or sought - it belongs to the caller, and may be write-only and forward-only, such as an HTTP response body.

No network access, and safe in an air-gapped environment. Nothing the markup references is fetched, and no font is resolved over the network - see ConvertAsync(string, bool, Stream, CancellationToken) to opt in.

public static Task ConvertAsync(string html, Stream destination, CancellationToken ct = default)

Parameters

html string

The markup to convert.

destination Stream

The stream the PDF is written to.

ct CancellationToken

Cancels the conversion and the write to destination.

Returns

Task

Remarks

The document is laid out on A4. Use ConvertAsync(string, PageSetup, Stream, CancellationToken) for anything else.

Exceptions

ArgumentNullException

Either argument is null.

ArgumentException

destination is not writable.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted or written.

ConvertAsync(string, CancellationToken)

Converts html straight to PDF bytes.

No network access, and safe in an air-gapped environment. Nothing the markup references is fetched, and no font is resolved over the network - see ConvertAsync(string, bool, CancellationToken) to opt in.

public static Task<byte[]> ConvertAsync(string html, CancellationToken ct = default)

Parameters

html string

ct CancellationToken

Returns

Task<byte[]>

Remarks

The document is laid out on A4. Use ConvertAsync(string, PageSetup, CancellationToken) for anything else.

Exceptions

ArgumentNullException

html is null.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted.

ConvertToFileAsync(string, PageSetup, string, CancellationToken)

Converts html and writes the PDF, laid out on page, to outputPath.

public static Task ConvertToFileAsync(string html, PageSetup page, string outputPath, CancellationToken ct = default)

Parameters

html string

The markup to convert.

page PageSetup

The page size, orientation and margins.

outputPath string

Where to write the PDF. Overwritten if it exists.

ct CancellationToken

Cancels the conversion and the write.

Returns

Task

Exceptions

ArgumentNullException

html or page is null.

ArgumentException

outputPath is blank.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted.

ConvertToFileAsync(string, string, CancellationToken)

Converts html and writes the PDF to outputPath.

public static Task ConvertToFileAsync(string html, string outputPath, CancellationToken ct = default)

Parameters

html string

outputPath string

ct CancellationToken

Returns

Task

Remarks

The document is laid out on A4. Use ConvertToFileAsync(string, PageSetup, string, CancellationToken) for anything else.

Exceptions

ArgumentNullException

html is null.

ArgumentException

outputPath is blank.

OperationCanceledException

ct was cancelled.

DocumentConversionException

The HTML could not be converted.