DEV Community

IronSoftware
IronSoftware

Posted on

iTextSharp Not Working in .NET Core and .NET 5+ (Isseu Fixed)

#csharp #dotnet

Developers attempting to use iTextSharp in modern .NET applications frequently encounter a frustrating discovery: the library simply does not work with .NET Core or .NET 5+. This compatibility issue has left thousands of developers searching for solutions after their PDF generation code breaks during framework migrations.

The Problem

iTextSharp 5.x was built exclusively for .NET Framework. When Microsoft released .NET Core as a cross-platform alternative, iTextSharp remained tied to the legacy framework. Attempting to reference the iTextSharp NuGet package in a .NET Core or .NET 5+ project results in compatibility warnings and runtime failures.

The typical error message developers encounter when adding iTextSharp to an ASP.NET Core project reads:

NU1701: Package 'iTextSharp 5.5.13' was restored using '.NETFramework,Version=v4.6.1'
instead of the project target framework '.NETCoreApp,Version=v2.1'.
This package may not be fully compatible with your project.
Enter fullscreen mode Exit fullscreen mode

While NuGet allows the package to install with this warning, runtime exceptions follow when the code actually executes. System.Drawing dependencies fail, platform-specific calls break, and developers find themselves unable to generate PDFs in their modernized applications.

Why iTextSharp Cannot Support .NET Core

iTextSharp's architecture relies on several .NET Framework-specific components that have no direct equivalent in .NET Core:

  1. System.Drawing.Common dependencies: iTextSharp uses System.Drawing for image manipulation, which behaves differently (or fails entirely) on non-Windows platforms under .NET Core.

  2. Windows-specific APIs: Internal calls to Windows-only functionality prevent cross-platform execution.

  3. Assembly references: Hard references to .NET Framework assemblies that do not exist in the .NET Core runtime.

  4. End-of-life status: iText officially deprecated iTextSharp in favor of iText 7, meaning no updates address .NET Core compatibility.

Who Is Affected

This compatibility gap affects developers in several scenarios:

Framework Migration Projects: Teams modernizing legacy .NET Framework applications to .NET Core or .NET 5+ find their existing iTextSharp code unusable without significant changes.

New .NET Core/5/6/7/8 Projects: Developers starting new projects discover that tutorials and Stack Overflow answers referencing iTextSharp simply do not apply to modern .NET.

Cross-Platform Development: Anyone targeting Linux, macOS, or containerized deployments cannot use the original iTextSharp package.

Azure App Service on Linux: Cloud deployments on Linux-based App Service plans fail when code references iTextSharp.

Evidence from the Developer Community

The iTextSharp .NET Core compatibility issue has generated significant discussion across developer forums and communities.

Timeline

Date Event Source
2016-06-27 .NET Core 1.0 released Microsoft
2017-08-01 iText 7 for .NET released (replacement) iText
2018-present Community creates unofficial .NET Core ports GitHub
2020-11-10 .NET 5 released, iTextSharp still incompatible Microsoft
2023-present iTextSharp officially in maintenance-only mode iText

Community Reports

On Stack Overflow, a developer asked directly about the compatibility:

"iTextSharp: Any support for .Net 6?"
The accepted answer confirms: "iTextSharp is the name of the iText 5 PDF library for .NET. iText 5 has been EOL. Bug fixes and support still exist, but new development is happening on the next generation: iText 9."

The ASP.NET Snippets community documented the specific warning:

"When using iTextSharp 5.5.13 with .NET Core, you receive: 'The package iTextSharp 5.5.13 has been restored using .NETFramework, Version = v4.6.1 and not through the target framework of the project .NETCoreApp.'"

On the official iText product page, the company states clearly:

"iTextSharp is EOL and has transitioned to maintenance mode, meaning it only receives security related releases and fixes. No new features will be added. For new implementations they strongly recommend iText Core."

Root Cause Analysis

The incompatibility stems from architectural decisions made before .NET Core existed. When iTextSharp was developed, .NET Framework was the only .NET implementation. The library was designed assuming Windows-specific functionality would always be available.

Several technical factors prevent simple porting:

System.Drawing Dependency: iTextSharp relies heavily on System.Drawing for image processing. While System.Drawing.Common exists for .NET Core, it behaves as a thin wrapper around GDI+ on Windows and requires libgdiplus on Linux/macOS, leading to inconsistent behavior and deployment complexity.

No .NET Standard Target: The official iTextSharp package never received a .NET Standard build, which would have enabled cross-framework compatibility.

Commercial Focus Shifted: iText Software chose to invest development resources in iText 7/8/9 rather than backporting .NET Core support to the legacy iTextSharp codebase.

Available Options and Their Limitations

Developers facing this compatibility issue have several paths forward, each with significant tradeoffs.

Option 1: Unofficial iTextSharp Ports

Community members created unofficial .NET Core ports of iTextSharp's last LGPL version (4.1.6):

iTextSharp.LGPLv2.Core (NuGet: iTextSharp.LGPLv2.Core)

This package ports the 4.1.6 codebase to .NET Core and .NET Standard 2.0.

// Installing via NuGet
dotnet add package iTextSharp.LGPLv2.Core
Enter fullscreen mode Exit fullscreen mode

Limitations:

  • Based on version 4.1.6 from 2009, missing over a decade of bug fixes and features
  • Table rowspans do not work correctly (fixed in 5.4.3, not 4.1.6)
  • PdfTextExtractor unavailable (added in 5.0.2)
  • Requires additional dependencies for Linux: SkiaSharp.NativeAssets.Linux.NoDependencies and HarfBuzzSharp.NativeAssets.Linux
  • No official support or maintenance guarantees

Option 2: Migrate to iText 7/8/9

iText's official recommendation is migrating to their current product line.

// Installing iText Core
dotnet add package itext
dotnet add package itext.bouncy-castle-adapter
Enter fullscreen mode Exit fullscreen mode

Limitations:

  • AGPL License: The free version requires your entire application to be open source and AGPL-compliant
  • Commercial License Required: Proprietary applications must purchase a commercial license
  • API Completely Different: iText 7 introduced a redesigned API requiring significant code rewrites
  • Learning Curve: Developers must learn new patterns and class names

The API differences are substantial. For example, creating a simple document:

iTextSharp 5.x style:

Document document = new Document();
PdfWriter.GetInstance(document, new FileStream("output.pdf", FileMode.Create));
document.Open();
document.Add(new Paragraph("Hello World"));
document.Close();
Enter fullscreen mode Exit fullscreen mode

iText 7 style:

PdfWriter writer = new PdfWriter("output.pdf");
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);
document.Add(new Paragraph("Hello World"));
document.Close();
Enter fullscreen mode Exit fullscreen mode

Option 3: Package Confusion on NuGet

Searching NuGet for "iTextSharp" reveals multiple packages with confusing names:

Package Status Notes
iTextSharp 5.5.13.4 Official but .NET Framework only
iTextSharp.NetCore 5.5.13.1 Unofficial port, questionable maintenance
iTextSharp.LGPLv2.Core 3.7.x Unofficial, based on old 4.1.6 version
itext7 9.3.0 Official replacement (AGPL/Commercial)
itext 9.3.0 Same as itext7, consolidated package

This fragmentation creates confusion for developers who may install the wrong package or misunderstand licensing implications.

A Different Approach: IronPDF

For developers seeking .NET Core compatibility without the licensing complexity of iText 7 or the limitations of unofficial ports, IronPDF provides an alternative approach.

Why IronPDF Works Across All .NET Versions

IronPDF was designed from the ground up for cross-platform .NET development. Rather than depending on System.Drawing or Windows-specific APIs, IronPDF embeds a Chromium rendering engine that works identically across Windows, Linux, and macOS.

Key architectural differences:

  • Single NuGet package works across .NET Framework 4.6.2+, .NET Core 2.1+, .NET 5, 6, 7, and 8
  • No System.Drawing dependency eliminates libgdiplus issues on Linux
  • Chrome-based rendering ensures consistent HTML/CSS support across platforms
  • Docker-ready with official guidance for containerized deployments

Code Example

The following example demonstrates PDF generation that works identically across .NET Framework and .NET Core:

using IronPdf;

public class PdfGenerationService
{
    public byte[] GenerateInvoice(string htmlContent)
    {
        // ChromePdfRenderer uses embedded Chromium for consistent cross-platform rendering
        var renderer = new ChromePdfRenderer();

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

        // Render HTML to PDF - works on Windows, Linux, and macOS
        var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);

        // Return as byte array for web responses or further processing
        return pdfDocument.BinaryData;
    }
}
Enter fullscreen mode Exit fullscreen mode

For ASP.NET Core applications returning PDFs:

using IronPdf;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class ReportController : ControllerBase
{
    [HttpGet("download")]
    public IActionResult DownloadReport()
    {
        var renderer = new ChromePdfRenderer();

        string html = @"
            <html>
            <head>
                <style>
                    body { font-family: Arial, sans-serif; }
                    h1 { color: #333; }
                    table { width: 100%; border-collapse: collapse; }
                    td, th { border: 1px solid #ddd; padding: 8px; }
                </style>
            </head>
            <body>
                <h1>Quarterly Report</h1>
                <table>
                    <tr><th>Metric</th><th>Value</th></tr>
                    <tr><td>Revenue</td><td>$150,000</td></tr>
                    <tr><td>Expenses</td><td>$95,000</td></tr>
                </table>
            </body>
            </html>";

        var pdf = renderer.RenderHtmlAsPdf(html);

        return File(pdf.BinaryData, "application/pdf", "report.pdf");
    }
}
Enter fullscreen mode Exit fullscreen mode

Key points about this code:

  • The same code runs on .NET Core 3.1, .NET 5, .NET 6, .NET 7, and .NET 8
  • No platform-specific configuration required
  • Full CSS support including Flexbox and Grid layouts
  • JavaScript execution supported for dynamic content

API Reference

For detailed documentation on the methods demonstrated:

Migration Considerations

Licensing

IronPDF uses a commercial licensing model. A free trial is available for evaluation, with licenses starting at $749 for individual developers. Unlike iText 7's AGPL license, there is no requirement to open-source your application.

For pricing details: IronPDF Licensing

API Migration Effort

Migrating from iTextSharp to IronPDF typically requires less effort than migrating to iText 7 because:

  1. IronPDF's HTML-based approach often simplifies what was complex programmatic layout code
  2. No need to learn an entirely new document object model
  3. Existing HTML/CSS skills transfer directly

However, direct iTextSharp API calls (Document, PdfWriter, PdfPTable) have no 1:1 equivalents. Code generating PDFs programmatically will need restructuring to use either IronPDF's HTML rendering or its lower-level PDF manipulation APIs.

What You Gain

  • Cross-platform compatibility out of the box
  • Modern CSS support including Flexbox and CSS Grid
  • JavaScript rendering for dynamic content
  • Consistent output across Windows, Linux, and macOS
  • Docker support without libgdiplus configuration

What to Consider

  • Commercial license required for production use
  • Different API paradigm (HTML-centric vs. programmatic document building)
  • Larger package size due to embedded Chromium (~50MB additional)

Conclusion

iTextSharp's incompatibility with .NET Core and .NET 5+ reflects its end-of-life status and the library's architectural ties to .NET Framework. Developers face a choice between unofficial ports with significant limitations, migrating to iText 7 with its AGPL licensing requirements, or adopting an alternative library designed for modern .NET development. IronPDF provides a path forward with native cross-platform support and a straightforward licensing model.

Jacob Mellor is CTO at Iron Software, where he leads development of IronPDF and other developer tools.

References

  1. iTextSharp Product Page{:rel="nofollow"} - Official iText documentation confirming EOL status
  2. iTextSharp GitHub Repository (Deprecated){:rel="nofollow"} - Official repository marked deprecated
  3. iTextSharp.LGPLv2.Core on NuGet{:rel="nofollow"} - Unofficial .NET Core port package
  4. iTextSharp-LGPL-Core on GitHub{:rel="nofollow"} - Another unofficial .NET Core port
  5. Stack Overflow: iTextSharp support for .NET 6{:rel="nofollow"} - Community discussion on compatibility
  6. ASP.NET Snippets: iTextSharp 5.5.13 Warning{:rel="nofollow"} - Documentation of the compatibility warning
  7. iText 7 Installation Guide{:rel="nofollow"} - Official migration documentation
  8. iText 7.1 Migration Guide for .NET{:rel="nofollow"} - Official migration guide
  9. VahidN/iTextSharp.LGPLv2.Core{:rel="nofollow"} - Popular unofficial port with documentation

For the latest IronPDF documentation and tutorials, visit ironpdf.com.

Top comments (0)