Click or drag to resize

PdfConverter Class

PdfConverter defines a set of methods to render a PDF document from a URL, an HTML string, an HTML file or an HTML stream. The result can be an array of bytes, a file, a stream or a Document object. The generated PDF document can be further changed, saved to a file, stored in a database or sent as the HTTP response to a browser.

PdfConverter Save/Render Methods

The methods below convert the URL given as parameter to a PDF document returned as an array of bytes. The URL can also be the full path of an HTML file on the local file system. The bytes can be sent to a browser, saved to a file or a database, or sent by email as an attachment. The internalLinksDocUrl parameter is the full URL of the document the links with anchors (#name) point to; the links to that document become links inside the PDF.

public byte[] GetPdfBytesFromUrl(string url);
public byte[] GetPdfBytesFromUrl(string url, string internalLinksDocUrl);

To convert an HTML string to PDF use one of the methods below. The first one renders the HTML string as it is. The second one has the additional parameter urlBase, the full URL of the page the HTML string comes from. The converter uses it to resolve the images, CSS and JavaScript files referenced by relative URLs; without it those resources are not loaded. With an http or https base URL the HTML string is loaded as the page at that URL, so web fonts, scripts and cookies of that site work as they do when the URL itself is converted.

public byte[] GetPdfBytesFromHtmlString(string htmlString);
public byte[] GetPdfBytesFromHtmlString(string htmlString, string urlBase);

The corresponding methods that save the PDF document to a file are listed below.

public void SavePdfFromUrlToFile(string url, string outFile);
public void SavePdfFromHtmlStringToFile(string htmlString, string outFile);
public void SavePdfFromHtmlStringToFile(string htmlString, string outFile,
    string urlBase);

The methods with the ToStream suffix write the PDF document to a stream you provide - a file stream, the response stream of a web request - instead of returning the bytes:

public void SavePdfFromUrlToStream(string url, Stream outPdfStream);
public void SavePdfFromUrlToStream(string url, string internalLinksDocUrl,
    Stream outPdfStream);
public void SavePdfFromHtmlFileToStream(string htmlFilePath, Stream outPdfStream);
public void SavePdfFromHtmlFileToStream(string htmlFilePath,
    string internalLinksDocUrl, Stream outPdfStream);
public void SavePdfFromHtmlStringToStream(string htmlString, Stream outPdfStream);
public void SavePdfFromHtmlStringToStream(string htmlString, string urlBase,
    Stream outPdfStream);
public void SavePdfFromHtmlStringToStream(string htmlString, string urlBase,
    string internalLinksDocUrl, Stream outPdfStream);
public void SavePdfFromHtmlStreamToStream(System.IO.Stream htmlStream,
    Encoding streamEncoding, Stream outPdfStream);
public void SavePdfFromHtmlStreamToStream(System.IO.Stream htmlStream,
    Encoding streamEncoding, string urlBase, Stream outPdfStream);
public void SavePdfFromHtmlStreamToStream(System.IO.Stream htmlStream,
    Encoding streamEncoding, string urlBase, string internalLinksDocUrl,
        Stream outPdfStream);

A set of methods returns a Document object that can be changed before it is saved - new pages, text, images, HTML, a digital signature - as described in Post Convert Customization Overview. The Document class and the elements that can be added to it are in the ExpertPdf.Anywhere.PdfDocument namespace. Close the document when you are done with it (it is IDisposable, so a using statement does the same).

public Document GetPdfDocumentObjectFromUrl(string url);
public Document GetPdfDocumentObjectFromUrl(string url, string internalLinksDocUrl);
public Document GetPdfDocumentObjectFromHtmlFile(string htmlFilePath);
public Document GetPdfDocumentObjectFromHtmlFile(string htmlFilePath,
    string internalLinksDocUrl);
public Document GetPdfDocumentObjectFromHtmlString(string htmlString);
public Document GetPdfDocumentObjectFromHtmlString(string htmlString,
    string urlBase);
public Document GetPdfDocumentObjectFromHtmlString(string htmlString,
    string urlBase, string internalLinksDocUrl);
public Document GetPdfDocumentObjectFromHtmlStream(System.IO.Stream htmlStream,
    Encoding streamEncoding);
public Document GetPdfDocumentObjectFromHtmlStream(System.IO.Stream htmlStream,
    Encoding streamEncoding, string urlBase);
public Document GetPdfDocumentObjectFromHtmlStream(System.IO.Stream htmlStream,
    Encoding streamEncoding, string urlBase, string internalLinksDocUrl);

The methods with WithTempFile in their name, for example GetPdfBytesFromHtmlStringWithTempFile(String), first save the HTML to a temporary file and convert that file.

Asynchronous methods

Each of the methods below returns a Task, and no thread waits while the page loads and renders, so the calling thread - a web request, a user interface - is free during the conversion. Cancelling the optional CancellationToken stops the conversion and completes the task as canceled. Do not change the converter, or start another conversion with it, before the task completes; use one converter for each conversion that runs at the same time.

public Task<byte[]> GetPdfBytesFromUrlAsync(string url,
    CancellationToken cancellationToken = default(CancellationToken));
public Task<byte[]> GetPdfBytesFromHtmlFileAsync(string htmlFilePath,
    CancellationToken cancellationToken = default(CancellationToken));
public Task<byte[]> GetPdfBytesFromHtmlStringAsync(string htmlString,
    CancellationToken cancellationToken = default(CancellationToken));
public Task<byte[]> GetPdfBytesFromHtmlStringAsync(string htmlString,
    string urlBase, CancellationToken cancellationToken = default(
        CancellationToken));
public Task SavePdfFromUrlToFileAsync(string url, string outFile,
    CancellationToken cancellationToken = default(CancellationToken));
public Task SavePdfFromHtmlStringToFileAsync(string htmlString, string outFile,
    CancellationToken cancellationToken = default(CancellationToken));
public Task SavePdfFromHtmlStringToFileAsync(string htmlString, string outFile,
    string urlBase, CancellationToken cancellationToken = default(
        CancellationToken));
public Task SavePdfFromUrlToStreamAsync(string url, Stream outPdfStream,
    CancellationToken cancellationToken = default(CancellationToken));
public Task SavePdfFromHtmlStringToStreamAsync(string htmlString, string urlBase,
    Stream outPdfStream, CancellationToken cancellationToken = default(
        CancellationToken));
public Task<Document> GetPdfDocumentObjectFromUrlAsync(string url,
    CancellationToken cancellationToken = default(CancellationToken));
public Task<Document> GetPdfDocumentObjectFromHtmlStringAsync(string htmlString,
    string urlBase, CancellationToken cancellationToken = default(
        CancellationToken));

The image converter has the same pattern: GetImageBytesFromUrlAsync(String, ImageFormat, CancellationToken), GetImageBytesFromHtmlStringAsync and SaveImageFromUrlToFileAsync.

using System.Threading;
using System.Threading.Tasks;

public async Task<byte[]> CreateReportAsync(string url,
    CancellationToken cancellationToken)
{
    PdfConverter converter = new PdfConverter();
    return await converter.GetPdfBytesFromUrlAsync(url, cancellationToken);
}
PdfConverter Configuration Properties

The conversion and the generated PDF document can be configured in many ways: the page size (A4, A3, Letter...), orientation and margins, compression, encryption and passwords, the document information (author, title, subject...), headers and footers with page numbers, and more. The main properties of the converter are described below.

The LicenseKey property takes the license key you received after purchase. When it is not set, the converter runs in evaluation mode and a demo watermark is drawn on the generated document.

public string LicenseKey { get; set; }

The PageWidth and PageHeight properties set the width and height, in pixels, of the browser window the page is rendered in - the same effect as resizing a browser window to those dimensions. The page is laid out at that width and then scaled to the width of the PDF page between the margins.

The default PageWidth is 1024 pixels; 0 or a negative value also means 1024. The default PageHeight is 0, and the whole page is converted, on as many PDF pages as it needs. A positive height sets the height of the browser window, which pages sized to the window (for example with CSS vh units) use; with ClipHtmlView set to true the content below that height is left out of the PDF. Both values can also be passed to the PdfConverter constructor.

public int PageWidth { get; set; }
public int PageHeight { get; set; }

The PdfDocumentOptions property controls the generated PDF document: the margins, the page size and orientation, the compression and JPEG compression level, live links and internal links, single page conversion, documents to prepend or append, and whether the header and footer are shown. It exposes an object of type PdfDocumentOptions, created by the PdfConverter constructor: you set the properties of that object rather than the property itself. The same holds for the other option objects below.

public PdfDocumentOptions PdfDocumentOptions { get; }

The PdfSecurityOptions property sets the user and owner passwords and the permissions of the generated document - printing, copying, editing and so on. It exposes an object of type PdfSecurityOptions. See Security.

public PdfSecurityOptions PdfSecurityOptions { get; }

The PdfDocumentInfo property sets the description of the generated document - title, author, subject, keywords, creation date. It exposes an object of type PdfDocumentInfo. See Document information.

public PdfDocumentInfo PdfDocumentInfo { get; }

The PdfHeaderOptions and PdfFooterOptions properties set the content and the look of the header and the footer. The header and the footer are shown only when the ShowHeader and ShowFooter properties of PdfDocumentOptions are true. They expose objects of type PdfHeaderOptions and PdfFooterOptions. See Headers and footers.

public PdfHeaderOptions PdfHeaderOptions { get; }
public PdfFooterOptions PdfFooterOptions { get; }

Other properties used often:

See Also