DEV Community

IronSoftware
IronSoftware

Posted on

PdfSharp HTML to PDF in .NET Core: Limitations and Alternatives

#css #dotnet

Developers frequently search for PdfSharp HTML to PDF conversion capabilities, expecting the library to handle web content rendering. The reality is more complicated: PdfSharp does not natively support HTML conversion and requires third-party middleware that imposes significant CSS limitations. This becomes particularly problematic in .NET Core environments where compatibility issues compound the already restrictive feature set.

This article documents what PdfSharp actually provides, explains the limitations of the HtmlRenderer.PdfSharp workaround, and presents an alternative approach for developers who need modern HTML and CSS support.

The Core Issue: PdfSharp Has No Native HTML Support

PdfSharp is a low-level PDF generation library focused on programmatic document creation. The library allows developers to draw text, graphics, and images on PDF pages using C# code, but it has no built-in capability to parse or render HTML content.

When developers attempt to find HTML-to-PDF functionality in PdfSharp's API, they discover that no such methods exist. There is no RenderHtml(), no ConvertFromUrl(), and no way to process CSS stylesheets. The library operates at a fundamental drawing level, not as a document format converter.

This architectural decision means that any HTML conversion workflow involving PdfSharp requires additional libraries. The most common approach is to use HtmlRenderer.PdfSharp, a separate NuGet package that bridges the gap between HTML content and PdfSharp's drawing API.

The HtmlRenderer.PdfSharp Workaround

HtmlRenderer.PdfSharp provides static rendering methods that convert HTML strings into PDF documents using PdfSharp as the underlying PDF engine. The library parses HTML markup and translates it into PdfSharp drawing commands.

Installation and Basic Usage

The package is available on NuGet:

Install-Package HtmlRenderer.PdfSharp
Enter fullscreen mode Exit fullscreen mode

A basic conversion looks like this:

using PdfSharp.Pdf;
using TheArtOfDev.HtmlRenderer.PdfSharp;

public class HtmlRendererPdfExample
{
    public void ConvertHtmlToPdf()
    {
        string htmlContent = @"
            <html>
            <body>
                <h1>Invoice #12345</h1>
                <p>Thank you for your order.</p>
            </body>
            </html>";

        // Generate PDF using HtmlRenderer.PdfSharp
        PdfDocument pdf = PdfGenerator.GeneratePdf(htmlContent, PdfSharp.PageSize.A4);

        pdf.Save("output.pdf");
    }
}
Enter fullscreen mode Exit fullscreen mode

This appears straightforward until developers attempt to use modern CSS features.

CSS Limitations: HTML 4.01 and CSS Level 2 Only

HtmlRenderer.PdfSharp supports only HTML 4.01 and CSS Level 2 specifications. This limitation stems from the library's parsing engine, which was designed before modern CSS became standard.

No Flexbox Support

CSS Flexbox, introduced in CSS3 and widely adopted since 2012, is not supported. Layouts that rely on display: flex, justify-content, align-items, or any flex properties will not render correctly.

/* This CSS will NOT work in HtmlRenderer.PdfSharp */
.container {
    display: flex;
    justify-content: space-between;
    align-items: center;
}
Enter fullscreen mode Exit fullscreen mode

Developers must fall back to float-based layouts or table structures:

/* Workaround: Table-based layout */
.container {
    display: table;
    width: 100%;
}
.item {
    display: table-cell;
    vertical-align: middle;
}
Enter fullscreen mode Exit fullscreen mode

No CSS Grid Support

CSS Grid Layout, which became a W3C Recommendation in 2017, is completely unsupported. Grid properties including display: grid, grid-template-columns, grid-gap, and all related properties are ignored.

/* This CSS will NOT work in HtmlRenderer.PdfSharp */
.dashboard {
    display: grid;
    grid-template-columns: 1fr 2fr 1fr;
    grid-gap: 20px;
}
Enter fullscreen mode Exit fullscreen mode

Complex grid layouts must be rewritten using nested tables, adding significant complexity to HTML templates.

No CSS Transforms or Animations

CSS transforms (transform, rotate, scale, skew) are not available. While animations are irrelevant for static PDF output, transforms are often used for visual effects like rotated text or scaled images:

/* These CSS properties will NOT work */
.rotated-text {
    transform: rotate(-45deg);
}
.scaled-image {
    transform: scale(1.5);
}
Enter fullscreen mode Exit fullscreen mode

Limited Box Model Support

Modern box model features including box-sizing: border-box may not function as expected. The library's CSS parser predates the widespread adoption of box-sizing, leading to layout calculation differences compared to browser rendering.

Missing Pseudo-Elements and Selectors

Advanced CSS selectors and pseudo-elements have limited or no support:

  • ::before and ::after pseudo-elements
  • :nth-child() selectors
  • CSS variables (--custom-property)
  • calc() functions
  • Media queries

Summary of Unsupported CSS Features

CSS Feature Support Status
Flexbox (display: flex) Not supported
CSS Grid (display: grid) Not supported
Transforms (transform) Not supported
CSS Variables Not supported
calc() function Not supported
box-sizing: border-box Partial/inconsistent
::before, ::after Not supported
Media queries Not supported
Web fonts (@font-face) Limited
Modern selectors (:nth-child) Limited

.NET Core and .NET 6/8 Compatibility Issues

The original HtmlRenderer.PdfSharp package targets .NET Framework. For .NET Core projects, developers must use alternative forks or adapted packages, each with its own compatibility challenges.

PdfSharpCore Fork

PdfSharpCore is a community fork that provides .NET Core compatibility for the base PdfSharp library. However, as documented in GitHub issues, HTML rendering support in this fork has limitations.

"PdfSharpCore doesn't come with support for converting HTML to PDF currently. I know there is an extension library called HtmlRendererCore but I'm not sure if it's still actively maintained."
— GitHub Issue #166, PdfSharpCore Repository

HtmlRendererCore Package

A separate package called HtmlRendererCore exists for .NET Core environments. This package bridges HtmlRenderer with PdfSharpCore but introduces additional dependencies and potential version conflicts.

The installation requires multiple packages:

Install-Package PdfSharpCore
Install-Package HtmlRendererCore.PdfSharp
Enter fullscreen mode Exit fullscreen mode

Developers report version compatibility issues between these packages. When PdfSharpCore updates, HtmlRendererCore may lag behind, causing breaking changes or requiring specific version pinning.

Forum Reports of Issues

The PdfSharp forum contains threads from developers encountering problems with HTML conversion:

"I would like to know what would be the best strategy to convert an ASP.NET Server Control's rendered HTML to PDF using PDFSharp."
— Forum Thread, PDFsharp.net

The responses confirm that PdfSharp itself has no HTML support, directing users to third-party solutions with the caveat that modern CSS features will not work.

.NET 6/8 Specific Problems

Developers targeting .NET 6 or .NET 8 may encounter:

  1. Missing System.Drawing dependencies: HtmlRenderer historically depends on System.Drawing.Common, which has limited Linux support
  2. Native library issues: Some rendering operations require platform-specific native libraries
  3. Package version conflicts: The ecosystem of forks and adapters can create dependency resolution failures

When PdfSharp Is Appropriate

Despite the HTML limitations, PdfSharp remains useful for specific scenarios where programmatic PDF generation is required without HTML involvement.

Suitable Use Cases

  • Generated reports from data: When report layouts are defined in C# code and populated from databases
  • Certificates and badges: Fixed-layout documents where design is controlled programmatically
  • PDF manipulation: Merging, splitting, or modifying existing PDF files
  • Drawing-based output: Technical diagrams, charts, or custom visualizations
  • Projects without HTML templates: New projects where HTML conversion is not a requirement

Unsuitable Use Cases

  • Converting existing HTML/CSS templates to PDF
  • Web page capture or URL-to-PDF conversion
  • Rendering rich text HTML from CMS systems or databases
  • Any layout requiring Flexbox, Grid, or modern CSS
  • Cross-platform deployments where System.Drawing limitations apply

Converting HTML to PDF with IronPDF

For developers who need genuine HTML-to-PDF conversion with modern CSS support, IronPDF provides this functionality using an embedded Chromium rendering engine. This is the same engine that powers Google Chrome, ensuring that HTML, CSS, and JavaScript render exactly as they would in a browser.

Why IronPDF Handles HTML Differently

PdfSharp and HtmlRenderer.PdfSharp use a custom CSS parser limited to CSS Level 2 specifications from the early 2000s. IronPDF takes a fundamentally different approach: it embeds a headless Chromium browser that processes web content using the same engine as modern browsers.

This architecture supports:

  • Full HTML5 parsing
  • CSS3 including Flexbox and Grid layouts
  • JavaScript execution for dynamic content
  • Web fonts and custom typography via @font-face
  • SVG rendering
  • Responsive design and media queries
  • CSS transforms and modern visual effects

Code Example: HTML String with Modern CSS to PDF

The following example demonstrates converting HTML with Flexbox layout to PDF:

using IronPdf;

public class ModernHtmlToPdfConverter
{
    public void ConvertFlexboxHtmlToPdf()
    {
        // Create a ChromePdfRenderer instance
        // This uses the embedded Chromium engine for rendering
        var renderer = new ChromePdfRenderer();

        // Configure rendering options
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;
        renderer.RenderingOptions.MarginLeft = 20;
        renderer.RenderingOptions.MarginRight = 20;

        // HTML content with modern CSS including Flexbox
        // HtmlRenderer.PdfSharp cannot render this correctly
        string htmlContent = @"
        <!DOCTYPE html>
        <html>
        <head>
            <style>
                body {
                    font-family: 'Segoe UI', Arial, sans-serif;
                    margin: 0;
                    padding: 20px;
                }
                h1 {
                    color: #2c3e50;
                    border-bottom: 3px solid #3498db;
                    padding-bottom: 10px;
                }

                /* Flexbox layout - NOT supported by HtmlRenderer.PdfSharp */
                .invoice-header {
                    display: flex;
                    justify-content: space-between;
                    align-items: center;
                    margin-bottom: 30px;
                }

                .company-info {
                    display: flex;
                    flex-direction: column;
                }

                /* CSS Grid layout - NOT supported by HtmlRenderer.PdfSharp */
                .items-grid {
                    display: grid;
                    grid-template-columns: 3fr 1fr 1fr 1fr;
                    gap: 10px;
                    border: 1px solid #ddd;
                }

                .grid-header {
                    background-color: #3498db;
                    color: white;
                    padding: 12px;
                    font-weight: bold;
                }

                .grid-cell {
                    padding: 12px;
                    border-bottom: 1px solid #eee;
                }

                .total-row {
                    display: flex;
                    justify-content: flex-end;
                    margin-top: 20px;
                    padding: 15px;
                    background-color: #f8f9fa;
                    border-radius: 4px;
                }

                .total-amount {
                    font-size: 1.4em;
                    font-weight: bold;
                    color: #2c3e50;
                }
            </style>
        </head>
        <body>
            <div class='invoice-header'>
                <div class='company-info'>
                    <h1>Invoice #12345</h1>
                    <span>Acme Corporation</span>
                    <span>123 Business Street</span>
                </div>
                <div class='invoice-date'>
                    <strong>Date:</strong> January 20, 2026<br>
                    <strong>Due:</strong> February 19, 2026
                </div>
            </div>

            <div class='items-grid'>
                <div class='grid-header'>Item</div>
                <div class='grid-header'>Quantity</div>
                <div class='grid-header'>Unit Price</div>
                <div class='grid-header'>Total</div>

                <div class='grid-cell'>Widget A - Premium Model</div>
                <div class='grid-cell'>10</div>
                <div class='grid-cell'>$25.00</div>
                <div class='grid-cell'>$250.00</div>

                <div class='grid-cell'>Widget B - Standard</div>
                <div class='grid-cell'>5</div>
                <div class='grid-cell'>$45.00</div>
                <div class='grid-cell'>$225.00</div>

                <div class='grid-cell'>Service Fee</div>
                <div class='grid-cell'>1</div>
                <div class='grid-cell'>$50.00</div>
                <div class='grid-cell'>$50.00</div>
            </div>

            <div class='total-row'>
                <span class='total-amount'>Total: $525.00</span>
            </div>
        </body>
        </html>";

        // Render HTML to PDF
        // Chromium engine processes Flexbox and Grid correctly
        var pdf = renderer.RenderHtmlAsPdf(htmlContent);

        // Save the generated PDF
        pdf.SaveAs("invoice-with-modern-css.pdf");
    }
}
Enter fullscreen mode Exit fullscreen mode

This code renders the HTML content with full CSS3 support. The Flexbox header layout, CSS Grid table structure, and modern styling all render correctly because IronPDF uses an actual browser engine rather than a limited CSS parser.

Converting a URL to PDF

IronPDF can also capture live web pages, including those with JavaScript-rendered content:

using IronPdf;

public class UrlToPdfConverter
{
    public void ConvertWebPageToPdf()
    {
        var renderer = new ChromePdfRenderer();

        // Enable JavaScript for dynamic content
        renderer.RenderingOptions.EnableJavaScript = true;

        // Wait for JavaScript to execute before capturing
        renderer.RenderingOptions.WaitFor.RenderDelay(1000);

        // Render a URL directly to PDF
        var pdf = renderer.RenderUrlAsPdf("https://example.com/dashboard");

        pdf.SaveAs("webpage-capture.pdf");
    }
}
Enter fullscreen mode Exit fullscreen mode

Comparing the Approaches

Capability PdfSharp + HtmlRenderer IronPDF
HTML parsing HTML 4.01 HTML5
CSS support CSS Level 2 CSS3
Flexbox No Yes
CSS Grid No Yes
CSS Transforms No Yes
JavaScript execution No Yes
Web fonts Limited Yes
URL to PDF No Yes
.NET Core support Via forks, with issues Native
.NET 6/8 support Compatibility concerns Full support

API Reference

For detailed documentation on the methods demonstrated:

Migration Considerations

Switching from PdfSharp with HtmlRenderer to IronPDF involves evaluating licensing, API differences, and project requirements.

Licensing

PdfSharp is open source under the MIT License. HtmlRenderer.PdfSharp is also open source. IronPDF is commercial software with per-developer licensing. A free trial is available for evaluation, and a free version exists for development purposes.

For projects with commercial revenue or where modern CSS support is required, the licensing cost may be justified by reduced development time from not having to work around CSS limitations.

API Differences

The migration from HtmlRenderer.PdfSharp to IronPDF is relatively straightforward since both accept HTML strings as input.

HtmlRenderer.PdfSharp:

// HtmlRenderer.PdfSharp approach
PdfDocument pdf = PdfGenerator.GeneratePdf(htmlContent, PdfSharp.PageSize.A4);
pdf.Save("output.pdf");
Enter fullscreen mode Exit fullscreen mode

IronPDF:

// IronPDF approach
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("output.pdf");
Enter fullscreen mode Exit fullscreen mode

The primary difference is that IronPDF returns its own PdfDocument type with additional manipulation capabilities, while HtmlRenderer returns a PdfSharp PdfDocument.

What You Gain

Migrating to IronPDF provides:

  • Modern CSS support without layout workarounds
  • JavaScript execution for dynamic content
  • URL rendering capability
  • Reliable .NET Core and .NET 6/8 support
  • Active development and support

What to Consider

  • Commercial licensing required for production use
  • Larger package size due to embedded Chromium
  • Learning curve for advanced features
  • Memory usage differs from lightweight PdfSharp approach

Conclusion

PdfSharp does not natively support HTML to PDF conversion. The HtmlRenderer.PdfSharp workaround provides basic functionality but is limited to HTML 4.01 and CSS Level 2, excluding modern layout systems like Flexbox and CSS Grid. In .NET Core environments, additional compatibility challenges arise from fragmented package ecosystems and dependency conflicts.

For developers who need to convert modern HTML and CSS to PDF documents, IronPDF offers a Chromium-based solution that renders web content identically to how it appears in browsers. The choice between approaches depends on whether the project can accommodate CSS limitations or requires full modern web standards support.

Jacob Mellor has 25+ years of commercial software experience and originally built IronPDF as CTO at Iron Software.

References

  1. Can PDFSharp create Pdf file from a Html string in Net Core?{:rel="nofollow"} - Stack Overflow discussion on PdfSharp HTML limitations
  2. PdfSharpCore GitHub Issue #166{:rel="nofollow"} - Discussion of HTML support in PdfSharpCore
  3. PdfSharp Forum - HTML TO PDF Conversion{:rel="nofollow"} - Forum thread on HTML conversion strategies
  4. HtmlRenderer.PdfSharp NuGet Package{:rel="nofollow"} - Official package documentation
  5. HtmlRendererCore GitHub Repository{:rel="nofollow"} - .NET Core port of HtmlRenderer
  6. PdfSharpCore GitHub Repository{:rel="nofollow"} - .NET Core fork of PdfSharp

For comprehensive IronPDF documentation including tutorials, API reference, and code examples, visit ironpdf.com.

Top comments (0)