ABCpdf .NET Azure Deployment Guide

ABCpdf is supported on the following platforms:

Azure App Services
Azure Virtual Machines (recommended)
Azure Cloud Services (classic)

The preferred installation method is using the ABCpdf NuGet package.

Neither Azure nor Visual Studio are static - both are in a process of continual update.

As such - if you find idiosyncrasies which we have not documented - please do let us know.

Azure App Service

ABCpdf works fine in Azure App Services. This guide was last tested July 2023 using Visual Studio 2022 and .NET 7.0.

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 ABCWebKit engine the minimum configurations options for your app service must be as follows:

The runtime stack must set to .NET 5, .NET 6 or .NET 7.
The operating system must be Windows.
The minimum app service plan supported is Basic B1.
The App Service platform must be 64-bit.

While ABCWebKit bypasses many of the problems created by the Azure Sandbox, it is not completely immune to them. Most notably, as detailed on the sandbox restrictions page, custom fonts typically get substituted using system-installed fonts because of GDI API limitations. We do not find that Base64 embedded fonts, or web fonts work correctly - do not believe everything you read on StackOverflow. However fonts converted into SVG using Transfonter generally look good. Arial and Courier tend to provide good output. Times can look a bit odd at 12pt but increasing or reducing the size often improves things markedly.

The Azure Sandbox is under continual development so things do change. If you find a good approach please do tell us. Nevertheless, if you want the best quality HTML conversion, the way to get it is to use a full featured Azure VM or Cloud Service rather than a budget sandboxed offering.

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.

Clone the example repository

Go to our GitHub repository and copy the clone link.

Now open Visual Studio (we test with 2019 & 2022) and use the URL to clone.

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

You may wish to update the NuGet packages to the current release, but we would suggest you test first using the ones referenced in the package.

When running in an App Service ABCpdf will require the license key to be installed in your code using the XSettings.InstallLicense method.

In the example code from the repository you can simply paste your license in where XSettings.InstallLicense is called in Startup.cs.

If you do not yet have a license there are notes in the code detailing how to get a trial license you can use for deployment.

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.
Create your App Service

Select "Create App Service" in your Azure Portal - a "Web App" not a "Static Web App" - and you will get the following screen.

Ensure that you set the runtime stack to .NET (preferably 7) and the operating system to Windows.

The App Service plan must be Basic B1 or higher so do not select a free service.
Ensure you have a supported App Plan

Please make sure you have selected a B1 or higher plan. The cheaper and free services do not support the APIs needed.

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.
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.
Publish to your Azure App Service

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

Select "Azure"...

Select Azure App Service (Windows)...

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

The publish profile is created...

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

After some time - typically a few minutes - you should see the following message.

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

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

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.
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"
Complete the application by following the steps here...
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...

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.

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.
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".
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".
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".
Complete the application by following the steps here...
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...

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.

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

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

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.

Click publish and you will see a progress dialog:

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:

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

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

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.

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>

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!
Deploy

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

ABCpdf .NET