ABCpdf .NET Azure Deployment Guide

Please be aware that the Azure deployment process is liable to change. Although the guides presented here worked at the time we tested them (most recently March 2021), you may find it's necessary to make changes in order to get things working.

ABCpdf is supported on the following platforms:

The preferred installation method is using the ABCpdf NuGet package.

Azure App Service

ABCpdf works fine in Azure App Services.

If you want to do HTML conversion you will need to use the ABCWebKit engine. This engine was introduced in ABCpdf 12.1 primarily for the purpose of performing HTML conversion in Azure App Services.

You can use the other engines in an Azure Virtual Machine or Cloud Service but not under Azure App Services as they are hampered by Azure App Service sandbox restrictions that effectively disable the ABCChrome, ABCGecko and MSHTML engines.

To use ABCpdf for WebKit engine the minimum configurations options for your app service must be as follows:

  • The runtime stack must set to .NET (preferably .NET 5).
  • The operating system must be Windows.
  • The minimum app service plan supported is Basic B1.
  • The App Service platform must be 64-bit.

Here is a walkthrough from code to cloud using an example app from our GitHub repository that performs a HTML to PDF conversion using the ABCWebKit engine.

  1. Clone the example repository

    Go to our GitHub repository and copy the clone link.

    Clone Repo 1

    Now open Visual Studio (preferably 2019) and use the URL to clone.

    Clone Repo 2

    Clone Repo 3

    Restore the NuGet Packages - this will restore the ABCpdf and ABCWebKit NuGet packages and may take a minute or so

    Restore Nuget packages

    When running in an App Service ABCpdf will require the license key to be installed in your code using the XSettings.InstallLicense method. For the example code from the repository paste your license code between the quotes on line 31 of Startup.cs.

    Finally build the solution and run locally to test. If everything works well you may proceed to test the app in the cloud. So next we need to create and configure an App Service to publish to.

  2. Create your App Service

    This section will walk you through the correct configurations for ABCWebKit to function correctly.

    Select "Create App Service" in your Azure Portal and you will get the following screen. Ensure that you set the runtime stack to .NET (preferably 5) and the operating system to Windows. Also the App Service plan must be Basic B1 or higher so you may need to click "Change size".

    Create-HTML to PDF Azure App Service using ABCpdf

  3. Ensure you have a supported App Plan

    If you did select change size then following screen will appear where you can select the B1 SKU. Be aware that at the time of writing the Basic B1 App Service plan is not free even in the development tier. Our advice is to cancel the attached subscription while you do not need it and re-enable when you do, otherwise you will incur charges whether the App Service is active or not.

    Set App Plan to Basic ABCpdf

  4. Ensure the App Service Platform is 64-bit

    Once you have reviewed and created your App Service you will need to go to the resource and click "Configuration" the "General Settings". In this panel you will likely need to change the "Platform" to 64-bit.

    Configure App Service Platform

  5. Publish to your Azure App Service

    Right-click on the project and select "Publish..."

    Publish App Service Step 1

    Select "Azure"...

    Publish App Service Step 2

    Select Azure App Service (Windows)...

    Publish App Service Step 3

    After you've signed in you will be able to select the app service you created in the Azure poertal earlier...

    Publish App Service Step 4

    For simplicity we'll use local publish settings...

    Publish App Service Step 5

    Visual Studio will then check the config and ultimately display "Ready to Publish" at which point you may simple press the publish button...

    Publish App Service Step 6

    After some time - typically 5-10 minutes you should see the following message.

    Publish App Service Step 7

    Now when you navigate to the site specified in the publish dialog you, after a short delay, get output similar to the following.

    Publish App Service Step 8

Azure Pipelines

You may use Azure Pipelines for deployment to any of the above platforms using the ABCpdf NuGet package. Do ensure that you:

  • Reference the desired version of ABCpdf in the project file's PackageReference section or for legacy projects in the packages.config.
  • For legacy projects you will need to add the packages.config to your source code control.
  • Include the NuGet restore task prior to any build actions for the pipeline.

Additionally you can specify allowed versions to enable same-version updates automatically. The following examples will always restore the latest version of ABCpdf 12 package but will not upgrade to version 13:

Project file example

<ItemGroup>
  <PackageReference Include="ABCpdf" version="[12,13]" />
</ItemGroup>

packages.config example

<packages>
  <package id="ABCpdf" version="12.0.0.0" allowedVersions="[12,13]" />
</packages>

Azure Virtual Machines

The setup of your VM will depend upon how you want to deploy your projects. We'll give you an overview of creating an ABCpdf Web App project using our NuGet package and deploying it to your VM from within Visual Studio. Of course you can also use Azure DevOps to deploy directly from source control

  1. Configuring your Windows Azure Virtual Machine

    You will need to set up your VM and ensure it is configured for IIS and Web Deploy. To do this you will need to:

    1. Go to your Azure Portal to create your desired flavor of Windows Server VM.
    2. Setup IIS on your virtual machine.
    3. Install WebDeploy by downloading and running the installer. NB you must install all features of the IIS Deployment Handler during setup. We've found this more reliable that installing via the Web Platform Installer.

    4. After WebDeploy installation completes ensure that both the Web Deployment Agent (MsDepSvc) and Web Management (WmSvc) services are running and set to Automatic startup. Re-installation has been known to fix some issues here.

    5. In your Azure Portal configure your VM's Networking properties to create inbound rules to open the following ports: 80 (HTTP), 443 (HTTPS), 3389 (RDP), 22 (SSH), and 8172 (WebDeploy). NB for security you should limit the sources that can access some of these ports.

      As a sanity check use a port checker to check that, in particular, ports 80 and 8172 are indeed open.

    6. Finally open IIS Manager and ensure that right-clicking on the Default Web Site now displays "Deploy" as a sub-menu. If it doesn't try re-installing WebDeploy and re-checking the services in step iii.

  2. Create your project

    You will need to have installed the Microsoft Azure SDK for .NET using the Visual Studio Installer.

    Open Visual Studio and create a new project (File > New Project). When the "Create a New Project" dialog appears select ASP.NET Web Application and click "Next".

    Name your project and click "Create"

    Configure Web App

  3. Complete the application by following the steps here...

  4. Create a Deployment Profile

    You can create a Web Deployment profile from within Visual Studio. However we have found this buggy and a more reliable method is to create a publish profile within your VM. Simply log in to your virtual machine and right-click on the desired website in IIS Manager and select Deploy->Configure Web Deploy Publishing. In the resultant dialog click Setup...

    Web Deploy settings

    This will write a .publishsettings profile file to the VM desktop that can be imported into visual studio.

Should you have more complex platform requirements we have created some documentation on Manual Installation.

Azure Cloud Service

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

A Cloud Service is analogous to a Virtual Machine. A Web Role you install on your Cloud Service is analogous 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 using the Visual Studio Installer, this guide also assumes you will be using the NuGet package manager.

  2. Create a new Azure Cloud Service (classic) for your desired .NET Framework version

    Open Visual Studio and create a new project (File > New Project). When the "Create a New Project" dialog appears select Azure Cloud Service (classic) and click "Next".

    Creat Cloud Service Class Screen

     
  3. Configure the project

    In the "Configure the Project" screen, type a name for your Cloud Service project, select your target .NET target framework and click "Create".

    Configure Cloud Service Project

  4. Create a Web Role

    Now you are prompted to add your desired roles for your project. In our example we will create a Web Role but you can use any role depending on your requirements. Select C#  ASP.NET Web Role and click the right ">" arrow. Click the pencil icon to give your Web Role an appropriate name then click "OK".

    Add Cloud Service Web Role

  5. Complete the application by following the steps here...

  6. Deployment to Azure as a Cloud Service

    With your solution thus configured, you may deploy in a number of ways. Right-clicking on the cloud service project in Solution Explorer and selecting publish will enable you to publish as a cloud service. You will be presented with the following screens.

    First you will need sign in to your Microsoft Azure Account and select your subscription...

    Azure Sign in

    Once you have signed in click "Next" and you will be prompted to create a cloud storage. Type a suitable name and select your desired location then click create.

    Cloud Service Storage

    Once you have created your cloud storage you can set your publish settings.

    Cloud service role settings

    If you click on "Enable Remote Desktop for all roles" you can then setup an RDP account:

    Configre remote desktop

    Once you click "OK" and "Next" you will be presented options for diagnostics. By all means enable them we have found that they tend to slow down the deployment.

     

    In the Publish dialog you can now click "Next" and enable diagnostics if you desire. Click "Publish" will now present you with a Publish  Summary.

    Azure Cloud Service Publish Summary

    Click publish and you will see a progress dialog:

    Publish Cloud Service Summary

    One disadvantage of Cloud Service apps is that they can take some time to deploy. Once it is complete you will be presented with the following:

    Cloud service deployment complete

    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.

  7. Troubleshooting:

    If you have initial deployment issues and you reused a previous Cloud Service you may want to consider creating a new profile 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.

Creating and Testing an ABCpdf Web Application

  1. Create an ASP.NET Web Application

    To keep things simple we are going to create an empty project to which we will add just one aspx file. So click "Empty" then the "Create" button.

    Configure ASP.NET Project
  2. Install ABCpdf .NET Using NuGet

    In Tools > NuGet Package Manager > Manage NuGet Packages for Solution... click "Browse" and in the search box type "ABCpdf" and press enter. Now select the the ABCpdf package and tick the checkbox by your Web Role project and click "Install". Click "OK" on any prompts that appear.

    Install ABCpdf using NuGet

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

  3. Create a test page

    Right-click on the Web Role project in Solution Explorer and select "Add" then "HTML Page" and name it default.aspx. Open the file and replace its contents with the following code. Replace "INSERT_YOUR_LICENSE_HERE" with your license key.

    [C#]

    <%@ Page Language="C#" Debug="true" AutoEventWireup="true" %> 
    <%@ Import Namespace="WebSupergoo.ABCpdf11" %>
    <%@ Import Namespace="System.IO" %>
    <script runat="server">
        public void Page_Load(Object sender, EventArgs E) {
            string url = Request.QueryString["url"];
            if (!string.IsNullOrEmpty(url)) { 
                XSettings.InstallLicense("INSERT_YOUR_LICENSE_HERE");
                string thePath = Path.GetTempFileName();
                using(Doc theDoc = new Doc()) { 
                    theDoc.HtmlOptions.Engine = EngineType.Chrome;
                    int id = theDoc.AddImageUrl(url);
                    while(theDoc.Chainable(id)) {
                        theDoc.Page = theDoc.AddPage();
                        id = theDoc.AddImageToChain(id); 
                    }
                    theDoc.Save(thePath); 
                }
                FileInfo fi = new FileInfo(thePath);
                Response.ClearHeaders();
                Response.Clear();
                Response.ContentType = "application/pdf";
                Response.AddHeader("content-length", fi.Length.ToString());
                Response.WriteFile(thePath);
                Response.End();
            }
        }
    </script> 
    <html>
        <head>
            <title>ABCPdf Test Page</title>
        </head>
        <body>
            <form>
                <label for="url">URL</label><br>
                <input type="text" name="url" /><br>
                <input type="submit" value="Submit" />
            </form>
        </body>
    </html>

    For debugging 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":

    <system.web>
    <customErrors mode="Off" />
    </system.web>
  4. Test locally prior to deploying.

    Now we can build and test the application using the debugger. Fire it up and type in a domain name and press submit:

     

    And if all goes well you should see that site as a PDF in your browser!

  5. Deploy

    Return to the deployment guide for your platform to finally deploy the application to Azure.