Using HiQPdf Chromium for .NET on Azure App Service for Linux

HiQPdf Chromium for .NET is a library that can be easily integrated into Azure App Service for Linux to convert web pages and HTML strings into PDF or image formats.

The HTML to PDF conversion component uses a Chromium-based rendering engine capable of handling modern HTML, CSS and JavaScript according to the latest web standards.

HiQPdf Chromium for .NET is compatible with 64-bit applications hosted on Azure App Service 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, making it usable 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 HiQPdf.Chromium.Linux package.

After installing the package, add the using HiQPdf.Chromium; directive at the top of your source files to access the HiQPdf Chromium API.

Example code snippets and usage details are available in the Getting Started on Linux documentation section.

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

The Free F1 plan is the minimum supported tier and may be sufficient for testing or low-volume use. For development, we recommend using at least the B2 plan (2 cores, 3.5 GB RAM).

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

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

Finally, publish the application to Azure App Service for Linux.

The HiQPdf converter requires several native Linux libraries. These must be installed in the Azure App Service environment before running your application.

You can configure a startup script from the Azure Portal or use the SSH console to manually run the necessary installation commands.

After deployment, open the Azure Portal and navigate to your App Service resource.

Expand the Settings section and open the Configuration page. In the General Settings tab, locate the Startup Command field, which by default contains the command to start your .NET application (e.g., 'dotnet <your_application_name>.dll').

Insert the required library installation commands before this command, on the same line as the existing command that launches your application.

You can choose to install only the required libraries, or include optional packages such as Microsoft Core Fonts for improved compatibility with Windows platforms.

Install Only the Required Dependency Packages

To install only the required dependency packages, insert the commands below, including the ending && sign, in the Startup Command from Azure App configuration, before the existing command that launches your application, on the same line:

apt update && apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2 &&

The Startup Command should look as below, with the dotnet <your_application_name>.dll representing the initial command:

apt update && apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2 && dotnet <your_application_name>.dll

Follow the instructions below to Save the configuration and restart the application to install packages.

Install Both Required Dependencies and Microsoft Core Fonts (Optional)

If the HTML pages use fonts commonly found on Windows, installing Microsoft Core Fonts is recommended for consistent rendering.

To install both the required packages and the optional Microsoft Core Fonts, insert the command below, including the final &&, into the Startup Command field before the application startup command, on the same line:

apt update && apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2 && 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 &&

The Startup Command should look as below, with the dotnet <your_application_name>.dll representing the initial command:

apt update && apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2 && 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 &&  dotnet <your_application_name>.dll

Follow the instructions below to Save the configuration and restart the application to install packages.

Save and Apply the Startup Command

Click the Save button at the top of the page to store your startup command. Then navigate to the Overview page of your App Service and click Restart to apply the changes and install the necessary dependencies.

Although Azure Portal might indicate an immediate restart, the full installation process may take a few minutes. Refresh the browser to confirm when the app becomes responsive.

The Startup Command runs automatically at every application restart, ensuring dependencies are always available, since App Service environments do not persist installed packages after restart.

An alternative approach is to call the ConfigureRuntime(Boolean, String, String, Boolean) method in your .NET application code to configure the runtime for Azure App Service 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 it is executed again 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.

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 converter. You can call the method multiple times, but only the first call will set up the configuration and subsequent calls will be ignored.

Installation.ConfigureRuntime(false, null, "apt update && apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2");

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 the optional Microsoft Core Fonts, add the following line of code before the first call to the converter:

Installation.ConfigureRuntime(false, null, "apt update && apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2 && 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");

While the Startup Command method is preferred for consistency across restarts, you can also install dependencies manually using the SSH console.

Open the Azure Portal, navigate to your App Service and go to Development Tools -> SSH. Click the "Go" button to launch the console.

Run the following commands inside the SSH session:

Install Required Packages via SSH

Use the command below to install the required Linux packages:

apt update && apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2

Install Microsoft Core Fonts (Optional)

If your HTML content requires fonts typically found on Windows systems, install Microsoft Core Fonts with the command below:

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

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 HiQPdf ASP.NET demo application in Azure App Service for Linux.

Reference

Other Resources