BitMiracle Docotic.Pdf to IronPDF: The Honest Walkthrough

Docotic.Pdf is a genuinely well-engineered library. The API is clean, the NuGet package is lean, and it handles PDF parsing and programmatic construction reliably across platforms. The migration decision rarely comes from Docotic.Pdf breaking. It comes from how its HTML-to-PDF story is packaged.

The most common trigger: someone adds a feature that requires rendering a complex HTML template to PDF. Docotic.Pdf supports HTML rendering, but only via the separate BitMiracle.Docotic.Pdf.HtmlToPdf add-on, which exposes an async-only HtmlConverter that downloads its own Chromium on first use. Teams that started on Docotic for parsing or programmatic construction often end up dragging the add-on into the dependency tree just to render one invoice template, and once that's in, the licensing and packaging story starts looking like a candidate for consolidation onto a single renderer-first library.

This article covers the troubleshooting patterns and API mapping for migrating from BitMiracle Docotic.Pdf to IronPDF. The migration is relatively low-drama because both are managed .NET libraries with no COM dependencies. The complexity concentrates in two places: the different mental model (Docotic's document construction plus a separate add-on for HTML vs IronPDF's unified renderer + document model), and any text extraction or annotation code that relies on Docotic's parse-side API.

Why Migrate

Neutral triggers teams run into:

1. HTML-to-PDF requires an add-on. Docotic.Pdf's HTML rendering lives in the separate BitMiracle.Docotic.Pdf.HtmlToPdf package. That add-on uses an async-only HtmlConverter and downloads its own Chromium on first use, so the dependency tree grows when you need HTML support.
2. CSS rendering fidelity. Programmatic document construction in Docotic doesn't match what a designer produces in HTML/CSS. IronPDF's Chromium renderer closes this gap for HTML-based workflows without a separate add-on.
3. Template maintenance burden. Programmatic PDF construction (positioning text objects, drawing borders) requires developer changes for every layout update. HTML templates can be maintained by non-developers.
4. Font handling complexity. Docotic requires explicit font loading and glyph management on the canvas side. IronPDF's Chromium renderer handles font resolution as a browser would.
5. Deployment simplicity. Both are managed .NET, but IronPDF's all-in-one approach (render + edit + security) reduces the number of libraries and add-on packages in the dependency tree.
6. Async / parallel patterns. Both libraries support concurrent use; evaluate under your specific load patterns.
7. API surface for new developers. ChromePdfRenderer.RenderHtmlAsPdf(html) is a shorter onboarding path than document construction for HTML-heavy workloads.
8. PDF/A output workflow. Both support PDF/A; test against your target compliance profile to compare output.
9. License changes. Evaluate current Docotic.Pdf pricing at bitmiracle.com for your usage scenario, including any per-add-on costs.
10. Consolidation. Teams combining parsing (Docotic) and rendering (HtmlToPdf add-on or something else) sometimes consolidate to one library.

Comparison Table

Migration Complexity Assessment

Effort by Feature

Decision Matrix

Before You Start

Prerequisites:

• .NET Framework 4.6.2+, .NET Core 3.1+, or .NET 5/6/7/8/9 (IronPDF supports the full modern range)
• IronPDF license key (license setup)
• Baseline PDF outputs captured for visual regression

Find all Docotic.Pdf references:

# Find all files with Docotic imports
rg "using BitMiracle" --type cs -l

# Find all PdfDocument usages (Docotic's main class)
rg "PdfDocument" --type cs

# Find text extraction calls
rg "GetText|GetWords|TextData" --type cs

# Find annotation references
rg "Annotations|PdfAnnotation" --type cs

# Find drawing / graphics operations
rg "PdfCanvas|DrawString|DrawLine|HtmlConverter" --type cs

Remove Docotic, add IronPDF:

dotnet remove package BitMiracle.Docotic.Pdf
dotnet remove package BitMiracle.Docotic.Pdf.HtmlToPdf
dotnet add package IronPdf
dotnet restore

PowerShell: Uninstall-Package BitMiracle.Docotic.Pdf (plus the HtmlToPdf add-on if installed) then Install-Package IronPdf.

Quick Start Migration (3 Steps)

Step 1: License Configuration

Before (Docotic.Pdf):

using BitMiracle.Docotic.Pdf;

// Docotic uses a license string set before any API call
PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

After (IronPDF):

using IronPdf;

// https://ironpdf.com/how-to/license-keys/
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

Step 2: Namespace Imports

Before:

using BitMiracle.Docotic.Pdf;
// HtmlConverter (from the HtmlToPdf add-on) also lives in BitMiracle.Docotic.Pdf

After:

using IronPdf;

Step 3: Basic PDF Operation

Before (Docotic, opening a PDF and extracting text):

using BitMiracle.Docotic.Pdf;

PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");
using var doc = new PdfDocument("input.pdf");
string text = doc.GetText();
Console.WriteLine(text);

After (IronPDF):

using IronPdf;

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
using var pdf = PdfDocument.FromFile("input.pdf");
// https://ironpdf.com/how-to/extract-text-and-images/
string text = pdf.ExtractAllText();
Console.WriteLine(text);

API Mapping Tables

Namespace Mapping

Core Class Mapping

Document Loading Methods

Page Operations

Merge/Split

Four Complete Before/After Migrations

1. HTML to PDF

Before (Docotic with the HtmlToPdf add-on):

using System;
using System.Threading.Tasks;
using BitMiracle.Docotic.Pdf;

class Program
{
    static async Task Main()
    {
        PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

        // HtmlConverter is async-only and downloads Chromium on first use
        using var converter = await HtmlConverter.CreateAsync();

        var options = new HtmlConversionOptions();
        options.Page.SetSize(PdfPaperSize.A4);
        options.Page.MarginTop = 20;
        options.Page.MarginBottom = 20;

        string html = @"<html>
            <body style='font-family:Arial; padding:40px'>
                <h1 style='color:#2563EB'>Invoice #2071</h1>
                <p>Amount: <strong>$1,200.00</strong></p>
                <p>Due: 2025-12-01</p>
            </body>
        </html>";

        using var pdf = await converter.CreatePdfFromStringAsync(html, options);
        pdf.Save("invoice.pdf");
        Console.WriteLine("Saved invoice.pdf");
    }
}

After (IronPDF, built-in renderer, no add-on):

using System;
using IronPdf;

class Program
{
    static void Main()
    {
        // https://ironpdf.com/how-to/html-string-to-pdf/
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;

        // HTML template — can be maintained separately from code
        string html = @"<html>
            <body style='font-family:Arial; padding:40px'>
                <h1 style='color:#2563EB'>Invoice #2071</h1>
                <p>Amount: <strong>$1,200.00</strong></p>
                <p>Due: 2025-12-01</p>
            </body>
        </html>";

        using var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("invoice.pdf");
        Console.WriteLine("Saved invoice.pdf");
    }
}

2. Merge PDFs

Before (Docotic.Pdf):

using System;
using BitMiracle.Docotic.Pdf;

class Program
{
    static void Main()
    {
        PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

        // PdfDocument.Append accepts a file path, Stream, or byte[] --
        // not another PdfDocument instance.
        using var pdf1 = new PdfDocument("part1.pdf");
        pdf1.Append("part2.pdf");
        pdf1.Append("part3.pdf");
        pdf1.Save("merged.pdf");

        Console.WriteLine("Merged to merged.pdf");
    }
}

After (IronPDF):

using System;
using IronPdf;

class Program
{
    static void Main()
    {
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        // https://ironpdf.com/how-to/merge-or-split-pdfs/
        var pdf1 = PdfDocument.FromFile("part1.pdf");
        var pdf2 = PdfDocument.FromFile("part2.pdf");
        var pdf3 = PdfDocument.FromFile("part3.pdf");

        using var merged = PdfDocument.Merge(pdf1, pdf2, pdf3);
        merged.SaveAs("merged.pdf");
        Console.WriteLine("Merged to merged.pdf");
    }
}

3. Watermark

Before (Docotic.Pdf):

using System;
using BitMiracle.Docotic.Pdf;

class Program
{
    static void Main()
    {
        PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

        using var doc = new PdfDocument("input.pdf");

        foreach (var page in doc.Pages)
        {
            var canvas = page.Canvas;

            // Save/restore graphics state around the watermark
            canvas.SaveState();
            canvas.SetTransparency(0.3); // 30% opacity

            canvas.FontSize = 48;
            canvas.FillColor = new PdfRgbColor(200, 0, 0);

            // Rotate around the page center, then draw the watermark text
            canvas.Rotate(45, page.Width / 2, page.Height / 2);
            canvas.DrawString(page.Width / 4, page.Height / 2, "CONFIDENTIAL");

            canvas.RestoreState();
        }

        doc.Save("watermarked.pdf");
        Console.WriteLine("Watermarked PDF saved");
    }
}

After (IronPDF):

using System;
using IronPdf;
using IronPdf.Editing;

class Program
{
    static void Main()
    {
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        using var pdf = PdfDocument.FromFile("input.pdf");

        // https://ironpdf.com/how-to/stamp-text-image/
        var stamper = new TextStamper
        {
            Text = "CONFIDENTIAL",
            FontSize = 48,
            Opacity = 40,
            Rotation = 45,
            VerticalAlignment = VerticalAlignment.Middle,
            HorizontalAlignment = HorizontalAlignment.Center
        };

        // Applies to all pages by default
        pdf.ApplyStamp(stamper);
        pdf.SaveAs("watermarked.pdf");
        Console.WriteLine("Watermarked PDF saved");
    }
}

4. Password Protection

Before (Docotic.Pdf):

using System;
using BitMiracle.Docotic.Pdf;

class Program
{
    static void Main()
    {
        PdfInfo.SetLicenseKey("YOUR-LICENSE-KEY");

        using var doc = new PdfDocument("input.pdf");

        // Docotic exposes encryption through a single Encrypt() call
        var permissions = PdfPermissions.Printing |
                          PdfPermissions.ContentExtraction;

        doc.Encrypt(
            ownerPassword: "owner456",
            userPassword: "user123",
            permissions: permissions,
            encryptionAlgorithm: PdfEncryptionAlgorithm.Aes256
        );

        doc.Save("protected.pdf");
        Console.WriteLine("Password protected PDF saved");
    }
}

After (IronPDF):

using System;
using IronPdf;

class Program
{
    static void Main()
    {
        IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

        // https://ironpdf.com/how-to/pdf-permissions-passwords/
        using var pdf = PdfDocument.FromFile("input.pdf");

        pdf.SecuritySettings.UserPassword = "user123";
        pdf.SecuritySettings.OwnerPassword = "owner456";
        pdf.SecuritySettings.AllowUserPrinting =
            IronPdf.Security.PdfPrintSecurity.FullPrintRights;
        pdf.SecuritySettings.AllowUserCopyPasteContent = true;

        pdf.SaveAs("protected.pdf");
        Console.WriteLine("Password protected PDF saved");
    }
}

Critical Migration Notes

Text Extraction Differences

Docotic.Pdf has a detailed text model. It exposes per-word bounds via page.GetWords(), with chunk.Bounds.Left and chunk.Bounds.Top for positional data. IronPDF's text extraction returns the text content with less detail on positional data. If your code depends on character- or word-level positioning (e.g., table detection, column parsing), test IronPDF's output carefully before committing.

// Docotic -- detailed word data with bounds
using var doc = new PdfDocument("input.pdf");
foreach (var page in doc.Pages)
{
    foreach (var word in page.GetWords())
    {
        Console.WriteLine($"{word.Text} at ({word.Bounds.Left}, {word.Bounds.Top})");
    }
}

// IronPDF -- text content
// https://ironpdf.com/how-to/extract-text-and-images/
using var pdf = PdfDocument.FromFile("input.pdf");
string allText = pdf.ExtractAllText();
for (int i = 0; i < pdf.PageCount; i++)
{
    string pageText = pdf.ExtractTextFromPage(i);
    Console.WriteLine($"--- Page {i + 1} ---\n{pageText}");
}

If you need positional data after migration, review the current IronPDF text extraction API at https://ironpdf.com/how-to/extract-text-and-images/.

Annotation API Differences

Docotic.Pdf's annotation model is explicit. You create PdfAnnotation objects on page.Annotations with coordinates and properties. IronPDF has annotation support, but the API shape differs. Teams with heavy annotation workflows should test annotation round-trips (create, save, reload, verify) before migrating.

See IronPDF annotations docs for current API.

Page Indexing

Both Docotic.Pdf and IronPDF use 0-based page indexing. This makes the page index migration simpler than moving from 1-based libraries, but still audit all page index references. Off-by-one errors are silent.

Canvas vs Stamper

Docotic's PdfCanvas is a drawing context. You position everything with coordinates and explicit graphics state. IronPDF's stamper model is alignment-based with offsets. If you have precise coordinate requirements for stamps or overlays, check the stamper's IsStampedOnAllPages, HorizontalOffset, and VerticalOffset properties. For highly precise positioning, IronPDF's HTML-stamp approach (stamping a rendered HTML element) often gives finer control than the basic stamper API.

Performance Considerations

Native Dependencies

Docotic.Pdf core is fully managed and has no native interop requirements. Docotic's HtmlToPdf add-on downloads its own Chromium and brings the same browser-process model that IronPDF uses. IronPDF's Chromium renderer requires the standard Linux system libraries (libnss3, libatk-bridge2.0-0, libdrm2, etc.) on Linux deployments. If your existing Docotic workload is parse-only with no HtmlToPdf add-on, the Linux dependency footprint will grow after the migration.

Renderer Reuse

If you're adding HTML-to-PDF as a new capability during this migration, reuse ChromePdfRenderer:

// Register in DI container as singleton in ASP.NET Core
services.AddSingleton<ChromePdfRenderer>();

// Or reuse at class level
private static readonly ChromePdfRenderer _renderer = new ChromePdfRenderer();

Memory Patterns

Docotic.Pdf documents are IDisposable. IronPDF PdfDocument is also IDisposable. The migration shouldn't change disposal discipline if your existing code uses using consistently. Audit for any PdfDocument instances created without using or explicit .Dispose() calls.

Parallel Workloads

If you generate PDFs in parallel, review IronPDF's concurrent rendering behavior at parallel examples. The Chromium renderer process is separate from the managed layer — concurrent requests share the renderer process differently than Docotic's in-process drawing API.

Migration Checklist

Pre-Migration

• [ ] Run rg "using BitMiracle" --type cs -l to find all affected files
• [ ] Capture baseline PDF outputs for visual regression comparison
• [ ] Identify all PdfCanvas drawing operations (will need refactoring to HTML or stamper)
• [ ] Note whether the HtmlToPdf add-on (HtmlConverter) is in use. That code maps to ChromePdfRenderer
• [ ] Inventory annotation-heavy code. Audit IronPDF annotation API parity
• [ ] Check form field editing usage. Audit IronPDF form API
• [ ] Note any character-level or per-word text extraction dependencies (page.GetWords())
• [ ] Confirm target .NET version supports IronPDF (4.6.2+, Core 3.1+, .NET 5/6/7/8/9)
• [ ] Test IronPDF output in parallel with Docotic before removing Docotic

Code Migration

• [ ] Replace BitMiracle.Docotic.Pdf (and .HtmlToPdf add-on) NuGet with IronPdf
• [ ] Replace PdfInfo.SetLicenseKey() with IronPdf.License.LicenseKey = "..."
• [ ] Replace using BitMiracle.Docotic.Pdf with using IronPdf
• [ ] Replace new PdfDocument("file.pdf") with PdfDocument.FromFile("file.pdf")
• [ ] Replace HtmlConverter.CreateAsync() + CreatePdfFromStringAsync with new ChromePdfRenderer().RenderHtmlAsPdf(...)
• [ ] Replace programmatic layout with HTML templates where feasible
• [ ] Replace PdfCanvas drawing with TextStamper, ImageStamper, or HTML
• [ ] Replace Docotic merge (pdf1.Append("file.pdf")) with PdfDocument.Merge(pdf1, pdf2, ...)
• [ ] Replace doc.Encrypt(...) with pdf.SecuritySettings properties
• [ ] Replace doc.GetText() / page.GetText() with pdf.ExtractAllText() / pdf.ExtractTextFromPage(i)
• [ ] Update annotation handling to IronPDF API. Audit coverage

Testing

• [ ] Visual comparison: programmatic layouts vs HTML-rendered equivalents
• [ ] Text extraction output. Compare per-word data if positional data is needed
• [ ] Annotation round-trip: create, save, reload, verify
• [ ] Password protection: open with user password, confirm owner restrictions
• [ ] Merge page count and order verification
• [ ] Test on Linux if target environment. Verify Chromium system library requirements
• [ ] Load test concurrent rendering if parallel workloads exist

Post-Migration

• [ ] Remove BitMiracle.Docotic.Pdf and BitMiracle.Docotic.Pdf.HtmlToPdf from all project files
• [ ] Update Docker images for Linux deployment with IronPDF Chromium dependencies
• [ ] Update internal documentation on PDF generation approach
• [ ] Archive Docotic license for audit purposes

One Last Thing

The Docotic.Pdf to IronPDF migration is generally straightforward for the common operations: loading, merging, and password protection. The complexity concentrates in annotation workflows and text extraction. If either is central to your use case, run a spike against the IronPDF API before committing to the migration path.

The real win for most teams isn't the API swap. It's collapsing the parse library plus the HtmlToPdf add-on plus the licensing for both into a single package that renders HTML like a browser. That removes the programmatic layout code no one wants to maintain, and it removes the add-on coordination that nobody enjoys auditing either.

Question for the comments: For teams that moved from a parse-focused PDF library (Docotic, iText, etc.) to a renderer-first library. How did you handle the text extraction use cases that didn't port cleanly? Did you keep the parse library alongside the renderer, or find a different approach?

The free trial is on NuGet if you want to test before committing.