DEV Community

IronSoftware
IronSoftware

Posted on

ASPX to PDF in C# (.NET Guide)

#csharp #dotnet

Converting ASP.NET Web Forms to PDF used to mean wrestling with complex libraries or paying for third-party rendering services. I've built invoice systems and reporting dashboards where users needed a "Download as PDF" button, and the solution was never as simple as I wanted.

Then I found you can render an entire ASPX page to PDF with a single line of code.

using IronPdf;
// Install via NuGet: Install-Package IronPdf

// In your Page_Load or button click handler:
IronPdf.AspxToPdf.RenderThisPageAsPdf();
Enter fullscreen mode Exit fullscreen mode

That's it. The current page renders as a PDF and sends to the browser. No manual HTML capture, no fragile string building.

How Does ASPX to PDF Conversion Work?

When you call RenderThisPageAsPdf(), IronPDF intercepts the rendered HTML output from your ASPX page — everything that would normally go to the browser — and converts it to PDF using a Chromium-based rendering engine.

This means:

  • Your CSS stylesheets apply exactly as they do in Chrome
  • JavaScript executes before rendering
  • Images, hyperlinks, and forms preserve their formatting
  • Dynamic content from databases or APIs renders correctly

I've used this for management reports where the page pulls data from SQL Server, binds it to a GridView, and the user clicks "Export to PDF." The PDF matches what they see on screen.

What's the Simplest ASPX to PDF Example?

Drop this into any ASPX page's code-behind:

protected void Page_Load(object sender, EventArgs e)
{
    IronPdf.AspxToPdf.RenderThisPageAsPdf();
}
Enter fullscreen mode Exit fullscreen mode

Now when you navigate to that page, instead of seeing HTML, the browser downloads a PDF.

For a button-triggered export:

protected void btnExportPDF_Click(object sender, EventArgs e)
{
    IronPdf.AspxToPdf.RenderThisPageAsPdf(
        IronPdf.AspxToPdf.FileBehavior.Attachment,
        "Report.pdf"
    );
}
Enter fullscreen mode Exit fullscreen mode

FileBehavior.Attachment forces a download. FileBehavior.InBrowser displays the PDF inline (if the browser supports it).

How Do I Control the PDF Filename?

Pass the filename as the second parameter:

IronPdf.AspxToPdf.RenderThisPageAsPdf(
    IronPdf.AspxToPdf.FileBehavior.Attachment,
    $"Invoice_{DateTime.Now:yyyyMMdd}.pdf"
);
Enter fullscreen mode Exit fullscreen mode

This is useful for invoices or reports where the filename should include a date or customer ID.

Can I Customize the PDF Rendering?

Yes, through [ChromePdfRenderer](https://ironpdf.com/blog/videos/how-to-render-html-string-to-pdf-in-csharp-ironpdf/). Here's how I configure it for professional reports:

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;
renderer.RenderingOptions.MarginTop = 40;
renderer.RenderingOptions.MarginBottom = 40;
renderer.RenderingOptions.CssMediaType = IronPdf.Rendering.PdfCssMediaType.Print;

IronPdf.AspxToPdf.RenderThisPageAsPdf(renderer);
Enter fullscreen mode Exit fullscreen mode

The Print media type triggers your @media print CSS rules, which is how I hide navigation menus and footers in PDF exports.

How Do I Add Headers and Footers?

IronPDF supports text and HTML headers/footers with placeholders:

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
    HtmlFragment = "<div style='text-align:center; font-size:10px;'>Company Invoice</div>"
};

renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
    HtmlFragment = "<div style='text-align:center; font-size:10px;'>Page {page} of {total-pages}</div>"
};

IronPdf.AspxToPdf.RenderThisPageAsPdf(renderer);
Enter fullscreen mode Exit fullscreen mode

Available placeholders:

  • {page} — Current page number
  • {total-pages} — Total page count
  • {date} — Current date
  • {time} — Current time
  • {url} — Page URL
  • {html-title} — Page title from <title> tag

I use these for compliance reports where every page needs a timestamp and page number.

What About Page Breaks?

You control page breaks with CSS:

<div style="page-break-after: always;"></div>
Enter fullscreen mode Exit fullscreen mode

This forces a new page. I use it between sections in multi-page reports:

<div class="report-section">
    <!-- First section content -->
</div>
<div style="page-break-after: always;"></div>
<div class="report-section">
    <!-- Second section content -->
</div>
Enter fullscreen mode Exit fullscreen mode

For tables that shouldn't split across pages:

.no-break {
    page-break-inside: avoid;
}
Enter fullscreen mode Exit fullscreen mode

Does This Work with Dynamic Data?

Absolutely. Here's a pattern I use for database-driven reports:

protected void Page_Load(object sender, EventArgs e)
{
    if (!IsPostBack)
    {
        // Load data from database
        var orders = GetOrdersFromDatabase();
        GridView1.DataSource = orders;
        GridView1.DataBind();
    }
}

protected void btnDownloadPDF_Click(object sender, EventArgs e)
{
    // Rebind data before rendering
    var orders = GetOrdersFromDatabase();
    GridView1.DataSource = orders;
    GridView1.DataBind();

    IronPdf.AspxToPdf.RenderThisPageAsPdf(
        IronPdf.AspxToPdf.FileBehavior.Attachment,
        "OrderReport.pdf"
    );
}
Enter fullscreen mode Exit fullscreen mode

The key: rebind your data before calling RenderThisPageAsPdf() to ensure the PDF reflects the current state.

Can I Generate Multiple PDFs Asynchronously?

For bulk operations, use async patterns:

var customerIds = new[] { 101, 102, 103, 104 };

await Parallel.ForEachAsync(customerIds, async (customerId, cancellationToken) =>
{
    var renderer = new ChromePdfRenderer();
    var html = await GenerateInvoiceHtmlAsync(customerId);
    var pdf = renderer.RenderHtmlAsPdf(html);
    pdf.SaveAs($"Invoice_{customerId}.pdf");
});
Enter fullscreen mode Exit fullscreen mode

I built a nightly report generator that processes thousands of customer statements this way. IronPDF handles the parallelism without issues.

What About JavaScript-Heavy Pages?

IronPDF executes JavaScript before rendering. If your page uses AJAX or delayed rendering:

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.WaitFor.RenderDelay(2000); // Wait 2 seconds

IronPdf.AspxToPdf.RenderThisPageAsPdf(renderer);
Enter fullscreen mode Exit fullscreen mode

Or wait for specific elements:

renderer.RenderingOptions.WaitFor.HtmlElement("#chart-loaded");
Enter fullscreen mode Exit fullscreen mode

This ensures your charts or async-loaded content renders before PDF generation.

How Does This Compare to Other Libraries?

I've used iTextSharp and wkhtmltopdf in the past:

iTextSharp: Requires manual PDF construction. You're not rendering HTML; you're positioning text and shapes with coordinates. Great for programmatic PDFs, terrible for converting existing web pages.

wkhtmltopdf: Command-line tool that renders HTML via an old WebKit engine. It's free but deprecated, and CSS support is years behind modern browsers. I ran into rendering bugs constantly.

IronPDF: Uses Chromium (same engine as Chrome), so if it looks right in Chrome, it looks right in the PDF. You're rendering actual HTML, not approximating it.

The complete ASPX to PDF tutorial covers advanced scenarios like custom paper sizes, watermarks, and digital signatures.

Does This Work with .NET Core?

Yes. IronPDF supports:

  • .NET Framework 4.x+ (classic ASP.NET Web Forms)
  • .NET Core 2.0+
  • .NET 5, 6, 7, 8, 9, 10

For .NET Core Razor Pages or MVC, you'd use RenderHtmlAsPdf() instead of RenderThisPageAsPdf(), but the rendering engine is identical.

Quick Troubleshooting

PDF downloads but is blank:

  • Check if your page has a form element — you might need to render outside the form lifecycle
  • Ensure CSS files use absolute URLs or are embedded inline

Styles don't match the browser:

  • Set CssMediaType = PdfCssMediaType.Print to use print stylesheets
  • Check for external CSS files that aren't accessible from the server context

Images missing:

  • Use absolute URLs for images, or embed them as base64 data URIs

I learned these the hard way on production deployments. The most common issue is CSS paths — what works in development often breaks when you deploy to a subfolder or different domain.

Written by Jacob Mellor, CTO at Iron Software. Jacob created IronPDF and leads a team of 50+ engineers building .NET document processing libraries.

Top comments (0)