iText 7で発生するUnknown PdfExceptionの解決方法（.NET MAUI）

問題概要

.NET MAUIアプリケーションでiText 7を使用してPDFを生成する際、以下の例外が発生する場合があります:

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

エラーはPDF生成処理中、特にPdfWriterオブジェクトの作成時:

var writer = new PdfWriter(stream);

典型的な発生ケース

• iText 7のバージョンが7.8.0以上の場合
• BouncyCastle関連の依存関係が適切に設定されていない場合
• .NET MAUIやモバイル環境での実行時

public static MemoryStream CreatePdf()
{
    using (var stream = new MemoryStream())
    {
        var writer = new PdfWriter(stream); // ここで例外発生!
        var pdf = new PdfDocument(writer);
        var document = new Document(pdf);
        
        document.Add(new Paragraph("hello"));
        document.Close();
        
        stream.Position = 0;
        return stream;
    }
}

根本原因

iText 7のバージョン8.0以降で依存関係が大きく変更されました:

1. BouncyCastleライブラリへの依存管理が変更
2. 明示的なアダプターの指定が必要に
3. 特に.NET MAUIのようなクロスプラットフォーム環境で顕著

公式ドキュメントの記載

iText 8 公式変更ログにて:

BouncyCastle Changes
From version 8, explicit adapter selection is required to avoid dependency conflicts.

解決方法

方法1: BouncyCastleアダプターのインストール（推奨）

以下のNuGetパッケージをプロジェクトに追加:

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

.NET CLIを使用する場合

dotnet add package itext7.bouncy-castle-adapter --version 8.0.5
dotnet add package Portable.BouncyCastle --version 1.9.0

方法2: 環境変数による明示的指定

Program.csに以下の初期化コードを追加:

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        // ソリューション1: 環境変数でアダプター指定
        Environment.SetEnvironmentVariable(
            "ITEXT_BOUNCY_CASTLE_FACTORY_NAME", 
            "bouncy-castle"
        );
        
        var builder = MauiApp.CreateBuilder();
        // 通常のMAUI初期化処理...
        return builder.Build();
    }
}

方法3: コードからの直接初期化（高度なケース）

アプリケーション起動時に直接ファクトリを登録:

using iText.Commons.Bouncycastle;

public partial class App : Application
{
    public App()
    {
        // ソリューション2: 明示的なファクトリ登録
        BouncyCastleFactory.SetFactory(
            new Org.BouncyCastleFactory() // アダプタークラス
        );
        
        InitializeComponent();
        MainPage = new MainPage();
    }
}

動作確認済み環境

コンポーネント	推奨バージョン
iText7	8.0.5+
.NET MAUI	7.0+
BouncyCastle	1.9.0

重要な注意点

1. パッケージバージョンの整合性
   itext7.bouncy-castle-adapterはiText7本体とメジャーバージョンを一致させる必要あり

2. ビルド後のクリーンアップ
   パッケージ追加後は完全なリビルドが必要（特にAndroid/iOSプロジェクト）

3. FIPS要件がある場合:
   itext7.bouncy-castle-fips-adapterを使用し環境変数をbouncy-castle-fipsに設定

完全なサンプルコード

public static MemoryStream CreatePdf()
{
    using (var stream = new MemoryStream())
    {
        // 問題解消後のコード
        using var writer = new PdfWriter(stream);
        using var pdf = new PdfDocument(writer);
        using var document = new Document(pdf);
        
        document.Add(new Paragraph("Hello .NET MAUI with iText7!"));
        document.Close();
        
        stream.Position = 0;
        return stream;
    }
}

参考リソース

• iText公式：BouncyCastle変更点
• NuGet：itext7.bouncy-castle-adapter
• Portable.BouncyCastle