Resolve Unknown PdfException in iText7 for .NET MAUI

Problem Statement

When creating PDFs using iText7 in .NET MAUI, you may encounter an Unknown PdfException with the following error:

Unknown PdfException. -> System.NotSupportedException: Either itext7.bouncy-castle-adapter or itext7.bouncy-castle-fips-adapter...

The exception typically occurs when initializing PdfWriter:

var writer = new PdfWriter(stream);

This error prevents PDF generation in .NET MAUI applications and is caused by changes in iText7's dependency management starting with version 8.0.

Root Cause

Since version 8.0, iText7 requires explicit configuration of its cryptographic dependencies:

1. iText7 no longer includes default Bouncy Castle implementations
2. You must manually reference the correct adapter packages
3. Some platforms require explicit factory configuration

Solutions

1. Install Required NuGet Packages (Recommended)

Add these packages to your .NET MAUI project:

Install-Package itext7.bouncy-castle-adapter
Install-Package Portable.BouncyCastle

Configure your project references to match these versions:

Package	Recommended Version
itext7	8.0.0+
itext7.bouncy-castle-adapter	8.0.5+
Portable.BouncyCastle	1.9.0+

WARNING

Ensure packages are resolved consistently across all projects in your solution. Use NuGet's "Consolidate" tab to verify version alignment.

2. Set Environment Variable (For MAUI Specific Issues)

If the error persists after installing packages, add this configuration to MauiProgram.cs:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        // Add before any PDF operations occur
        Environment.SetEnvironmentVariable(
            "ITEXT_BOUNCY_CASTLE_FACTORY_NAME", 
            "bouncy-castle"
        );
        
        var builder = MauiApp.CreateBuilder();
        // Rest of your initialization
        return builder.Build();
    }
}

Why This Works

This explicitly tells iText7 which cryptographic implementation to use, bypassing automatic detection that fails in some mobile environments.

Complete Working Example

using System;
using iText.Kernel.Pdf;
using iText.Layout;
using iText.Layout.Element;
using System.IO;

public static class PdfGenerator
{
    public static MemoryStream CreatePdf()
    {
        try
        {
            using (var stream = new MemoryStream())
            {
                using (var writer = new PdfWriter(stream))
                {
                    using (var pdf = new PdfDocument(writer))
                    {
                        using (var document = new Document(pdf))
                        {
                            var paragraph = new Paragraph("Successfully generated PDF");
                            document.Add(paragraph);
                        }
                    }
                }
                stream.Position = 0;
                return stream;
            }
        }
        catch(Exception ex)
        {
            Console.WriteLine($"PDF Generation Failed: {ex}");
            return null;
        }
    }
}

Key Takeaways

1. Breaking changes in iText7 v8+ require explicit Bouncy Castle dependencies
2. .NET MAUI needs both:
   • Crypto adapter package (itext7.bouncy-castle-adapter)
   • Actual crypto implementation (Portable.BouncyCastle)
3. The environment variable workaround addresses platform-specific initialization issues
4. Always verify package versions are compatible across dependencies

Critical Implementation Notes

1. Dispose all PDF objects (PdfWriter, PdfDocument, Document) properly
2. Reset stream position to 0 before returning MemoryStream
3. Avoid mixing different versions of iText7 packages

For additional troubleshooting, consult iText7's official breaking changes documentation regarding Bouncy Castle changes in 8.0.