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 (October 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.

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.

Copying files to a Visual Studio project, selecting 'Include in Project' in Solution Explorer, does not guarantee they will be deployed to the output directory. Visual Studio seems to ignore certain files. You may need to set the 'Copy to Output Directory' property for each file in Solution Explorer, or edit the project file directly.

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

This walkthrough is based on Visual Studio 2015

  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 Gecko 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.

    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. Deploy the XULRunner folder:

    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. Publish to Azure:

    Right-click on your Web Role project and select "Publish to Microsoft Azure..." to deploy the solution. Publishing can be a little buggy with Visual Studio 2015. It may hang in which case you will have to restart Visual Studio. It generally works second time around.

    When deployment has completed (it will take a few minutes), 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.

  8. Troubleshooting:

    "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 3 "Deploy the XULRunner Folder" to see if anything was missed.

    To troubleshoot deployment issues you can also log in to an Azure Web or Worker role using a Remote Desktop Connection.

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 5 "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.