ABCpdf .NET Azure Deployment Guide

Please be aware the Azure deployment process is liable to change. Although the guides presented here worked at the time we tested them (most recently November 2017), you may find it's necessary to make changes in order to get things working. Also note the distinction between "App Service" and "Cloud Service".

Microsoft Azure is not one thing. It is a set of virtual machines and platforms. It offers a variety of ways to host a website - not just one. For ABCpdf we recommend using an Azure Virtual Machine though you can also use ABCpdf with an Azure Cloud Service Web Role or Worker Role.

A Cloud Service is one step up from a standard Web App. It allows greater control over the setup process and can host one or more web sites. Like Web Apps it can be scaled up or down using simple rules.

The deployment guides on this page assume you have already signed up for a Microsoft Azure account and installed the Microsoft Azure SDK for your development environment.

In general ABCpdf will work on any of these. However to enable HTML to PDF conversion using the ABCChrome or Gecko engine you need a setup that will allow Remote Desktop access such as an Azure Cloud Service.

For more details on the different types of Azure services please see this guide.

Azure Virtual Machines

ABCpdf can be installed or deployed to a Microsoft Azure VM. This is the simplest method of installing on Microsoft Azure.

All you need to do is to log in to your virtual machine, download ABCpdf from our website and install as you would normally.

This is our recommended method of installation on Azure.

Another option, the Web Publishing method (web deploy), requires more effort to set up. You'll need to configure IIS on the VM, install Web Deploy for hosting servers, and add an endpoint for the service.

You'll need to ensure ABCpdf is installed correctly. If you want them you will need to ensure ABCChrome, or Gecko and the XULRunner folder, are installed correctly. Please see the documentation on Manual Installation for details.

Azure App Service Web App (Web Apps)

ABCpdf will work fine in a default Web App but permissions do not allow HTML conversion.

If this is a feature you require you should use one of the other options detailed here.

Azure Cloud Service Web Role

Please note that you will need a Trial or Professional license to run ABCpdf on a cloud server. You cannot use a Standard license.

This walkthrough is based on Visual Studio 2015 Community Edition with Gecko. However the process is almost identical for ABCChrome and this has been tested with Visual Studio 2017.

A Cloud Service is analagous to a Virtual Machine. A Web Role you install on your Cloud Service is analagous to a web site on the Virtual Machine. So in your Azure Portal, the setup procedure detailed here will result in a Cloud Service containing a Web Role exposing a site.

  1. Prerequisites:

    In addition to a Microsoft Azure account and installation of the Microsoft Azure SDK for .NET , this guide also assumes you will be using the NuGet package manager.

  2. Create a New Azure Cloud Service for .NET 4.0 or 4.5

    Open Visual Studio and create a new project (File > New Project). When the New Project dialog appears select .NET Framework 4.0  or 4.5 (roles are only supported for these versions of .NET). Now in the left-hand tree view expand C# or Visual Basic and select "Cloud" then "Azure Cloud Service". Type a name for the project and click "OK":

    Azure Screenshot - New Cloud Service

  3. Add the ASP.NET Web Role

    In the next dialog add ASP.NET Web Role and name it accordingly and click "OK":

    Screenshot - Add ASP.NET Web Role

    In the following dialog select the template you wish to use and click "OK":


  4. Install ABCpdf .NET and ABCGecko Runtime Using NuGet

    In Tools > NuGet Package Manager > Manage NuGet Packages for Solution click "Browse" and in the search box type "ABCpdf" and press enter.:

    Screenshot - Install ABCpdf & Gecko with NuGet

    Select the ABCpdf package and tick your project then click the "Install" button.

    Do the same for the ABCpdf.ABCGecko package:

    Install ABCGecko Package

    While you are in the NuGet package manager it may be prudent to check the "Installed" section and uninstall any unnecessary packages that the wizard may have added. This will speed up deployment.

  5. Reconfigure the XULRunner folder Deployment

    You should now have a folder named XULRunner38_0 (the 38 refers to the version - it may be different for your version) in the Web Role's project directory. Delete it. We'll reference a copy from the NuGet package folder instead.

    Once the folder has been deleted, right click on the Azure Cloud project (not the Web Role) in the Solution Explorer and select 'Unload Project'. Right-click again and select to edit the project file, and add the following ItemGroup, taking care to update the version number from the packages:

        <None Include="..\packages\ABCpdf.ABCGecko.\content\XULRunner38_0\**\*.*">

    Ensure that the path is correct in the packages folder under the solution. Save the changes and reload the web role project.

    You may notice the XULRunner38_0 folder reappear. This time it will contain links to resources in the NuGet package directory and help ensure the XULFolder is deployed correctly. Do not delete it.

  6. Create a test page:

    Add a default.aspx page to the project and paste in the following code, replacing "INSERT_YOUR_LICENSE_KEY_HERE" with your license key. If you do not have a purchased license you can use a trial license copied from the PDFSettings application which comes with ABCpdf:


    		<%@ Page Language="C#" Debug="true" AutoEventWireup="true" %>
    <%@ Import Namespace="WebSupergoo.ABCpdf9" %>
    <%@ Import Namespace="System.IO" %>
    <script runat="server">
    public void Page_Load(Object sender, EventArgs E) {
      if (String.Equals("123", Request.ServerVariables["QUERY_STRING"])) {
        string thePath = Path.GetTempFileName();
        using(Doc theDoc = new Doc()) {
          theDoc.HtmlOptions.Engine = EngineType.Gecko;
        FileInfo fi = new FileInfo(thePath);
        Response.ContentType = "application/pdf";
        Response.AddHeader("content-disposition", "attachment; filename=example.PDF");
        Response.AddHeader("content-length", fi.Length.ToString());

    <p><a href="?123">Get web page as PDF...</a></p>


    		<%@ Page Language="vb" Debug="true" AutoEventWireup="true" %>
    <%@ Import Namespace="WebSupergoo.ABCpdf9" %>
    <%@ Import Namespace="System.IO" %>
    <script runat="server">
      Public Sub Page_Load(sender As Object, E As EventArgs)
        If String.Equals("123", Request.ServerVariables("QUERY_STRING")) Then
          Dim thePath As String = Path.GetTempFileName()
          Using theDoc As New Doc()
            theDoc.HtmlOptions.Engine = EngineType.Gecko
          End Using
          Dim fi As New FileInfo(thePath)
          Response.ContentType = "application/pdf"
          Response.AddHeader("content-disposition", "attachment; filename=example.PDF")
          Response.AddHeader("content-length", fi.Length.ToString())
        End If
      End Sub
    <p><a href="?123">Get web page as PDF...</a></p>

    For testing purposes you'll want to disable custom error reporting now. Add a customErrors tag to the system.web section of your web.config file and set the mode attribute to "Off":

    <customErrors mode="Off" />
  7. Deploy to Azure:

    Right-click on your Web Role project name in Solution Explorer and select "Publish to Microsoft Azure...". You will need sign in to your Microsoft Account.

    Deployment Step One

    Once you have signed in click "Next":


    The "Cloud Service" dropdown list will be populated with any Cloud Services you have already created. You may also use the <Create New...> option in the dropdown in which case you will get the following dialog:

    Create Cloud Service

    The Cloud Service Name must be unique as this forms part of the URL for the Cloud Service - e.g. If the desired name is taken you will recieve an error.

    When you create a new Cloud Service in this way you may find that Visual Studio 2015 hangs on the preceding Publish dialog but the service will have been created. In this case you will have to restart Visual Studio and then the newly created Cloud Service will be present in the dropdown list.

    It is strongly recommended that you tick the boxes "Enable Remote Desktop" and "Enable Web Deploy..." to enable you to publish individual files rather than performing a time-consuming deployment after you have modified files. Set up an appropriate user and password in the Remote Desktop dialog. The password should be at least ten characters with numbers and symbols. This is important as Azure may create the deployment but reject a simple password without reporting any error. If it does this you will need to reset the password from the Azure Portal:

    Remote Destop Settings

    In the Publish dialog you can now click "Next" and enable diagnostics if you desire. Click "Next" again:

    Publish Settings

    Now click the "Publish" button. You may get an error at this point about the storage account. Ignore this and right-click the role once more in Solution Explorer and click "Publish to Microsoft Azure..." again to bring the above dialog back up. Click "Publish" again. If you do create a storage account you can always use the Azure Portal to delete it later.

    Publishing the deployment may take some time - 10-15 minutes. Check the "Microsoft Azure Activity Log" window for errors. Common errors include connection to server lost requiring restarting the deployment.

    When deployment has completed (it may take some time), navigate to the test page on your site and click the 'Get web page as PDF...' link. If the project was deployed successfully you should receive a single page PDF of the target website.

    Deployment is time consuming because it recreates a Virtual Machine (VM) with a Virtual Hard Drive (VHD) containing the OS, IIS and your files and configuration. It is for this reason we recommend enabling Web Deploy to upload files over a Remote Desktop Connection.

    To connect via Remote Desktop, use Azure Portal to display the Web Role instance within the Cloud Service. Then click on the small 'Connect' button that appears at the top right. This will provide you with an RDP file you can use to connect.

  8. Troubleshooting:

    The page displays an Exception "Gecko engine hit an error it was unable to recover from. Possible causes: XULRunner folder is corrupt or is from another version of ABCpdf."

    If you receive the error message above, or another Gecko related error message, these can indicate an incomplete deployment of the XULRunner Folder. Please revisit step 5 "Reconfigure the XULRunner folder Deployment" to see if anything was missed.

    If you have initial deployment issues and you reused a previous Cloud Service you may want to consider creating a new using the Publish to Azure Wizard above to ensure no legacy settings are retained.

    Further deployment issues can usually be resolved by restarting the Cloud Service from Microsoft Azure Dashboard web page. Additionally you may also attempt to resolve the issues by connecting to your service instance using a Remote Desktop Connection if you enabled this facility.

Azure Worker Roles

Azure Worker Roles are similar to Web Roles, except they do not have IIS installed by default. Please follow the guide for deploying to a Web Role, but miss out step 6 "Create a test page". To verify the project has deployed correctly you'll need to find an alternative method, depending on how your project communicates with the worker role.