Table of Contents

Interface IPdfGenerator

Namespace
CobaltPdf
Assembly
CobaltPdf.dll

Defines the fluent configuration and render contract for a single PDF generation operation.

public interface IPdfGenerator

Methods

AddCookie(string, string, string?, string)

Adds a browser cookie to the request context.

IPdfGenerator AddCookie(string name, string value, string? domain = null, string path = "/")

Parameters

name string
value string
domain string
path string

Returns

IPdfGenerator

AddLocalStorage(string, string)

Adds a key-value pair to the browser's Local Storage before rendering.

IPdfGenerator AddLocalStorage(string key, string value)

Parameters

key string
value string

Returns

IPdfGenerator

AddSessionStorage(string, string)

Adds a key-value pair to the browser's Session Storage before rendering.

IPdfGenerator AddSessionStorage(string key, string value)

Parameters

key string
value string

Returns

IPdfGenerator

RenderHtmlAsPdfAsync(string, CancellationToken)

Executes the generation process by rendering the provided HTML string.

Task<PdfDocument> RenderHtmlAsPdfAsync(string html, CancellationToken cancellationToken = default)

Parameters

html string

The raw HTML content to render as a PDF.

cancellationToken CancellationToken

Optional token to cancel the render.

Returns

Task<PdfDocument>

A PdfDocument containing the generated binary data.

RenderHtmlFileAsPdfAsync(string, CancellationToken)

Reads an HTML file from disk and renders it as a PDF. Any fluent options set before this call are consumed and reset automatically.

Task<PdfDocument> RenderHtmlFileAsPdfAsync(string filePath, CancellationToken cancellationToken = default)

Parameters

filePath string

Absolute or relative path to a .html file on disk.

cancellationToken CancellationToken

Optional token to cancel the render.

Returns

Task<PdfDocument>

A PdfDocument containing the generated PDF bytes.

Exceptions

FileNotFoundException

Thrown when filePath does not exist.

RenderUrlAsPdfAsync(string, CancellationToken)

Executes the generation process by navigating to the specified URL.

Task<PdfDocument> RenderUrlAsPdfAsync(string url, CancellationToken cancellationToken = default)

Parameters

url string

The fully qualified web address to render.

cancellationToken CancellationToken

Optional token to cancel the render.

Returns

Task<PdfDocument>

A PdfDocument containing the generated binary data.

WithCspBypass(bool)

Enables or disables the bypass of the page's Content Security Policy (CSP).

IPdfGenerator WithCspBypass(bool enable = true)

Parameters

enable bool

Returns

IPdfGenerator

WithCustomJS(string)

Injects custom JavaScript to execute on the page before rendering.

IPdfGeneratorFinal WithCustomJS(string script)

Parameters

script string

Returns

IPdfGeneratorFinal

WithEncryption(PdfEncryptionOptions)

Password-protects the output PDF.

IPdfGenerator WithEncryption(PdfEncryptionOptions encryption)

Parameters

encryption PdfEncryptionOptions

Returns

IPdfGenerator

WithFonts(string)

Configures a local directory to search for custom fonts during rendering.

IPdfGenerator WithFonts(string fontDirectoryPath)

Parameters

fontDirectoryPath string

Returns

IPdfGenerator

WithFooter(string)

Sets the HTML template or file path for the PDF footer.

IPdfGenerator WithFooter(string htmlOrFilePath)

Parameters

htmlOrFilePath string

Returns

IPdfGenerator

WithGrayscale()

Enables grayscale rendering for the PDF.

IPdfGenerator WithGrayscale()

Returns

IPdfGenerator

WithHeader(string)

Sets the HTML template or file path for the PDF header.

IPdfGenerator WithHeader(string htmlOrFilePath)

Parameters

htmlOrFilePath string

Returns

IPdfGenerator

WithLandscape()

Sets the PDF orientation to landscape.

IPdfGenerator WithLandscape()

Returns

IPdfGenerator

WithLazyLoadPages(int, TimeSpan?, TimeSpan?)

Scrolls through a specific number of pages to trigger lazy-loading.

IPdfGenerator WithLazyLoadPages(int pageCount, TimeSpan? delay = null, TimeSpan? timeout = null)

Parameters

pageCount int

Number of viewports to scroll.

delay TimeSpan?

Time to wait at each step. Default is 200ms.

timeout TimeSpan?

Maximum time to wait for the entire scroll process. Default is 30s.

Returns

IPdfGenerator

WithMargins(MarginOptions)

Sets the page margins for the rendered PDF. Defaults to 1 cm on all sides if not called.

IPdfGenerator WithMargins(MarginOptions margins)

Parameters

margins MarginOptions

Returns

IPdfGenerator

WithMediaType(CssMediaType)

Sets the CSS media type to emulate during rendering (e.g., Screen or Print).

IPdfGenerator WithMediaType(CssMediaType type)

Parameters

type CssMediaType

Returns

IPdfGenerator

WithMetadata(Action<MetadataOptions>)

Sets descriptive metadata (title, author, subject, etc.) embedded in the PDF document.

IPdfGenerator WithMetadata(Action<MetadataOptions> configure)

Parameters

configure Action<MetadataOptions>

Returns

IPdfGenerator

WithPageRanges(string)

Restricts the output PDF to the specified page ranges.

IPdfGenerator WithPageRanges(string ranges)

Parameters

ranges string

Comma-separated page ranges, e.g. "1-3", "1,4,7".

Returns

IPdfGenerator

WithPageSize(string, string)

Sets custom page dimensions, overriding the paper format.

IPdfGenerator WithPageSize(string width, string height)

Parameters

width string

CSS width string, e.g. "8.5in", "200mm".

height string

CSS height string, e.g. "11in", "297mm".

Returns

IPdfGenerator

WithPaperFormat(string)

Sets the paper format (size) for the rendered PDF. Defaults to "A4" if not called.

IPdfGenerator WithPaperFormat(string format)

Parameters

format string

A Playwright paper format string, e.g. "A4", "A3", "Letter", "Legal", "Tabloid".

Returns

IPdfGenerator

WithPrintBackground(bool)

Enables or disables printing of CSS background graphics (colors, images).

IPdfGenerator WithPrintBackground(bool enable = true)

Parameters

enable bool

true to print backgrounds (default); false to suppress them.

Returns

IPdfGenerator

WithReloadAfterStorage()

Requests a page reload after localStorage and sessionStorage values have been injected on the initial page load.

IPdfGenerator WithReloadAfterStorage()

Returns

IPdfGenerator

WithScale(float)

Sets the scale factor for PDF content (0.1 – 2.0). Values below 1.0 shrink the content.

IPdfGenerator WithScale(float scale)

Parameters

scale float

A value between 0.1 and 2.0.

Returns

IPdfGenerator

WithWaitStrategy(WaitOptions)

Configures the strategy used to determine when the page is ready for PDF rendering. Use this to handle asynchronous content by waiting for a fixed duration or a specific event.

IPdfGenerator WithWaitStrategy(WaitOptions strategy)

Parameters

strategy WaitOptions

Returns

IPdfGenerator

Remarks

Note: This is an assignment; if called multiple times, the last call in the chain wins.

Supported Strategies:

  • Network IdleThe default. Waits until there are no network requests for at least 500ms.
  • Fixed DelayWaits for a specific TimeSpan (e.g., WaitOptions.ForDelay(TimeSpan.FromSeconds(5))).
  • CSS/JS PollingWaits for a CSS selector to appear or a JS expression to return true.
  • Manual Signal The most robust method for complex apps. Use WaitOptions.ForSignal(timeout) and call window.cobaltNotifyRender() inside your WithCustomJS(string) script to manually trigger the render once your logic is complete.

WithWatermark(WatermarkOptions)

Applies a watermark overlay to every page of the output PDF.

IPdfGenerator WithWatermark(WatermarkOptions watermark)

Parameters

watermark WatermarkOptions

Returns

IPdfGenerator