How to Generate PDFs in ASP.NET Core on Azure Using wkhtmltopdf and DinkToPDF

Generating a PDF from HTML in ASP.NET Core can work perfectly during local development and still fail after the same application is deployed to Azure App Service.

The problem is often not the C# code itself.

PDF libraries such as wkhtmltopdf and DinkToPDF depend on native components, system resources, fonts and operating-system-level behavior. Azure App Service introduces a different execution environment, which can expose dependency or resource issues that were not visible locally.

In this guide, we will cover:

• How to generate PDFs in ASP.NET Core using wkhtmltopdf
• How to use DinkToPDF with .NET Core
• How [page] and [toPage] work in DinkToPDF
• Why PagesCount = true matters
• How to configure DinkToPDF headers and footers
• Why PDF generation may fail after Azure deployment
• Azure Windows vs Linux considerations
• Common timeout, font and dependency issues
• What our testing showed on different Azure App Service configurations

Quick Answer: How Do You Generate a PDF in ASP.NET Core on Azure?

ASP.NET Core applications can generate PDFs using tools such as wkhtmltopdf, wrappers such as DinkToPDF, or MVC-oriented libraries such as Rotativa.

The implementation itself is only part of the decision. For Azure-hosted applications, also evaluate:

For basic HTML-to-PDF generation, wkhtmltopdf can be used directly through a .NET wrapper.

For greater configuration control, DinkToPDF provides a .NET API around wkhtmltopdf, including support for paper size, orientation, margins, headers, footers and page counters.

2026 Technical Note: Is wkhtmltopdf Still Maintained?

The official wkhtmltopdf repository was archived on January 2, 2023 and is now read-only. Its latest listed release is version 0.12.6.

This does not mean every existing wkhtmltopdf implementation needs to be replaced immediately.

Existing applications may continue using it when:

• The implementation is already stable
• PDF templates are thoroughly tested
• The runtime environment is controlled
• Replacing the rendering engine would require substantial redevelopment

However, teams starting a new long-term application should also evaluate actively maintained PDF-generation approaches before making wkhtmltopdf a new architectural dependency.

What We Tested for ASP.NET Core PDF Generation on Azure

The recommendations in this guide are based partly on practical testing carried out while deploying ASP.NET Core PDF-generation examples to Azure.

The results described in this article should be treated as tested implementation experience rather than universal behavior for every Azure configuration.

Different .NET versions, package versions, App Service tiers and native dependencies can change the result.

DinkToPDF vs wkhtmltopdf vs Rotativa for ASP.NET Core PDF Generation

Choosing between wkhtmltopdf, DinkToPDF and Rotativa depends primarily on how the PDF is created and how much configuration the application requires.

DinkToPDF is a C# wrapper around wkhtmltopdf, rather than an independent PDF-rendering engine.

Therefore, when wkhtmltopdf cannot load correctly in a hosting environment, a DinkToPDF implementation can also be affected.

For an existing application, choose based on the implementation already in place and the PDF features you require.

For a new application, also consider the maintenance status of the underlying rendering technology.

How to Generate a PDF with wkhtmltopdf in ASP.NET Core

wkhtmltopdf converts HTML content into PDF documents.

ASP.NET Core applications can access it through .NET wrapper packages such as Wkhtmltopdf.NetCore.

A basic implementation involves:

Step 1: Install the .NET Package

Using Package Manager Console:

PM > Install-Package Wkhtmltopdf.NetCore

The current article explicitly hard-codes:

Version 3.0.2

I recommend removing the fixed version unless your development team confirms that this exact version remains the supported version in Satva’s repository.

Package versions should match the application’s .NET/runtime requirements.

Step 2: Generate the PDF from HTML

Use a controller or service to pass HTML into the PDF generator.

public class HomeController : Controller
{
    private readonly IGeneratePdf _generatePdf;
    private readonly ILogger<HomeController> _logger;

    public HomeController(
        IGeneratePdf generatePdf,
        ILogger<HomeController> logger)
    {
        _generatePdf = generatePdf;
        _logger = logger;
    }

    public IActionResult Index()
    {
        try
        {
            var html = "<h1 style='color:red'>Hello World</h1>";

            var bytes = _generatePdf.GetPDF(html);

            return File(
                bytes,
                "application/pdf",
                "wkhtmltopdf-example.pdf");
        }
        catch (Exception ex)
        {
            _logger.LogError(
                ex,
                "PDF generation failed.");

            return StatusCode(
                500,
                "PDF generation failed.");
        }
    }
}

This example is useful for confirming whether basic PDF generation works in the local environment.

public class HomeController : Controller
{
    private readonly IGeneratePdf _generatePdf;
    private readonly ILogger<HomeController> _logger;

    public HomeController(
        IGeneratePdf generatePdf,
        ILogger<HomeController> logger)
    {
        _generatePdf = generatePdf;
        _logger = logger;
    }

    [Obsolete]
    public IActionResult Index()
    {
        try
        {
            var htmlContent = "<h1 style='color:red'>Hello World</h1>";

            var bytes = _generatePdf.GetPDF(htmlContent);

            var pdfPath = Path.Combine(
                Environment.ContentRootPath,
                "PDfswkhtmltopdf.pdf"
            );

            System.IO.File.WriteAllBytes(pdfPath, bytes);

            return PhysicalFile(
                pdfPath,
                "application/pdf"
            );
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Error generating PDF");

            var errorMessage = ex.InnerException?.Message ?? ex.Message;

            var errorPath = Path.Combine(
                Environment.ContentRootPath,
                "PDfswkhtmltopdfError.txt"
            );

            System.IO.File.WriteAllText(
                errorPath,
                errorMessage
            );

            return PhysicalFile(
                errorPath,
                "text/plain"
            );
        }
    }
}

Once the implementation works locally, the next step is testing the same code after deployment to Azure App Service.

That is where native dependency, font and hosting-environment differences become important.

How to Run wkhtmltopdf on Azure App Service

A wkhtmltopdf implementation that works locally may fail after Azure deployment because Azure App Service is a different execution environment from a developer workstation.

Before changing the PDF code, validate the following.

Native wkhtmltopdf dependencies

Make sure the required executable or native library is included in the deployed application.

Runtime architecture

The application’s architecture must be compatible with the wkhtmltopdf native dependency.

For example, a 64-bit application should not attempt to load an incompatible 32-bit native library.

Fonts

A font installed locally might not exist in the Azure environment.

This can result in:

• Different typography
• Changed line breaks
• Misaligned content
• Incorrect PDF layouts

Hosting restrictions

Azure App Service environments may restrict access to operating-system functionality compared with a traditional server or VM.

This is particularly relevant for applications that execute native PDF-rendering components.

wkhtmltopdf Issue on Azure App Service Free Plan

In our original Windows Azure App Service test, wkhtmltopdf did not behave the same way as it did locally.

After adding the required wkhtmltopdf files and running the application, we encountered PDF rendering issues, including incorrect fonts.

The behavior depends on factors including:

• Windows vs Linux hosting
• Native dependencies
• App Service restrictions
• Application architecture
• wkhtmltopdf build
• Runtime resources

This result shows what worked in our test environment. It should not be interpreted as evidence that every wkhtmltopdf deployment requires the same Azure tier.

Later in our testing, we were also able to run a wkhtmltopdf-based implementation using an Azure Linux App Service configuration.

2. DinkToPDF .NET Core Complete Example

A basic global configuration can look like this:

var globalSettings = new GlobalSettings
{
    ColorMode = ColorMode.Color,
    Orientation = Orientation.Portrait,
    PaperSize = PaperKind.A4,
    Margins = new MarginSettings
    {
        Top = 18,
        Bottom = 18
    }
};

Configure the HTML document:

    
var objectSettings = new ObjectSettings
{
    PagesCount = true,

    HtmlContent = htmlContent,

    WebSettings =
    {
        DefaultEncoding = "utf-8"
    },

    HeaderSettings =
    {
        FontSize = 10,
        Right = "Page [page] of [toPage]",
        Line = true
    },

    FooterSettings =
    {
        FontSize = 8,
        Center = "PDF demo",
        Line = true
    }
};

Then create and convert the PDF:

    

var htmlToPdfDocument = new HtmlToPdfDocument
{
    GlobalSettings = globalSettings,
    Objects =
    {
        objectSettings
    }
};

return _converter.Convert(htmlToPdfDocument);

A complete implementation can look like this:

  private byte[] GeneratePdf(string htmlContent)
{
    try
    {
        var globalSettings = new GlobalSettings
        {
            ColorMode = ColorMode.Color,
            Orientation = Orientation.Portrait,
            PaperSize = PaperKind.A4,
            Margins = new MarginSettings
            {
                Top = 18,
                Bottom = 18
            }
        };

        var objectSettings = new ObjectSettings
        {
            PagesCount = true,
            HtmlContent = htmlContent,

            WebSettings =
            {
                DefaultEncoding = "utf-8"
            },

            HeaderSettings =
            {
                FontSize = 10,
                Right = "Page [page] of [toPage]",
                Line = true
            },

            FooterSettings =
            {
                FontSize = 8,
                Center = "PDF demo",
                Line = true
            }
        };

        var document = new HtmlToPdfDocument
        {
            GlobalSettings = globalSettings,
            Objects =
            {
                objectSettings
            }
        };

        return _converter.Convert(document);
    }
    catch (Exception ex)
    {
        _logger.LogError(
            ex,
            "Error generating PDF."
        );

        throw;
    }
}

Because DinkToPDF uses wkhtmltopdf underneath, the appropriate native wkhtmltopdf dependency must also be available in the deployed environment.

• It will give you options and methods to set the PDF size, margins, etc…
• I have created one example and here is the main code to use.

private byte[] GeneratePdf(string htmlContent)
{
    try
    {
        _logger.LogInformation("GeneratePdf started.");

        // Configure global settings for the PDF document
        var globalSettings = new GlobalSettings
        {
            ColorMode = ColorMode.Color,
            Orientation = Orientation.Portrait,
            PaperSize = PaperKind.A4,
            Margins = new MarginSettings { Top = 18, Bottom = 18 },
        };

        // Configure object settings for the HTML content
        var objectSettings = new ObjectSettings
        {
            PagesCount = true,
            HtmlContent = htmlContent,
            WebSettings = { DefaultEncoding = "utf-8" },
            HeaderSettings = 
            {
                FontSize = 10,
                Right = "Page [page] of [toPage]",
                Line = true
            },
            FooterSettings = 
            {
                FontSize = 8,
                Center = "PDF demo",
                Line = true
            }
        };

        // Create the PDF document
        var htmlToPdfDocument = new HtmlToPdfDocument
        {
            GlobalSettings = globalSettings,
            Objects = { objectSettings },
        };

        // Convert HTML to PDF
        return _converter.Convert(htmlToPdfDocument);
    }
    catch (Exception ex)
    {
        _logger.LogError("Error in GeneratePdf: {Message}", ex.Message);
        return null;
    }
}

• So once you download the code and run it it will work locally. Basically, the key thing which is required is DinkToPdf NugetPackage and the folder of v12.0.4. It is the wkhtmltopdf Wrapper.

• I have used the Invoice template for a demo. And you can find it in the Views folder.
• Here I used to save the pdf file to Azure Blob Storage after pdf generation. For that please provide your storage key and the pdf file name in the appsettings.json.
• Once all set the code Host the code into Azure app service. And run.
• And run this url to get your output : https://{AppServiceName}.azurewebsites.net/documentgenerator

DinkToPDF Timeout Error on Azure App Service

After publishing our DinkToPDF example to Azure App Service, the PDF-generation endpoint returned a timeout in the configuration we were testing.

• Fix for DinkToPDF Timeout Error: In our test, the issue was fixed by moving the application to a paid Azure App Service Production plan, restarting the app, and running the PDF generation process again.
• Here, I am using the minimum plan for this.

• Apply the plan, Restart the app and run, you will get the desired output.

Text screenshot from an Asp.Net Core application on Azure displaying: “{‘statusCode’: 200, ‘message’: ‘pdf file has been successfully uploaded’}.

• And when i see in the blob storage.

Screenshot displaying a file directory with two PDF files: “GeneratedPdf.pdf” and “RazorTemplatePdf.pdf,” both labeled under the “Hot (inferred)” access tier. These files were efficiently managed using Asp.Net Core within the Azure ecosystem.

• So it’s all about choosing the right hosting plan and your code works well.

DinkToPDF Page Numbers: How [page] and [toPage] Work

DinkToPDF can display the current PDF page and the document’s total page count through wkhtmltopdf page-number placeholders.

For example, a five-page document can display:

Page 1 of 5
Page 2 of 5
Page 3 of 5
Page 4 of 5
Page 5 of 5

The two important placeholders are:

DinkToPDF FooterSettings Example for Page [page] of [toPage]

If you want page numbering in the footer, configure it through FooterSettings.

FooterSettings =
{
    FontSize = 8,
    Right = "Page [page] of [toPage]",
    Line = true,
    Spacing = 3
}

For example, the generated footer can display:

Page 3 of 12

A more complete configuration is:

var objectSettings = new ObjectSettings
{
    PagesCount = true,

    HtmlContent = htmlContent,

    WebSettings =
    {
        DefaultEncoding = "utf-8"
    },

    FooterSettings =
    {
        FontSize = 8,
        Right = "Page [page] of [toPage]",
        Line = true,
        Spacing = 3
    }
};

Is PagesCount = true Required in DinkToPDF?

When you need document page counters for headers and footers, configure:

PagesCount = true

inside the relevant ObjectSettings.

A basic example is:

var objectSettings = new ObjectSettings
{
    PagesCount = true,

    HtmlContent = htmlContent,

    FooterSettings =
    {
        Right = "Page [page] of [toPage]"
    }
};

PagesCount tells DinkToPDF to count the pages of the document for page-counter functionality.

This setting is especially relevant when using:

[page]

or:

[toPage]

Why Is [toPage] Not Working in DinkToPDF?

If [toPage] is missing, incorrect or appears as plain text in the PDF, work through these checks.

1. Confirm PagesCount

Make sure:

PagesCount = true

is enabled on the appropriate ObjectSettings.

2. Check the Placeholder

Use:

[toPage]

For example:

Right = "Page [page] of [toPage]"

3. Place It in the Header or Footer Configuration

FooterSettings =
{
    Right = "Page [page] of [toPage]"
}

4. Test a Multi-Page Document

Use enough HTML content to create multiple PDF pages so that the page counter can be tested properly.

5. Verify wkhtmltopdf Dependencies

Because DinkToPDF relies on wkhtmltopdf, a native-library or deployment problem can affect features even if the C# configuration appears correct.

6. Compare Local and Azure Results

If [toPage] works locally but fails after Azure deployment, investigate:

• Operating system
• wkhtmltopdf binary
• Architecture
• Deployment folders
• Native-library loading
• Fonts
• App Service configuration

DinkToPDF Page Number Troubleshooting Checklist

DinkToPDF HeaderSettings Example

Page numbers can also be displayed in the document header.

HeaderSettings =
{
    FontSize = 9,
    Right = "Page [page] of [toPage]",
    Line = true,
    Spacing = 3
}

Whether you use the header or footer depends on the document design.

For invoices, reports and statements, footer page numbering is often a natural choice. Technical documents may use either location.

Rotativa PDF Generation in ASP.NET Core

Rotativa is commonly used when an ASP.NET MVC application needs to generate PDFs directly from Razor/MVC views.

It can be convenient because it fits naturally into MVC applications.

However, Rotativa also relies on wkhtmltopdf, so Azure deployment still requires attention to:

• wkhtmltopdf executable availability
• Hosting environment
• Native dependencies
• Fonts
• Resource limitations

In our tested Azure configuration, the Free-tier deployment returned a timeout.

Common Azure App Service Issues with PDF Generation

When PDF generation works locally but fails after Azure deployment, use the symptoms to narrow down the likely cause.

Should You Use a Custom Container for wkhtmltopdf on Azure?

A custom container is worth considering when the application requires tighter control over native PDF-generation dependencies.

A container can package the application together with:

• wkhtmltopdf
• Linux or Windows dependencies
• Fonts
• .NET runtime
• Other required system libraries

Azure App Service supports custom container deployments, including custom Linux images.

This can make the runtime environment more predictable than depending on packages or system components already installed by the host.

A container may be particularly useful when:

• Multiple native packages are required
• wkhtmltopdf dependencies differ between environments
• Custom fonts are required
• The team wants repeatable development, staging and production environments

Containers add deployment and maintenance responsibilities, so they should be chosen because the architecture benefits from them, not simply as a workaround for every PDF issue.

Generate PDF on Azure App Service Free Plan using Linux

In Satva’s tested configuration, we were able to run a wkhtmltopdf ASP.NET Core implementation using Azure App Service on Linux with the Free tier.

This was different from the earlier Windows App Service configuration we tested.

The important point is that this was the result of a specific test configuration, not a guarantee that every wkhtmltopdf/.NET/Azure Linux combination will behave identically.

The same areas still need verification:

• wkhtmltopdf binary compatibility
• Linux dependencies
• Application runtime
• Fonts
• Deployment configuration

public class HomeController : Controller
{
    private readonly IGeneratePdf _generatePdf;
    private readonly ILogger<HomeController> _logger;
    private readonly IFileProvider _fileProvider;
    private readonly IConfiguration _config; // Ensure you have a configuration instance injected

    public HomeController(IGeneratePdf generatePdf, ILogger<HomeController> logger, IFileProvider fileProvider, IConfiguration config)
    {
        _generatePdf = generatePdf;
        _logger = logger;
        _fileProvider = fileProvider;
        _config = config; // Initialize the configuration instance
    }

    [Obsolete]
    public async Task<IActionResult> Index()
    {
        try
        {
            // Generate PDF
            var bytes = _generatePdf.GetPDF("<h1 style='color:red'>Hello World</h1>");
            
            // Retrieve storage configuration values
            var connString = _config.GetValue<string>("StorageKey") ?? string.Empty;
            var blobContainer = _config.GetValue<string>("blobContainer") ?? string.Empty;
            var blobName = _config.GetValue<string>("blobName") ?? string.Empty;

            // Create the blob client
            var storageAccount = CloudStorageAccount.Parse(connString);
            var blobClient = storageAccount.CreateCloudBlobClient();

            // Retrieve reference to the container and blob
            var container = blobClient.GetContainerReference(blobContainer);
            var blockBlob = container.GetBlockBlobReference(blobName);

            // Upload the byte array to the blob asynchronously
            await blockBlob.UploadFromByteArrayAsync(bytes, 0, bytes.Length);

            return Ok(new { Message = "File has been uploaded successfully." });
        }
        catch (Exception ex)
        {
            // Log the error
            _logger.LogError("Error: {Message}", ex);

            // Create a message for the response
            var msg = ex.InnerException?.Message ?? ex.Message;
            return Ok(new { Message = "Error: " + msg });
        }
    }
}

• If you want to know more about the comparison of App service plans of windows and linux see the below table for your reference.

Azure Linux vs Windows App Service for PDF Generation

The better App Service operating system depends on the application’s dependencies rather than one platform being universally better.

Choose Linux when

• Your application supports Linux
• You want to package native dependencies in a Linux container
• wkhtmltopdf has been validated in your chosen Linux environment

Choose Windows when

• The application already depends on Windows components
• A Windows-specific executable or library is required
• Migrating the application to Linux would introduce unnecessary complexity

The final decision should be based on the actual runtime dependencies and tested deployment environment.

Azure App Service Linux vs Windows Pricing for PDF Generation

Should You Keep Using wkhtmltopdf in 2026?

For an existing application, wkhtmltopdf may still remain practical when the implementation is stable and thoroughly tested.

Replacing a working PDF engine can introduce new rendering differences, migration work and regression testing.

However, for a new application, the fact that wkhtmltopdf’s official repository is archived should form part of the technical decision.

Evaluate:

• Maintenance status
• Security expectations
• HTML and CSS requirements
• JavaScript rendering
• Cloud deployment requirements
• Support expectations
• Migration risk
• Long-term product roadmap

A new application with modern HTML/CSS or JavaScript-heavy templates may benefit from evaluating actively maintained browser-based or PDF-generation alternatives before adopting wkhtmltopdf.

Recommended PDF Generation Approach by Scenario

Conclusion: Best PDF Generation Option for ASP.NET Core on Azure

Generating PDFs in ASP.NET Core on Azure requires more than selecting a .NET library.

You also need to account for:

• Native dependencies
• Operating system
• Runtime architecture
• Fonts
• Azure hosting configuration
• PDF complexity
• Long-term maintenance

If an application already uses wkhtmltopdf or DinkToPDF, first determine whether the problem is in the PDF configuration or Azure environment before replacing the implementation.

For DinkToPDF page numbering, the key configuration is:

PagesCount = true

with placeholders such as:

Page [page] of [toPage]

If the same code works locally but fails on Azure, compare native libraries, operating system, architecture, fonts, resource availability and hosting restrictions.

For a new system, also consider wkhtmltopdf’s archived maintenance status before choosing it as a long-term dependency.