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 (November 2016), 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".

The Microsoft Azure platform offers a variety of ways to host a website. For ABCpdf we recommend using an Azure Virtual Machine though you can also use ABCpdf with an Azure Web Role or Worker Role as a Cloud Service.

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 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, Gecko and the XULRunner folder are installed correctly. Please see the documentation on Manual Installation for details.

Azure App Service

ABCpdf will work under Azure App Services but permissions do not allow HTML conversion. If this is a feature you require you should use one of the other options detailed here.

Deploying as an Azure Cloud Service Web Role using Visual Studio

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

This walkthrough is based on Visual Studio 2015 Community Edition

  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 Web Role project 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:


    		<%@ 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:

    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 Azzure..." again to bring the above dialog back up. Click "Publish" again.

    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.

  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.