Migrating from HiQPdf Classic to HiQPdf Next

Migrating HTML to PDF from HiQPdf Classic to HiQPdf Next
			The class is still called HtmlToPdf and a conversion has the same shape: create the converter, set the options, call ConvertUrlToMemory or ConvertHtmlToMemory. The rendering engine behind it is what changes and with it the way the PDF page is sized and the way headers and footers are described. This guide lists the differences you will actually hit, with the Classic and Next code side by side. Your HiQPdf license works with both editions.

Download Now

Online Demo

Documentation

All Library Components

HiQPdf Next Components

Convert PDF to Text, PDF or Image, Search PDF Text, Extract PDF Images.

Download ASP.NET Demo

Download the ASP.NET Core demo project with complete C# source code

Same License for All Libraries

The same license works with classic HiQPdf library, HiQPdf Next and multiplatform library for .NET

What stays the same · Packages, namespace, serial number · Page sizing model · Headers and footers · Option map · Engine behavior

What Stays the Same

The conversion calls

ConvertUrlToMemory(url), ConvertHtmlToMemory(html, baseUrl), ConvertUrlToFile and ConvertHtmlToFile
WaitBeforeConvert, TriggerMode and HtmlLoadedTimeout
RunJavaScript and MediaType

The option groups

BrowserWidth, BrowserHeight and BrowserZoom
Document with PageSize, PageOrientation and Margins in points
Document.Security, Document.Viewer and Document.Properties

Licensing

The same license works with HiQPdf Classic and HiQPdf Next
Same serial number, set in a different place (see below)
Demo mode without a serial number, with a watermark on the output

Authentication, cookies and HTTP headers

Pages behind a login: Authentication Handling
Authentication, HttpCookies, HttpHeaders and HttpPostFields are set on the converter as before

Step 1: Packages, Namespace and Serial Number

Replace the HiQPdf or HiQPdf.NG package with the Next package for your deployment target, change the using directive and move the serial number from the converter object to the static Licensing class.

HiQPdf Classic

using HiQPdf;

HtmlToPdf converter = new HtmlToPdf();
converter.SerialNumber = "...";
converter.WaitBeforeConvert = 2;
byte[] pdf = converter.ConvertUrlToMemory(url);

HiQPdf Next

using HiQPdf.Next;

Licensing.SerialNumber = "...";   // once per process
HtmlToPdf converter = new HtmlToPdf();
converter.WaitBeforeConvert = 2;
byte[] pdf = converter.ConvertUrlToMemory(url);

HiQPdf Next is a .NET Standard 2.0 library with a platform-specific runtime inside the package: HiQPdf.Next.HtmlToPdf.Windows, .Linux, .MacOS or the .Windows.Arm64 and .Linux.Arm64 variants. Windows and macOS need nothing else; on Linux a few system packages are required, see Getting Started on Linux. HiQPdf Classic runs on Windows only.

In Next a converter object serves a single conversion, so create a new HtmlToPdf for each call.

Step 2: The Page Sizing Model Is Different

This is the change most likely to alter the look of your PDFs, because the default browser window is narrower in Next and the page layout is chosen with a method instead of a set of flags.

HiQPdf Classic

BrowserWidth is the browser window width in pixels (1200 by default) and the HTML is laid out at that width. The PDF page is Document.PageSize (A4 by default) and, because Document.FitPageWidth is true by default, the rendered content is scaled down to fit the fixed page width: 66.11 percent on A4. With FitPageWidth = false, ResizePageWidth (true by default) instead grows the page to show the content unscaled and PostCardMode puts the whole content on a single page.

converter.BrowserWidth = 1200; // default
converter.Document.PageSize = PdfPageSize.A4;
converter.Document.FitPageWidth = true; // default

// the page follows the content, drawn 1:1
converter.Document.FitPageWidth = false;
converter.Document.ResizePageWidth = true; // default

HiQPdf Next

BrowserWidth is again the browser window width, 1024 pixels by default. By default the page is a fixed A4 with that window scaled to it: the HTML is laid out at 1024 pixels and drawn at 77.47 percent. Because the Classic window was 1200 pixels wide, a new converter draws the same page a little larger than Classic did: a 16 px font becomes 9.3 points instead of 7.9 points. To keep the Classic output, pass 1200 as the window width of FitBrowserWindowToPage. With PageWidthFromBrowserWindow the page instead follows the window: the window width × 0.75 points wide (900 pt for 1200 px) with the HTML drawn 1:1.

// the default: an A4 page, the 1024 px window
// scaled to it at 77.47 percent
converter.FitBrowserWindowToPage(PdfPageSize.A4,
    PdfPageOrientation.Portrait, 1024);

// the Classic output: the 1200 px window
// scaled to A4 at 66.11 percent
converter.FitBrowserWindowToPage(PdfPageSize.A4,
    PdfPageOrientation.Portrait, 1200);

// the page follows the window, content drawn 1:1
converter.PageWidthFromBrowserWindow(1200);

Pages wider than the browser window

Both editions lay out content wider than the browser window at its own width and scale it to the page, so nothing is cut: Classic unless TrimToBrowserWidth is true, Next unless AutoResizeBrowserWidth is false. A page designed for a fixed width is laid out the same way from the start when the window has that width: a 1600 pixel page on A4 needs FitBrowserWindowToPage(PdfPageSize.A4, PdfPageOrientation.Portrait, 1600), zoom 49.58, or a page as wide as the content with PageWidthFromBrowserWindow(1600).

Practical rule

Decide once whether you want the content to follow the page (FitBrowserWindowToPage with a standard PdfPageSize) or the page to follow the content (PageWidthFromBrowserWindow). When replacing Classic, FitBrowserWindowToPage with a 1200 pixel window reproduces the Classic page size, layout width and scale, so your users see what they see today; the 1024 pixel default gives slightly larger text. HTML templates designed for A4 or Letter use LayoutAtPageWidth instead and are laid out 1:1. PageWidthFromBrowserWindow(1200, singlePage: true) is the Next equivalent of PostCardMode. Compare a few documents before switching. The zoom values for other page sizes and margins are in HTML to PDF Page Setup and Scaling and the full comparison in Migrate HTML to PDF Page Setup and Headers from HiQPdf Classic.

Step 3: Headers and Footers Are Described as HTML

In Classic a header is a canvas you lay out objects in (PdfHtml, PdfText, PdfLine), with page numbers in a PdfHtmlWithPlaceHolders object and per-page visibility decided in the PageCreatingEvent handler. In Next a header is an HTML document with its own options object; page numbers are variables inside that HTML and per-page visibility is three booleans.

HiQPdf Classic

converter.Document.Header.Enabled = true;
converter.Document.Header.Height = 60;
converter.Document.Header.BackgroundColor = Color.White;

PdfHtml headerHtml = new PdfHtml(headerUrl);
headerHtml.FitDestHeight = true;
converter.Document.Header.Layout(headerHtml);

// line under the header
PdfLine line = new PdfLine(new PointF(0, 59),
    new PointF(headerWidth, 59));
line.ForeColor = Color.Gray;
converter.Document.Header.Layout(line);

// page numbers: {CrtPage} and {PageCount} placeholders
converter.Document.Footer.Enabled = true;
converter.Document.Footer.Height = 40;
converter.Document.Footer.Layout(new PdfHtmlWithPlaceHolders(
    0, 20, "Page {CrtPage} of {PageCount}", null));

// hide on the first page, from an event handler
converter.PageCreatingEvent += (p) =>
    { if (p.PdfPageNumber == 1) p.PdfPage.DisplayHeader = false; };

HiQPdf Next

var header = converter.Document.PdfHtmlHeader;

// or header.Html with header.HtmlBaseUrl
header.HtmlSourceUrl = headerUrl;
// or header.AutoSizeContentHeight = true
header.Height = 60;
header.FitHeight = true;
// make room in the top margin, the default
header.AutoResizePdfMargins = true;

// line under the header: CSS in the header HTML

// page numbers: variables in the footer HTML
var footer = converter.Document.PdfHtmlFooter;
footer.Html = "<div style=\"text-align:center\">" +
    "Page {page_number} of {total_pages}</div>";

// per-page visibility: no event handler
header.ShowInFirstPage = false;
header.ShowInOddPages = true;
header.ShowInEvenPages = true;
// keep the space on the pages without header
header.ReserveSpaceAlways = true;

Anything you drew with PdfText, PdfImage or PdfLine becomes markup in the header or footer HTML. Header and footer HTML is rendered by the same engine as the page, so web fonts, CSS and images work there too. Full sample: Add HTML in Header and Footer with Page Numbers.

Option Map

Classic	Next	Note
using HiQPdf;	using HiQPdf.Next;	Namespace
converter.SerialNumber	Licensing.SerialNumber	Static, set once
BrowserWidth, 1200 by default	BrowserWidth, 1024 by default	Pass 1200 to FitBrowserWindowToPage to keep the Classic scale
Document.FitPageWidth = true (default)	FitBrowserWindowToPage(PdfPageSize.A4, PdfPageOrientation.Portrait, 1200)	Fixed page width, the window scaled to it, zoom 66.11 on A4 and 68.00 on Letter
Document.ForceFitPageWidth	FitBrowserWindowToPage(...)	A window narrower than the page is enlarged to the page width without another setting
FitPageWidth = false with ResizePageWidth	PageWidthFromBrowserWindow(1200)	Page width follows the window width, content drawn 1:1
Document.PostCardMode	PageWidthFromBrowserWindow(1200, singlePage: true)	Whole content on one page
Document.FitPageHeight	Document.AutoResizePdfPageHeight	The page grows to the content height instead of scaling the content down
Document.Header.Enabled + Header.Layout(...)	Document.PdfHtmlHeader.Html or HtmlSourceUrl	The header exists when it has HTML; the same for the footer
Header.Height	PdfHtmlHeader.Height / AutoSizeContentHeight	MinContentHeight and MaxContentHeight limit the automatic height
PdfHtmlWithPlaceHolders with {CrtPage} / {PageCount}	{page_number} / {total_pages} in the HTML	SkipVariablesParsing when not used
Header.FirstPageNumber / AdjustPageCount	PdfHtmlHeader.PageNumberOffset / TotalPagesOffset	FirstPageNumber = 3 becomes PageNumberOffset = 2
PageCreatingEvent → PdfPage.DisplayHeader	PdfHtmlHeader.ShowInFirstPage / ShowInOddPages / ShowInEvenPages	No event handler
Document.InsertPdfFileBefore / AppendPdfFile	Document.AddStartPdf / AddEndPdf	A file path or a byte array
Document.BreakBeforeHtmlElements, BreakAfterHtmlElements, BreakInsideAvoidHtmlElements	CSS break-before, break-after, break-inside	Page breaks are set in the stylesheet
ConvertedHtmlElementSelector	ConvertedElementsSelector	Same CSS selector
HiddenHtmlElements	ExcludedElementsSelector	The array of selectors becomes one comma separated selector
TrimToBrowserWidth = true	AutoResizeBrowserWidth = false	The window keeps its width and content wider than it is cut
MinBrowserHeight, StartBrowserHeight	none	Next always renders the whole content

Engine Behavior

Beyond the API: what the new rendering engine changes in layout, fonts, JavaScript and image loading.

Both engines render with the screen media type by default and both expose MediaType, so that part does not change. What changes is the engine underneath: Next renders like a current Chrome, so pages look the way your browser shows them and a few things Classic handled its own way now follow the browser.

Layout follows current web standards

Flexbox, CSS grid, custom properties, modern selectors and ES2015+ JavaScript render as in Chrome. Layouts that carried workarounds for the old engine can drop them and pages that looked acceptable only because a rule was ignored may now look different
Print CSS is honored: @page, break-before/after/inside, page-break-*, so the page breaks you set with BreakBeforeHtmlElements and the related properties move into the stylesheet
Content is laid out at 96 DPI in a browser window BrowserWidth pixels wide, 1024 by default; step 2 shows how that window is placed on the page

Text and fonts

Font fallback, hinting and metrics are Chrome's. Line breaks and therefore page breaks can shift by a line compared with Classic output on the same document
Web fonts (including WOFF2) are downloaded and embedded as subsets; PDFs with many fonts or large images can differ in size from Classic output
Text stays selectable and searchable; with PDF/UA output it is also tagged

JavaScript and dynamic content

Scripts run in a real browser engine: charts, frameworks and async data that the old engine could not execute now render and pages that finish loading late need WaitBeforeConvert or TriggerMode, as before
RunJavaScript, HtmlLoadedTimeout and BrowserWidth keep their role
The conversion methods have Async variants, such as ConvertUrlToMemoryAsync; ConvertUrlToStream and ConvertUrlToPdfDocument have no Next counterpart, so work with the returned bytes

Resources and security defaults

Lazy-loaded images are fetched by default (LoadLazyImages); images that the old engine skipped will appear
Local files, insecure content and blocked hosts are governed by explicit options (LocalFilesEnabled, AllowInsecureContent, BlockedHosts). Check them if your HTML references file paths or mixed content
Sites served only over HTTP/2 or TLS 1.3 load directly; no need to download the HTML yourself and convert it as a string, as some Classic integrations did

Suggested order: run the Next demo application on your own pages first (online or the downloaded project), settle the page sizing options on two or three representative documents, then port the headers and footers. Most integrations need changes in exactly those two places and nowhere else.

Try Your Pages on the Next Engine

The demo application runs without a serial number, with a stamp on the output, so you can compare Classic and Next side by side before changing anything in production.

Download HiQPdf Next Demo · Online Demo · HTML to PDF in Next

Migrating HTML to PDF from HiQPdf Classic to HiQPdf Next