Using Winnovative PDF Next for .NET in Azure Functions on Linux

Winnovative PDF Next for .NET is a library that can be integrated into Azure Functions for Linux to create and process PDF documents.

You can create PDF documents, convert HTML, Word, Excel, RTF and Markdown documents to PDF, extract text and images from existing PDF documents, perform text search operations on PDF documents and convert PDF pages to images.

Winnovative PDF Next for .NET is compatible with 64-bit applications hosted on Azure Functions for Linux. Before running your application, additional system packages must be installed in the Azure environment. The next sections provide detailed setup instructions.

The library targets .NET Standard 2.0, allowing it to be used in any .NET Core application that supports this standard.

Create a new .NET project in Visual Studio and use the NuGet Package Manager to add a reference to the Winnovative.Pdf.Next.Linux NuGet metapackage which will install all the library components.

To install only specific components of the Winnovative PDF Next library you can add references to the corresponding NuGet packages. You can find more details about the available packages in the Getting Started on Linux documentation section.

After installing the package, add the using Winnovative.Pdf.Next; directive at the top of your source files to access the Winnovative PDF Next API.

Code examples and usage details can be found in the Getting Started on Linux documentation section.

Deploying to Azure Functions on Linux is more challenging than to Azure App Service. The file system is read-only except for certain directories such as /tmp and runtime files are deployed without execution permissions by default.

The HTML to PDF Converter component requires several native Linux libraries. These must be installed in the Azure App Service environment before running your application.

The PDF Processor component has no additional dependencies but it still requires copying the runtime to a writable location where you can grant execute permission. The other components don't require any additional setup.

The Winnovative PDF Next library provides an API to install the required dependencies and perform the necessary configuration steps.

The easiest approach is to call the InstallationConfigureRuntime(Boolean, String, String, Boolean) method in your .NET application to configure the runtime for the HTML to PDF Converter component running in Azure Functions on Linux.

This method allows you to specify a Bash script that will be executed before the first HTML to PDF or image conversion. It tracks whether the script has already run and ensures that it runs again only after the application restarts.

You can choose to install only the required libraries or include optional packages such as Microsoft Core Fonts to ensure consistent rendering when using fonts commonly found on Windows platforms.

To use the PDF Processor component, you can call the PdfProcessorInstallationConfigureRuntime(Boolean, String) method in your .NET application to configure the runtime for the PDF Processor component running in Azure Functions on Linux.

Install Only the Required Dependency Packages

To install only the required dependency packages, add the following line of code before the first call to the HTML to PDF or HTML to Image converter. You can call the method multiple times, but only the first call sets up the configuration. Subsequent calls will be ignored.

Installation.ConfigureRuntime(true, null, "apt update && apt install -y libnss3 libatk-bridge2.0-0 libcairo2 libpango-1.0-0");

Additionally, to use the PDF Processor component, add the following line of code before the first call to a PDF Processor component. You can call the method multiple times, but only the first call sets up the configuration. Subsequent calls will be ignored.

PdfProcessorInstallation.ConfigureRuntime(true, null);

Install Both Required Dependencies and Microsoft Core Fonts (Optional)

If your HTML content uses fonts commonly found on Windows systems, installing Microsoft Core Fonts is recommended to ensure consistent rendering.

To install both the required packages and Microsoft Core Fonts, add the following line of code before the first call to the HTML to PDF or HTML to Image converter:

Installation.ConfigureRuntime(true, null, "apt update && apt install -y libnss3 libatk-bridge2.0-0 libcairo2 libpango-1.0-0 wget && wget -O /tmp/ttf-mscorefonts-installer_3.8_all.deb http://ftp.de.debian.org/debian/pool/contrib/m/msttcorefonts/ttf-mscorefonts-installer_3.8_all.deb && apt install -y /tmp/ttf-mscorefonts-installer_3.8_all.deb fontconfig && fc-cache -f -v");

HTML to PDF conversion can be resource-intensive depending on the complexity of the content, so proper sizing of the hosting plan is important.

When publishing, select the App Service plan or Premium as the Plan Type in the Visual Studio publish profile wizard. The Consumption plan is not suitable for running the converter.

The minimum supported hosting plan is B2 (2 cores, 3.5 GB RAM). The Free plan is also not suitable for Azure Functions running the converter.

For production scenarios or heavy workloads, a Premium plan such as P1v3 (2 vCPUs, 8 GB RAM) or higher is strongly recommended.

When configuring the publish profile, select Portable as the target runtime.

Finally, publish the application to Azure Functions on Linux.

Although configuring the environment through .NET code is the preferred method for maintaining consistency across restarts, you can alternatively install the required dependencies manually using the SSH console. Follow the steps below to configure the Linux environment for Azure Functions.

Set HTML Loader Path

Before publishing your application, set the full path to the winnovative_loadhtml executable in your .NET code. This path should point to a writable location such as /tmp where the runtime files will be copied later.

converter.HtmlLoaderFilePath = "/tmp/winnovative_runtimes/linux-x64/native/winnovative_loadhtml";

Set PDF Processor Path

If you are also using the PDF Processor, set the full path to the winnovative_pdfprocessor executable in your .NET code. This path should point to a writable location such as /tmp where the runtime files will be copied later.

pdfProcessorComponent.PdfLoaderFilePath = "/tmp/winnovative_runtimes/linux-x64/native/winnovative_pdfprocessor";

Publish the Azure Function on Linux

Publish your Azure Function using the same deployment options previously described for the .NET code-based configuration method.

After the application is published, continue with the environment setup to install the required packages as described in the steps below.

Install Required Linux Packages via SSH

Open the Azure Portal, navigate to your Azure Function, then go to Development Tools → SSH and click the Go button to open the SSH console.

Run the following command to install the required Linux packages:

apt update && apt install -y libnss3 libatk-bridge2.0-0 libcairo2 libpango-1.0-0

Install Microsoft Core Fonts (Optional)

If your HTML content uses fonts commonly found on Windows systems it is recommended to install Microsoft Core Fonts using the following command:

apt update && apt install -y wget && wget -O /tmp/ttf-mscorefonts-installer_3.8_all.deb http://ftp.de.debian.org/debian/pool/contrib/m/msttcorefonts/ttf-mscorefonts-installer_3.8_all.deb && apt install -y /tmp/ttf-mscorefonts-installer_3.8_all.deb fontconfig && fc-cache -f -v

Copy Runtime and Grant Execution Permission

Copy the runtime files to the /tmp directory:

cp -r /home/site/wwwroot/winnovative_runtimes /tmp/winnovative_runtimes

Then grant execution permission to the loader binary:

chmod +x /tmp/winnovative_runtimes/linux-x64/native/winnovative_loadhtml

If you are also using the PDF Processor component grant execution permission to its binary as well:

chmod +x /tmp/winnovative_runtimes/linux-x64/native/winnovative_pdfprocessor

With all dependencies installed and configurations completed, your application is ready to run. You can also follow the same procedure to publish and test the Winnovative PDF ASP.NET demo application in Azure App Service for Linux.

Reference

Other Resources