Class DocToolkitOptions

Namespace

DocToolkit.Extensions.DependencyInjection

Assembly

DocToolkit.Extensions.DependencyInjection.dll

Options controlling the services registered by AddDocToolkit(IServiceCollection, Action<DocToolkitOptions>?).

public sealed class DocToolkitOptions

Inheritance

object

DocToolkitOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Properties

AllowRemoteImageDownload

When true, HTML-to-DOCX and HTML-to-PDF conversion download images referenced by absolute http/https URLs, bounded by RemoteImage. This issues outbound network requests. Because this is a process-wide setting rather than a per-call choice, enabling it opts every conversion in the application into fetching whatever URL the markup names - narrow that with RemoteImage if any caller converts untrusted HTML. Default: false.

This is the only switch that decides whether anything is fetched: while it is false nothing is, no matter what RemoteImage says.

An air-gapped environment no longer fails the conversion - a host that cannot be reached leaves that image out of the result, at a cost of up to Timeout per image.

public bool AllowRemoteImageDownload { get; set; }

Property Value

bool

Fonts

Fonts supplied for characters the PDF renderer cannot otherwise encode, applied to every conversion this container performs. null - the default - supplies none.

public PdfFontOptions? Fonts { get; set; }

Property Value

PdfFontOptions

Remarks

Configured once rather than passed per call, which is a decision this layer makes rather than a signature it copies. The core API takes fonts per conversion; needing them is a property of the deployment, not of the document - somebody converting Cyrillic needs the font for every document, not for some. That is the same reasoning that turned the core's per-call allowRemoteImageDownload into AllowRemoteImageDownload here.

Assigned rather than configured in place, unlike RemoteImage, and for the opposite reason: PdfFontOptions is immutable and carries no defaults that could be lost by replacing it wholesale. There is nothing to protect.

services.AddDocToolkit(o =>
    o.Fonts = new PdfFontOptions("Noto Sans", File.ReadAllBytes("NotoSans-Regular.ttf"))
                  .Add("Noto Sans CJK", File.ReadAllBytes("NotoSansCJK-Regular.ttf")));

Supply fonts covering everything your 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 - measured over 99 real documents, one font rendered 63 where none rendered 71 and four rendered 77. See PdfFontOptions for the whole of that.

Applies to every converter that renders a PDF - IDocxToPdfConverter and IHtmlToPdfConverter alike. It reached only the first until core 0.34.0, because no core overload carried fonts alongside page setup and the remote-image settings; wiring it anyway would have applied fonts only when neither of the others was in play, and a setting that silently stops taking effect depending on unrelated configuration is worse than one that is documented as absent. HtmlToPdfOptions closed that, and this option now reaches both.

Page

The page every producer lays out on when a call does not name one. Default: A4 - what the static API already uses, so leaving this alone changes nothing.

Paper is an application-wide fact rather than a per-call one: a service producing documents for US readers wants Letter on all of them, and repeating that at every call site is how one of them ends up missing it.

services.AddDocToolkit(o => o.Page = PageSetup.Letter);

An explicit argument still wins: ConvertAsync(html, PageSetup.A4) produces A4 whatever this says, because a call naming a page is answering a narrower question than configuration.

Assigned rather than configured in place, unlike RemoteImage, because PageSetup is immutable - there is nothing to configure in place and no restrictive default a wholesale replacement could quietly drop.

public PageSetup Page { get; set; }

Property Value

PageSetup

Exceptions

ArgumentNullException

The value is null.

Note WHERE this surfaces: the configure delegate runs when the options are first materialised, not when AddDocToolkit is called or the service resolved - so a null assigned here throws out of the first conversion rather than out of startup. Measured, after an earlier version of this documentation asserted the opposite.

RemoteImage

Bounds applied to every image fetch, when - and only when - AllowRemoteImageDownload is true. Every default is already the restrictive one: loopback, private and link-local addresses are refused (including 169.254.169.254, the cloud metadata endpoint), only http and https are spoken, redirects are not followed, and each fetch is capped at 10 seconds and 5 MB.

Configured in place rather than assigned, so the restrictive defaults cannot be replaced wholesale by an object that missed one of them:

services.AddDocToolkit(o =>
{
    o.AllowRemoteImageDownload = true;
    o.RemoteImage.Timeout = TimeSpan.FromSeconds(3);
    o.RemoteImage.AllowedHosts.Add("cdn.example.com");
});

This is not a complete SSRF defence; see RemoteImageOptions for the DNS-rebinding window it does not close.

public RemoteImageOptions RemoteImage { get; }

Property Value

RemoteImageOptions