Deployment to Microsoft Azure

Microsoft Azure provides a multitude of services, setups and deployment options. Most important for us, are the following services:

• Azure Web Apps

• Azure Cloud Services

• Azure Virtual Machines

• Azure Functions

Azure App Service (which, in the past, was called Azure Websites) is a managed platform. This means that Azure takes care of application deployment and management, while the developer only needs to concentrate on app development. Azure App Service supports applications defined by Azure as "Web Apps", "Mobile Apps", "API Apps" and "Logic Apps".

Azure Cloud Services is a platform that allows developers access to the underlying virtual machines and still manages the application container and deployment automatically. This offers a much more flexible solution than Azure App Service.

Azure Virtual Machines give you full control over application management and deployment. For projects that may require substantial modifications to the technology stack in the future, or for people worried about being locked into a single vendor, the extra work required to launch and maintain Virtual Machines might be worth it.

Azure Functions allows you to run small pieces of code (called “functions”) without worrying about application infrastructure. With Azure Functions, the cloud infrastructure provides all the up-to-date servers you need to keep your application running at scale.

We will start with the conclusion (read the paragraphs below if you need to know the complete explanation):

SelectPdf (v18.3) or above works on Azure Web Apps, on Windows, starting with the Basic plan (does not work with Free/Shared plans). The Web Apps version uses a restricted rendering engine and because of that, some features are not available. To name a few: no support for web fonts, support only for single page PdfHtmlElement objects, no support to exclude elements from conversion.

The html to pdf conversion on Azure Web Apps platorm is done using a different rendering engine. SelectPdf's regular rendering engine performs a lot of GDI calls and because of the restrictions from the platform, it does not work. The restricted rendering engine can be controlled using 2 properties: EnableRestrictedRenderingEngine and EnableFallbackToRestrictedRenderingEngine of the GlobalProperties class. By default, the restricted engine is disabled, but the fallback to it is enabled on Microsoft Azure Web Apps platform. So, with the default settings, the restricted engine will be activated on Microsoft Azure Web Apps platform. To enable it on other platforms (like personal dev machines), set EnableRestrictedRenderingEngine to True.

Detailed explanation:

All Azure Web Apps (as well as Mobile App/Services, WebJobs and Functions) run in a secure environment called a sandbox. Each app runs inside its own sandbox, isolating its execution from other instances on the same machine as well as providing an additional degree of security and privacy which would otherwise not be available. The sandbox mechanism aims to ensure that each app running on a machine will have a minimum guaranteed level of service; furthermore, the runtime limits enforced by the sandbox protects apps from being adversely affected by other resource-intensive apps which may be running on the same machine.

The sandbox generally aims to restrict access to shared components of Windows. Unfortunately, many core components of Windows have been designed as shared components: the registry, cryptography, and graphics subsystems, among others. For the sake of radical attack surface area reduction, the sandbox prevents almost all of the Win32k.sys APIs from being called, which practically means that most of User32/GDI32 system calls are blocked. For most applications this is not an issue since most Azure Web Apps do not require access to Windows UI functionality (they are web applications after all). However one common pattern that is affected is PDF file generation from HTML. Since SelectPdf uses a lot of GDI calls during the HTML to PDF conversion, the default rendering engine does not work on Azure Web Apps.

To fix the problem, SelectPdf has, starting with version 18.3, a new (more restricted) rendering engine, that works on Microsoft Azure Web Apps platform. It requires Windows as operating system and an App Service Plan starting with Basic (does not work with Free/Shared plans). Using a Standard or Premium plan will make conversions faster.

Using a restricted rendering engine causes some features not to be available. To name a few: no support for web fonts, support only for single page PdfHtmlElement objects, no support to exclude elements from conversion.

SelectPdf works without any restrictions if Azure Cloud Services with Web Roles are used for deployment.

SelectPdf works without any restrictions if Azure Virtual Machines are used for deployment.

SelectPdf works with Azure Functions, starting with Azure Functions SDK 3.0. Due to platform restrictions, SelectPdf uses a more restricted rendering engine with Azure Functions. The hosting plan should be Premium or App Service Plan, starting with Basic. SelectPdf will not work with an Azure Consumption Plan nor with a Free or Shared App Service Plan.

Using a restricted rendering engine causes some features not to be available. To name a few: no support for web fonts, support only for single page PdfHtmlElement objects, no support to exclude elements from conversion.

Other Resources