Class HtmlToDocxConverter

Namespace

DocToolkit

Assembly

DocToolkit.dll

Converts an HTML fragment into a Word (.docx) package.

public static class HtmlToDocxConverter

Inheritance

object

HtmlToDocxConverter

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 .docx 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 .docx 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 .docx, 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 — it belongs to the caller, and may be write-only and forward-only, such as an HTTP response body.

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 .docx package 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 the bytes of a .docx package laid out on page. Remote images are not downloaded; see ConvertAsync(string, RemoteImageOptions, CancellationToken) to opt in.

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[]>

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 .docx 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.

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.

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 .docx package 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 to the bytes of a .docx package, downloading and embedding images referenced by absolute http/https URLs, bounded by options.

This still succeeds in an air-gapped or otherwise offline environment. A fetch that cannot leave the machine is caught the same way as a host that refuses to serve the image: that image is skipped, never the whole conversion. What options adds over ConvertAsync(string, bool, CancellationToken) is a per-fetch timeout, a byte cap, an optional host allow-list and a block on loopback/private/link-local addresses (so a hostile document cannot use this opt-in to reach 169.254.169.254 or an internal service, unless options sets AllowPrivateAddresses) - all active by default, so new RemoteImageOptions() already narrows the unbounded form considerably. Offline, that means every remote image is silently missing from the result, at a cost of up to Timeout per image - not a failed conversion. This is still not a complete SSRF defence; see RemoteImageOptions.

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 .docx 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.

Passing true for allowRemoteImageDownload still succeeds in an air-gapped or otherwise offline environment; see ConvertAsync(string, bool, CancellationToken) for what it 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 .docx package 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 to the bytes of a .docx package, optionally downloading and embedding images referenced by absolute http/https URLs.

Passing true for allowRemoteImageDownload routes fetches through a RemoteImageOptions with every default left in place. Loopback, private and link-local hosts - including 169.254.169.254, the cloud metadata endpoint - are refused, and every fetch is capped at 10 seconds and 5 MB. A host that cannot be reached, refuses the connection, or does not serve the image is skipped: that image is left out of the result, and the conversion still succeeds, at a cost of up to 10 seconds for each image it cannot reach. That includes an air-gapped or otherwise offline environment - the conversion completes, just with every remote image silently absent, one 10-second wait at a time. This is the only API on DocToolkit that opens a network connection; everything else, including allowRemoteImageDownload left false, is offline.

This overload can never reach a private or internal host - an intranet image server, for example - because a bool has no way to carry AllowPrivateAddresses. A caller that needs one must use ConvertAsync(string, RemoteImageOptions, CancellationToken) with AllowPrivateAddresses set true; otherwise a consumer converting intranet-hosted markup with allowRemoteImageDownload true gets a document with that image quietly missing, not an exception explaining why.

Only pass true for markup you trust, and prefer to bound it with ct.

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 .docx 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. Remote images are not downloaded; see ConvertAsync(string, bool, Stream, CancellationToken) to opt in.

No network access, and safe in an air-gapped environment, exactly as for ConvertAsync(string, CancellationToken).

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

Parameters

html string

The markup to convert.

destination Stream

The stream the .docx package 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 to the bytes of a .docx package.

No network access, and safe in an air-gapped environment. Nothing the markup references is fetched - not images, not stylesheets, not scripts, whether named by http, https or file. Only data: URI images are embedded. A byte[]-in, byte[]-out conversion that quietly fetched whatever URL happened to be in the markup would hand every caller an SSRF reach and an unbounded hang, so remote fetching is opt-in via ConvertAsync(string, bool, CancellationToken).

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

Parameters

html string

ct CancellationToken

Returns

Task<byte[]>

Examples

string html = "<h1>Quarterly Report</h1><p>Revenue was up <strong>12%</strong>.</p>";

byte[] docx = await HtmlToDocxConverter.ConvertAsync(html);

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 .docx, laid out on page, to outputPath. Remote images are not downloaded.

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 document. 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 .docx to outputPath. Remote images are not downloaded; see ConvertAsync(string, CancellationToken).

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.