Convert Word DOCX to PDF

The Word to PDF Converter component allows you to convert DOCX Word documents to PDF.

This component is bundled and distributed as two separate NuGet packages for Windows and Linux, each including the same .NET Standard 2.0 library and different native runtimes. Targeting .NET Standard 2.0 makes the packages compatible with a wide range of .NET Core and .NET Framework versions.

You can reference the HiQPdf.Next.WordToPdf.Windows NuGet package in applications running on Windows or the HiQPdf.Next.WordToPdf.Linux NuGet package in applications running on Linux to enable Excel to PDF conversion in your application. The package for Windows is referenced by the HiQPdf.Next.Windows metapackage for all components, and the package for Linux is referenced by the HiQPdf.Next.Linux metapackage for all components.

There are also multiplatform metapackages that reference both the Windows and Linux Excel to PDF packages: HiQPdf.Next.WordToPdf for the Excel to PDF functionality and HiQPdf.Next for the entire HiQPdf Next library.

Overview

The HiQPdf.NextWordToPdfConverter class allows you to load a DOCX file and generate a PDF document, with optional control over page formatting, layout and visual elements such as headers and footers and table of contents creation.

You can apply the PDF page settings such as size, orientation and margins from the original Word document or you can reflow the content using your own custom PDF page size, orientation and margins. The converter also supports HTML headers and footers, page break recognition and automatic creation of a table of contents based on document headings.

Create the Word to PDF Converter

The HiQPdf.NextWordToPdfConverter class is used to convert DOCX documents to PDF. You can create an instance using the default constructor, which initializes the converter with standard settings. These settings can later be customized through the WordToPdfConverterPdfDocumentOptions property which exposes an object of WordToPdfDocumentOptions type controlling various aspects of the generated PDF document and through properties like WordToPdfConverterProcessPageBreakMarks which controls the PDF generation process.

Create a Word to PDF Converter Instance
// Create a new Word to PDF converter instance
WordToPdfConverter wordToPdfConverter = new WordToPdfConverter();

Note that WordToPdfConverter instances are not reusable. You must create a new instance for each conversion. Reusing an instance after a completed conversion will result in an exception.

Configure the PDF Page Settings

The format of the generated PDF document pages is controlled primarily by the WordToPdfDocumentOptionsUsePageSettingsFromWord property, which specifies whether to use the page settings from the Word document or custom values defined in code. An object of type WordToPdfDocumentOptions is exposed through the WordToPdfConverterPdfDocumentOptions property.

If UsePageSettingsFromWord is set to true, the converter will use the page size, orientation and margins defined in the Word document. The following example shows how to enable this behavior.

Use Page Settings from Word
wordToPdfConverter.PdfDocumentOptions.UsePageSettingsFromWord = true;

If UsePageSettingsFromWord is set to false, the converter will use the custom PDF page settings defined through the WordToPdfConverterPdfDocumentOptions property. The following example shows how to configure custom page size, orientation and margins.

Use Custom PDF Page Settings
wordToPdfConverter.PdfDocumentOptions.UsePageSettingsFromWord = false;
wordToPdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;
wordToPdfConverter.PdfDocumentOptions.PdfPageOrientation = PdfPageOrientation.Landscape;
wordToPdfConverter.PdfDocumentOptions.LeftMargin = 20;
wordToPdfConverter.PdfDocumentOptions.RightMargin = 20;
wordToPdfConverter.PdfDocumentOptions.TopMargin = 30;
wordToPdfConverter.PdfDocumentOptions.BottomMargin = 30;

Add HTML Headers and Footers

You can add a header or footer from a URL or from an HTML string. The header and footer can include variables such as {page_number} or {total_pages} and support automatic resizing.

The creation of the HTML header and footer is controlled by the WordToPdfDocumentOptionsPdfHtmlHeader and WordToPdfDocumentOptionsPdfHtmlFooter properties. These properties expose objects of type PdfHtmlHeaderFooter, which derives from PdfHtmlTemplate.

The WordToPdfDocumentOptions object is exposed through the WordToPdfConverterPdfDocumentOptions property.

The header and footer options are similar to those available in the HTML to PDF Converter and are described in detail in the HTML Header and Footer with Page Numbers documentation section.

Table of Contents

If WordToPdfDocumentOptionsGenerateTableOfContents is set to true, the converter will automatically create a table of contents based on the titles and subtitles defined in the Word document using heading styles. The creation and appearance of the table of contents are controlled by the properties of a PdfTableOfContents object exposed through the WordToPdfDocumentOptionsTableOfContents property.

The WordToPdfDocumentOptions object is exposed through the WordToPdfConverterPdfDocumentOptions property.

The following example shows how enable the automatic generation of a table of contents.

Generate Table of Contents
wordToPdfConverter.PdfDocumentOptions.GenerateTableOfContents = true;

Page Break Recognition

The WordToPdfConverterProcessPageBreakMarks property controls whether page break markers found in the Word document are translated into actual page breaks in the generated PDF. The default value is true, which means that page breaks defined in the Word content will be preserved during conversion.

Enable Page Breaks from Word Document
wordToPdfConverter.ProcessPageBreakMarks = true;

Convert Word to PDF

To convert a Word document from a memory buffer to a PDF document in a memory buffer use the WordToPdfConverterConvertToPdf(Byte) method. The parameter is the Word document read into a memory buffer.

Convert Word from Memory to PDF in Memory
byte[] outPdfBuffer = wordToPdfConverter.ConvertToPdf(wordBytes);

To convert a Word file to a PDF document in a memory buffer use the WordToPdfConverterConvertToPdf(String) method. The parameter is the full path of the Word file to be converted.

Convert Word File to PDF in Memory
byte[] outPdfBuffer = wordToPdfConverter.ConvertToPdf(wordFilePath);

After conversion the resulting PDF document is returned as a byte array for in-memory processing such as streaming to a web client or saving to a database or a file.

For example you can write the byte array to disk to store the PDF as a file.

Write PDF Data to File
File.WriteAllBytes("output.pdf", outPdfBuffer);

There are also methods to convert a Word document to a PDF file directly.

To convert a Word document from a memory buffer to a PDF file use the WordToPdfConverterConvertToPdfFile(Byte, String) method. The first parameter is the Word document read into a memory buffer and the second parameter is the full path of the output PDF file.

Convert Word from Memory to PDF File
wordToPdfConverter.ConvertToPdfFile(wordBytes, outputPdfFilePath);

To convert a Word file to a PDF file use the WordToPdfConverterConvertToPdfFile(String, String) method. The first parameter is the full path of the Word file to be converted and the second parameter is the full path of the output PDF file.

Convert Word File to PDF File
wordToPdfConverter.ConvertToPdfFile(wordFilePath, outputPdfFilePath);

Asynchronous Word to PDF Methods

There are also asynchronous variants of these methods that follow the Task-based Asynchronous Pattern (TAP) in .NET, allowing Word to PDF conversion to run in parallel using async and await. These methods share the same names as their synchronous counterparts and include the "Async" suffix. They also accept an optional System.ThreadingCancellationToken parameter that can be used to cancel the conversion operation where applicable.

To convert a Word document from a memory buffer to a PDF document in a memory buffer use the WordToPdfConverterConvertToPdfAsync(Byte, CancellationToken) method. The parameter is the Word document read into a memory buffer.

Asynchronously Convert Word from Memory to PDF in Memory
byte[] outPdfBuffer = await wordToPdfConverter.ConvertToPdfAsync(wordBytes);

To convert a Word file to a PDF document in a memory buffer use the WordToPdfConverterConvertToPdfAsync(String, CancellationToken) method. The parameter is the full path of the Word file to be converted.

Asynchronously Convert Word File to PDF in Memory
byte[] outPdfBuffer = await wordToPdfConverter.ConvertToPdfAsync(wordFilePath);

To convert a Word document from a memory buffer to a PDF file use the WordToPdfConverterConvertToPdfFileAsync(Byte, String, CancellationToken) method. The first parameter is the Word document read into a memory buffer and the second parameter is the full path of the output PDF file.

Asynchronously Convert Word from Memory to PDF File
await wordToPdfConverter.ConvertToPdfFileAsync(wordBytes, outputPdfFilePath);

To convert a Word file to a PDF file use the WordToPdfConverterConvertToPdfFileAsync(String, String, CancellationToken) method. The first parameter is the full path of the Word file to be converted and the second parameter is the full path of the output PDF file.

Asynchronously Convert Word File to PDF File
await wordToPdfConverter.ConvertToPdfFileAsync(wordFilePath, outputPdfFilePath);

Code Sample - Convert Word to PDF

Convert Word to PDF in ASP.NET Core
using System;
using System.IO;
using System.ComponentModel.DataAnnotations;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using HiQPdf_Next_AspNetDemo.Models;

using HiQPdf.Next;

namespace HiQPdf_Next_AspNetDemo.Controllers
{
    public class WordToPdfController : Controller
    {
        private readonly IWebHostEnvironment m_hostingEnvironment;

        public WordToPdfController(IWebHostEnvironment hostingEnvironment)
        {
            m_hostingEnvironment = hostingEnvironment;
        }

        public IActionResult Index()
        {
            var model = SetViewModel();

            return View(model);
        }

        [HttpPost]
        public async Task<IActionResult> ConvertWordToPdf(WordToPdfViewModel model)
        {
            if (!ModelState.IsValid)
            {
                var errorMessage = ModelStateHelper.GetModelErrors(ModelState);
                throw new ValidationException(errorMessage);
            }

            // Replace the demo serial number with the serial number received upon purchase
            // to run the converter in licensed mode
            Licensing.SerialNumber = "YCgJMTAE-BiwJAhIB-EhlWTlBA-UEBRQFBA-U1FOUVJO-WVlZWQ==";

            // Create a Word to PDF converter object with default settings
            WordToPdfConverter wordToPdfConverter = new WordToPdfConverter();

            // Set whether a table of contents is automatically generated from headings
            wordToPdfConverter.PdfDocumentOptions.GenerateTableOfContents = model.GenerateToc;

            //  Set whether to use page settings (size, margins) from the Word document or the custom settings
            wordToPdfConverter.PdfDocumentOptions.UsePageSettingsFromWord = model.PdfPageSettingsMode == "FromWordDocument";

            // Set whether page break marks from Word documents should be processed
            wordToPdfConverter.ProcessPageBreakMarks = model.ProcessWordPageBreakMarks;

            if (!wordToPdfConverter.PdfDocumentOptions.UsePageSettingsFromWord)
            {
                // Set PDF page size which can be a predefined size like A4 or a custom size in points 
                // Leave it not set to have a default A4 PDF page
                wordToPdfConverter.PdfDocumentOptions.PageSize = SelectedPdfPageSize(model.PdfPageSize);

                // Set PDF page orientation to Portrait or Landscape
                // Leave it not set to have a default Portrait orientation for PDF page
                wordToPdfConverter.PdfDocumentOptions.PageOrientation = SelectedPdfPageOrientation(model.PdfPageOrientation);

                // Set PDF page margins in points or leave them not set to have a PDF page without margins
                wordToPdfConverter.PdfDocumentOptions.Margins.Left = model.LeftMargin;
                wordToPdfConverter.PdfDocumentOptions.Margins.Right = model.RightMargin;
                wordToPdfConverter.PdfDocumentOptions.Margins.Top = model.TopMargin;
                wordToPdfConverter.PdfDocumentOptions.Margins.Bottom = model.BottomMargin;

                // Set the Word viewer zoom percentage
                wordToPdfConverter.PdfDocumentOptions.Zoom = model.WordViewerZoom;
            }

            // Set PDF header and footer
            SetHeader(wordToPdfConverter, model);
            SetFooter(wordToPdfConverter, model);

            byte[] inputWordfBytes = null;

            // If an uploaded file exists, use it with priority
            if (model.WordFile != null && model.WordFile.Length > 0)
            {
                try
                {
                    using var ms = new MemoryStream();
                    await model.WordFile.CopyToAsync(ms);
                    inputWordfBytes = ms.ToArray();
                }
                catch (Exception ex)
                {
                    throw new Exception("Failed to read the uploaded Word file", ex);
                }
            }
            else
            {
                // Otherwise, fall back to the URL
                string wordUrl = model.WordFileUrl?.Trim();
                if (string.IsNullOrWhiteSpace(wordUrl))
                    throw new Exception("No Word file provided: upload a file or specify a URL");

                try
                {
                    if (wordUrl.StartsWith("file://", StringComparison.OrdinalIgnoreCase))
                    {
                        string localPath = new Uri(wordUrl).LocalPath;
                        inputWordfBytes = await System.IO.File.ReadAllBytesAsync(localPath);
                    }
                    else
                    {
                        using var httpClient = new System.Net.Http.HttpClient();
                        inputWordfBytes = await httpClient.GetByteArrayAsync(wordUrl);
                    }
                }
                catch (Exception ex)
                {
                    throw new Exception("Could not download the Word file from URL", ex);
                }
            }

            // The buffer to receive the generated PDF document
            byte[] outPdfBuffer = wordToPdfConverter.ConvertToPdf(inputWordfBytes);

            // Send the PDF file to browser
            FileResult fileResult = new FileContentResult(outPdfBuffer, "application/pdf");
            // send as attachment
            fileResult.FileDownloadName = "WordToPdf.pdf";

            return fileResult;
        }

        private void SetHeader(WordToPdfConverter wordToPdfConverter, WordToPdfViewModel model)
        {
            bool headerEnabled = model.HeaderEnabled;
            if (!headerEnabled)
                return;

            // Set the header HTML from a URL or from an HTML string
            bool headerHtmlFromUrl = model.HeaderHtmlSource == "Url";
            if (headerHtmlFromUrl)
            {
                string headerUrl = model.HeaderUrl;

                wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.HtmlSourceUrl = headerUrl;
            }
            else
            {
                string headerHtml = model.HeaderHtml;
                string headerHtmlBaseUrl = model.HeaderHtmlBaseUrl;

                wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.Html = headerHtml;
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.HtmlBaseUrl = headerHtmlBaseUrl;
            }

            // Enable automatic height adjustment based on header HTML content
            bool autoSizeHeaderContentHeight = model.AutoSizeHeaderContentHeight;
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.AutoSizeContentHeight = autoSizeHeaderContentHeight;

            // Set the minimum and maximum content height used when AutoSizeContentHeight is enabled
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.MinContentHeight = model.HeaderMinContentHeight;
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.MaxContentHeight = model.HeaderMaxContentHeight;

            // Set a fixed height for the header if AutoResizeHeight is disabled
            if (model.HeaderHeight.HasValue)
            {
                int headerHeight = model.HeaderHeight.Value;
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.Height = headerHeight;
            }

            // If AutoResizeHeight is enabled and both Height and FitHeight are set,
            // the content may be scaled down to fit the specified height
            bool fitHeaderHeight = model.FitHeaderHeight;
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.FitHeight = fitHeaderHeight;

            // Enable automatic top margin adjustment in the PDF based on the header
            bool autoResizeTopMargin = model.AutoResizeTopMargin;
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.AutoResizePdfMargins = autoResizeTopMargin;

            // Set header visibility on specific PDF pages: first page, odd-numbered pages and even-numbered pages
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.ShowInFirstPage = model.ShowHeaderInFirstPage;
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.ShowInOddPages = model.ShowHeaderInOddPages;
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.ShowInEvenPages = model.ShowHeaderInEvenPages;

            // Reserve space for the header on all pages, regardless of visibility
            // If false, the document will be rendered using print styles instead of screen styles
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.ReserveSpaceAlways = model.ReserveHeaderSpace;

            // Optimize the header rendering time by providing a hint if the HTML template contains variables such as { page_number} or { total_pages}
            wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.SkipVariablesParsing = model.SkipHeaderVariablesParsing;

            // Optionally set additional time to wait for the asynchronous header HTML content before rendering
            if (model.HeaderWaitBeforeConvert.HasValue && model.HeaderWaitBeforeConvert.Value > 0)
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlHeader.WaitBeforeConvert = model.HeaderWaitBeforeConvert.Value;
        }

        private void SetFooter(WordToPdfConverter wordToPdfConverter, WordToPdfViewModel model)
        {
            bool footerEnabled = model.FooterEnabled;
            if (footerEnabled)
            {
                // Set the footer HTML from a URL or from an HTML string
                bool footerHtmlFromUrl = model.FooterHtmlSource == "Url";
                if (footerHtmlFromUrl)
                {
                    string footerUrl = model.FooterUrl;

                    wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.HtmlSourceUrl = footerUrl;
                }
                else
                {
                    string footerHtml = model.FooterHtml;
                    string footerHtmlBaseUrl = model.FooterHtmlBaseUrl;

                    wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.Html = footerHtml;
                    wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.HtmlBaseUrl = footerHtmlBaseUrl;
                }

                // Enable automatic height adjustment based on footer HTML content
                bool autoSizeFooterContentHeight = model.AutoSizeFooterContentHeight;
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.AutoSizeContentHeight = autoSizeFooterContentHeight;

                // Set the minimum and maximum content height used when AutoSizeContentHeight is enabled
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.MinContentHeight = model.FooterMinContentHeight;
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.MaxContentHeight = model.FooterMaxContentHeight;

                // Set a fixed height for the footer if AutoResizeHeight is disabled
                if (model.FooterHeight.HasValue)
                {
                    int footerHeight = model.FooterHeight.Value;
                    wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.Height = footerHeight;
                }

                // If AutoResizeHeight is enabled and both Height and FitHeight are set,
                // the content may be scaled down to fit the specified height
                bool fitFooterHeight = model.FitFooterHeight;
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.FitHeight = fitFooterHeight;

                // Enable automatic bottom margin adjustment in the PDF based on the footer
                bool autoResizeBottomMargin = model.AutoResizeBottomMargin;
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.AutoResizePdfMargins = autoResizeBottomMargin;

                // Set footer visibility on specific PDF pages: first page, odd-numbered pages and even-numbered pages
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.ShowInFirstPage = model.ShowFooterInFirstPage;
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.ShowInOddPages = model.ShowFooterInOddPages;
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.ShowInEvenPages = model.ShowFooterInEvenPages;

                // Reserve space for the footer on all pages, regardless of visibility
                // If false, the document will be rendered using print styles instead of screen styles
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.ReserveSpaceAlways = model.ReserveFooterSpace;

                // Optimize the footer rendering time by providing a hint if the HTML template contains variables such as { page_number} or { total_pages}
                wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.SkipVariablesParsing = model.SkipFooterVariablesParsing;

                // Optionally set additional time to wait for the asynchronous footer HTML content before rendering
                if (model.FooterWaitBeforeConvert.HasValue && model.FooterWaitBeforeConvert.Value > 0)
                    wordToPdfConverter.PdfDocumentOptions.PdfHtmlFooter.WaitBeforeConvert = model.FooterWaitBeforeConvert.Value;
            }
        }

        private PdfPageSize SelectedPdfPageSize(string selectedValue)
        {
            switch (selectedValue)
            {
                case "A0":
                    return PdfPageSize.A0;
                case "A1":
                    return PdfPageSize.A1;
                case "A10":
                    return PdfPageSize.A10;
                case "A2":
                    return PdfPageSize.A2;
                case "A3":
                    return PdfPageSize.A3;
                case "A4":
                    return PdfPageSize.A4;
                case "A5":
                    return PdfPageSize.A5;
                case "A6":
                    return PdfPageSize.A6;
                case "A7":
                    return PdfPageSize.A7;
                case "A8":
                    return PdfPageSize.A8;
                case "A9":
                    return PdfPageSize.A9;
                case "ArchA":
                    return PdfPageSize.ArchA;
                case "ArchB":
                    return PdfPageSize.ArchB;
                case "ArchC":
                    return PdfPageSize.ArchC;
                case "ArchD":
                    return PdfPageSize.ArchD;
                case "ArchE":
                    return PdfPageSize.ArchE;
                case "B0":
                    return PdfPageSize.B0;
                case "B1":
                    return PdfPageSize.B1;
                case "B2":
                    return PdfPageSize.B2;
                case "B3":
                    return PdfPageSize.B3;
                case "B4":
                    return PdfPageSize.B4;
                case "B5":
                    return PdfPageSize.B5;
                case "Flsa":
                    return PdfPageSize.Flsa;
                case "HalfLetter":
                    return PdfPageSize.HalfLetter;
                case "Ledger":
                    return PdfPageSize.Ledger;
                case "Legal":
                    return PdfPageSize.Legal;
                case "Letter":
                    return PdfPageSize.Letter;
                case "Letter11x17":
                    return PdfPageSize.Letter11x17;
                case "Note":
                    return PdfPageSize.Note;
                default:
                    return PdfPageSize.A4;
            }
        }

        private PdfPageOrientation SelectedPdfPageOrientation(string selectedValue)
        {
            return selectedValue == "Portrait" ? PdfPageOrientation.Portrait : PdfPageOrientation.Landscape;
        }

        private WordToPdfViewModel SetViewModel()
        {
            var model = new WordToPdfViewModel();

            var contentRootPath = System.IO.Path.Combine(m_hostingEnvironment.ContentRootPath, "wwwroot");

            HttpRequest request = ControllerContext.HttpContext.Request;
            UriBuilder uriBuilder = new UriBuilder();
            uriBuilder.Scheme = request.Scheme;
            uriBuilder.Host = request.Host.Host;
            if (request.Host.Port != null)
                uriBuilder.Port = (int)request.Host.Port;
            uriBuilder.Path = request.PathBase.ToString() + request.Path.ToString();
            uriBuilder.Query = request.QueryString.ToString();

            string currentPageUrl = uriBuilder.Uri.AbsoluteUri;
            string rootUrl = currentPageUrl.Substring(0, currentPageUrl.Length - "WordToPdf".Length);

            model.HeaderHtml = System.IO.File.ReadAllText(System.IO.Path.Combine(contentRootPath, "DemoFiles/Html/Header_HTML.html"));
            model.FooterHtml = System.IO.File.ReadAllText(System.IO.Path.Combine(contentRootPath, "DemoFiles/Html/Footer_HTML.html"));
            model.HeaderHtmlBaseUrl = rootUrl + "DemoFiles/Html/";
            model.HeaderUrl = rootUrl + "DemoFiles/Html/Header_HTML.html";
            model.FooterHtmlBaseUrl = rootUrl + "DemoFiles/Html/";
            model.FooterUrl = rootUrl + "DemoFiles/Html/Footer_HTML.html";
            model.WordFileUrl = rootUrl + "/DemoFiles/Word/Word_Document.docx";

            return model;
        }
    }
}

See Also