Skip to footer content
  1. IronPDF
  2. IronPDF Blog
  3. Migration Guides
  4. migration from bitmiracle docotic pdf to ironpdf
MIGRATION GUIDES

How to Migrate from BitMiracle Docotic PDF to IronPDF in C#

Curtis Chau
Curtis Chau
Published:

BitMiracle Docotic PDF is a well-regarded .NET PDF library known for its 100% managed code architecture and extensive programmatic PDF manipulation capabilities. However, its modular add-on structure—requiring separate packages for HTML-to-PDF conversion, layout features, and other functionality—adds complexity to project management and licensing. This comprehensive guide provides a step-by-step migration path from BitMiracle Docotic PDF to IronPDF—a unified .NET PDF library with built-in Chromium-based HTML rendering and all features included in a single NuGet package.

Why Migrate from BitMiracle Docotic PDF to IronPDF?

While BitMiracle Docotic PDF offers robust PDF manipulation features, several factors drive development teams to seek alternatives with more streamlined architecture.

Package Architecture Comparison

BitMiracle Docotic PDF uses a modular add-on approach that requires multiple packages for full functionality:

AspectBitMiracle Docotic PDFIronPDF
HTML-to-PDFRequires separate add-on (HtmlToPdf)Built-in core feature
Package StructureCore + multiple add-onsSingle NuGet package
Licensing ModelPer-add-on licensingAll features included
API ComplexitySeparate namespaces per add-onUnified API
HTML EngineChromium (via add-on)Chromium (built-in)
Community SizeSmallerLarger, more resources
DocumentationTechnical referenceExtensive tutorials

Feature Parity

Both libraries support comprehensive PDF functionality:

FeatureBitMiracle Docotic PDFIronPDF
Create PDF from scratch✅✅
HTML to PDF✅ (add-on required)✅ (built-in)
URL to PDF✅ (add-on required)✅ (built-in)
PDF manipulation✅✅
Text extraction✅✅
Merge/Split✅✅
Digital signatures✅✅
Encryption✅✅
Form filling✅✅
PDF/A compliance✅✅

Key Differences in Approach

BitMiracle Docotic PDF uses canvas-based drawing with coordinate positioning (canvas.DrawString(x, y, text)), while IronPDF leverages HTML/CSS for layout and positioning. This represents a paradigm shift that simplifies content creation for developers familiar with web technologies.

Pre-Migration Preparation

Prerequisites

Ensure your environment meets these requirements:

  • .NET Framework 4.6.2+ or .NET Core 3.1 / .NET 5-9
  • Visual Studio 2019+ or VS Code with C# extension
  • NuGet Package Manager access
  • IronPDF license key (free trial available at ironpdf.com)

Audit BitMiracle Docotic PDF Usage

Run these commands in your solution directory to identify all Docotic.Pdf references:

# Find all Docotic.Pdf usages in your codebase
grep -r "using BitMiracle.Docotic" --include="*.cs" .
grep -r "PdfDocument\|PdfPage\|PdfCanvas" --include="*.cs" .

# Find NuGet package references
grep -r "Docotic.Pdf" --include="*.csproj" .
# Find all Docotic.Pdf usages in your codebase
grep -r "using BitMiracle.Docotic" --include="*.cs" .
grep -r "PdfDocument\|PdfPage\|PdfCanvas" --include="*.cs" .

# Find NuGet package references
grep -r "Docotic.Pdf" --include="*.csproj" .
SHELL

Breaking Changes to Anticipate

ChangeBitMiracle Docotic PDFIronPDFImpact
HTML renderingRequires HtmlToPdf add-onBuilt-inRemove add-on package
Page indexing0-based (Pages[0])0-based (Pages[0])No change needed
Coordinate systemBottom-left originHTML/CSS flowUse CSS for positioning
Canvas drawingPdfCanvas.DrawText()HTML markupParadigm shift
Text extractionpage.GetText()pdf.ExtractAllText()Method name change
Document loadingnew PdfDocument(path)PdfDocument.FromFile(path)Constructor → static method
Savingdocument.Save(path)pdf.SaveAs(path)Method name change
DisposalIDisposable patternNot requiredSimpler resource management

Step-by-Step Migration Process

Step 1: Update NuGet Packages

Remove BitMiracle Docotic PDF packages and install IronPDF:

# Remove Docotic.Pdf packages
dotnet remove package BitMiracle.Docotic.Pdf
dotnet remove package BitMiracle.Docotic.Pdf.HtmlToPdf
dotnet remove package BitMiracle.Docotic.Pdf.Layout

# Install IronPDF
dotnet add package IronPdf
# Remove Docotic.Pdf packages
dotnet remove package BitMiracle.Docotic.Pdf
dotnet remove package BitMiracle.Docotic.Pdf.HtmlToPdf
dotnet remove package BitMiracle.Docotic.Pdf.Layout

# Install IronPDF
dotnet add package IronPdf
SHELL

Step 2: Update Namespace References

Replace BitMiracle Docotic PDF namespaces with IronPDF:

// Remove these
using BitMiracle.Docotic.Pdf;
using BitMiracle.Docotic.Pdf.Layout;
using BitMiracle.Docotic.Pdf.HtmlToPdf;

// Add this
using IronPdf;
// Remove these
using BitMiracle.Docotic.Pdf;
using BitMiracle.Docotic.Pdf.Layout;
using BitMiracle.Docotic.Pdf.HtmlToPdf;

// Add this
using IronPdf;
$vbLabelText   $csharpLabel

Step 3: Configure License

// Add at application startup (Program.cs or Global.asax)
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
// Add at application startup (Program.cs or Global.asax)
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
$vbLabelText   $csharpLabel

Complete API Migration Reference

Document Operations

TaskBitMiracle Docotic PDFIronPDF
Create empty documentnew PdfDocument()new PdfDocument()
Load from filenew PdfDocument(path)PdfDocument.FromFile(path)
Load from streamPdfDocument.Load(stream)PdfDocument.FromStream(stream)
Load from bytesPdfDocument.Load(bytes)PdfDocument.FromBinaryData(bytes)
Save to filedocument.Save(path)pdf.SaveAs(path)
Get page countdocument.PageCountpdf.PageCount
Close/Disposedocument.Dispose()Not required

HTML to PDF Conversion

TaskBitMiracle Docotic PDF (HtmlToPdf Add-on)IronPDF
HTML string to PDFHtmlConverter.Create(html).ToPdf()renderer.RenderHtmlAsPdf(html)
HTML file to PDFHtmlConverter.Create(new Uri(filePath)).ToPdf()renderer.RenderHtmlFileAsPdf(path)
URL to PDFHtmlConverter.Create(new Uri(url)).ToPdf()renderer.RenderUrlAsPdf(url)
Set page sizeoptions.PageSize = PageSize.A4renderer.RenderingOptions.PaperSize = PdfPaperSize.A4
Set marginsoptions.PageMargins = new Margins(20)renderer.RenderingOptions.MarginTop = 20

Merge and Split Operations

TaskBitMiracle Docotic PDFIronPDF
Merge documentsdoc1.Append(doc2)PdfDocument.Merge(pdf1, pdf2)
Split documentdocument.CopyPage(index) to new docpdf.CopyPages(start, end)

Code Migration Examples

HTML to PDF Conversion

The most common operation demonstrates the significant simplification IronPDF provides.

BitMiracle Docotic PDF Implementation:

// NuGet: Install-Package Docotic.Pdf
using BitMiracle.Docotic.Pdf;
using System;

class Program
{
    static void Main()
    {
        using (var pdf = new PdfDocument())
        {
            string html = "<html><body><h1>Hello World</h1><p>This is HTML to PDF conversion.</p></body></html>";

            pdf.CreatePage(html);
            pdf.Save("output.pdf");
        }

        Console.WriteLine("PDF created successfully");
    }
}
// NuGet: Install-Package Docotic.Pdf
using BitMiracle.Docotic.Pdf;
using System;

class Program
{
    static void Main()
    {
        using (var pdf = new PdfDocument())
        {
            string html = "<html><body><h1>Hello World</h1><p>This is HTML to PDF conversion.</p></body></html>";

            pdf.CreatePage(html);
            pdf.Save("output.pdf");
        }

        Console.WriteLine("PDF created successfully");
    }
}
$vbLabelText   $csharpLabel

IronPDF Implementation:

// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        string html = "<html><body><h1>Hello World</h1><p>This is HTML to PDF conversion.</p></body></html>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("output.pdf");

        Console.WriteLine("PDF created successfully");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        string html = "<html><body><h1>Hello World</h1><p>This is HTML to PDF conversion.</p></body></html>";

        var pdf = renderer.RenderHtmlAsPdf(html);
        pdf.SaveAs("output.pdf");

        Console.WriteLine("PDF created successfully");
    }
}
$vbLabelText   $csharpLabel

IronPDF eliminates the using statement requirement and provides a dedicated ChromePdfRenderer class that clearly indicates its Chromium-based rendering capability. For more HTML conversion options, see the HTML to PDF documentation.

Merging Multiple PDFs

BitMiracle Docotic PDF Implementation:

// NuGet: Install-Package Docotic.Pdf
using BitMiracle.Docotic.Pdf;
using System;

class Program
{
    static void Main()
    {
        using (var pdf1 = new PdfDocument("document1.pdf"))
        using (var pdf2 = new PdfDocument("document2.pdf"))
        {
            pdf1.Append(pdf2);
            pdf1.Save("merged.pdf");
        }

        Console.WriteLine("PDFs merged successfully");
    }
}
// NuGet: Install-Package Docotic.Pdf
using BitMiracle.Docotic.Pdf;
using System;

class Program
{
    static void Main()
    {
        using (var pdf1 = new PdfDocument("document1.pdf"))
        using (var pdf2 = new PdfDocument("document2.pdf"))
        {
            pdf1.Append(pdf2);
            pdf1.Save("merged.pdf");
        }

        Console.WriteLine("PDFs merged successfully");
    }
}
$vbLabelText   $csharpLabel

IronPDF Implementation:

// NuGet: Install-Package IronPdf
using IronPdf;
using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var pdf1 = PdfDocument.FromFile("document1.pdf");
        var pdf2 = PdfDocument.FromFile("document2.pdf");

        var merged = PdfDocument.Merge(new List<PdfDocument> { pdf1, pdf2 });
        merged.SaveAs("merged.pdf");

        Console.WriteLine("PDFs merged successfully");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var pdf1 = PdfDocument.FromFile("document1.pdf");
        var pdf2 = PdfDocument.FromFile("document2.pdf");

        var merged = PdfDocument.Merge(new List<PdfDocument> { pdf1, pdf2 });
        merged.SaveAs("merged.pdf");

        Console.WriteLine("PDFs merged successfully");
    }
}
$vbLabelText   $csharpLabel

IronPDF's static Merge method accepts multiple documents directly, providing a cleaner API than the iterative Append pattern. For more options, see the PDF merging documentation.

Text Extraction

BitMiracle Docotic PDF Implementation:

// NuGet: Install-Package Docotic.Pdf
using BitMiracle.Docotic.Pdf;
using System;

class Program
{
    static void Main()
    {
        using (var pdf = new PdfDocument("document.pdf"))
        {
            string allText = "";

            foreach (var page in pdf.Pages)
            {
                allText += page.GetText();
            }

            Console.WriteLine("Extracted text:");
            Console.WriteLine(allText);
        }
    }
}
// NuGet: Install-Package Docotic.Pdf
using BitMiracle.Docotic.Pdf;
using System;

class Program
{
    static void Main()
    {
        using (var pdf = new PdfDocument("document.pdf"))
        {
            string allText = "";

            foreach (var page in pdf.Pages)
            {
                allText += page.GetText();
            }

            Console.WriteLine("Extracted text:");
            Console.WriteLine(allText);
        }
    }
}
$vbLabelText   $csharpLabel

IronPDF Implementation:

// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var pdf = PdfDocument.FromFile("document.pdf");
        string allText = pdf.ExtractAllText();

        Console.WriteLine("Extracted text:");
        Console.WriteLine(allText);
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var pdf = PdfDocument.FromFile("document.pdf");
        string allText = pdf.ExtractAllText();

        Console.WriteLine("Extracted text:");
        Console.WriteLine(allText);
    }
}
$vbLabelText   $csharpLabel

IronPDF reduces the text extraction from a multi-line loop to a single method call. For more extraction options, see the text extraction documentation.

Password Protection and Encryption

IronPDF Implementation:

using IronPdf;

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Confidential Document</h1>");

// Set security
pdf.SecuritySettings.UserPassword = "userPassword";
pdf.SecuritySettings.OwnerPassword = "ownerPassword";
pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.FullPrintRights;
pdf.SecuritySettings.AllowUserCopyPasteContent = false;

pdf.SaveAs("protected.pdf");
using IronPdf;

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<h1>Confidential Document</h1>");

// Set security
pdf.SecuritySettings.UserPassword = "userPassword";
pdf.SecuritySettings.OwnerPassword = "ownerPassword";
pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.FullPrintRights;
pdf.SecuritySettings.AllowUserCopyPasteContent = false;

pdf.SaveAs("protected.pdf");
$vbLabelText   $csharpLabel

For comprehensive security options, see the encryption documentation.

Headers and Footers

IronPDF Implementation:

using IronPdf;

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align:center; font-size:12px;'>
            Company Header - Confidential
        </div>",
    DrawDividerLine = true,
    MaxHeight = 30
};

renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align:center; font-size:10px;'>
            Page {page} of {total-pages}
        </div>",
    DrawDividerLine = true,
    MaxHeight = 25
};

var pdf = renderer.RenderHtmlAsPdf("<h1>Document Content</h1>");
pdf.SaveAs("with_headers.pdf");
using IronPdf;

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align:center; font-size:12px;'>
            Company Header - Confidential
        </div>",
    DrawDividerLine = true,
    MaxHeight = 30
};

renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align:center; font-size:10px;'>
            Page {page} of {total-pages}
        </div>",
    DrawDividerLine = true,
    MaxHeight = 25
};

var pdf = renderer.RenderHtmlAsPdf("<h1>Document Content</h1>");
pdf.SaveAs("with_headers.pdf");
$vbLabelText   $csharpLabel

IronPDF supports placeholder tokens like {page} and {total-pages} for dynamic page numbering. For more options, see the headers and footers documentation.

Critical Migration Notes

Canvas to HTML Paradigm Shift

BitMiracle Docotic PDF's canvas-based drawing approach must be converted to HTML with CSS positioning:

BitMiracle Docotic PDF Pattern:

var canvas = pdfPage.Canvas;
canvas.DrawString(50, 50, "Hello, World!");
var canvas = pdfPage.Canvas;
canvas.DrawString(50, 50, "Hello, World!");
$vbLabelText   $csharpLabel

IronPDF Pattern:

var html = "<div style='position:absolute; left:50px; top:50px;'>Hello, World!</div>";
var pdf = renderer.RenderHtmlAsPdf(html);
var html = "<div style='position:absolute; left:50px; top:50px;'>Hello, World!</div>";
var pdf = renderer.RenderHtmlAsPdf(html);
$vbLabelText   $csharpLabel

Same Page Indexing

Both libraries use 0-based indexing (Pages[0] is the first page)—no changes needed for page access code.

Disposal Not Required

IronPDF doesn't require using statements for memory management, simplifying code structure:

// BitMiracle Docotic PDF - disposal required
using (var pdf = new PdfDocument("input.pdf"))
{
    // operations
}

// IronPDF - disposal optional
var pdf = PdfDocument.FromFile("input.pdf");
// operations - no using statement needed
// BitMiracle Docotic PDF - disposal required
using (var pdf = new PdfDocument("input.pdf"))
{
    // operations
}

// IronPDF - disposal optional
var pdf = PdfDocument.FromFile("input.pdf");
// operations - no using statement needed
$vbLabelText   $csharpLabel

Async Support

BitMiracle Docotic PDF's HtmlToPdf add-on requires async patterns everywhere. IronPDF supports both synchronous and asynchronous methods:

// Synchronous
var pdf = renderer.RenderHtmlAsPdf(html);

// Asynchronous
var pdf = await renderer.RenderHtmlAsPdfAsync(html);
// Synchronous
var pdf = renderer.RenderHtmlAsPdf(html);

// Asynchronous
var pdf = await renderer.RenderHtmlAsPdfAsync(html);
$vbLabelText   $csharpLabel

ASP.NET Core Integration

IronPDF Pattern:

[ApiController]
[Route("[controller]")]
public class PdfController : ControllerBase
{
    [HttpGet("generate")]
    public IActionResult GeneratePdf()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Report</h1>");

        return File(pdf.BinaryData, "application/pdf", "report.pdf");
    }

    [HttpGet("generate-async")]
    public async Task<IActionResult> GeneratePdfAsync()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Report</h1>");

        return File(pdf.Stream, "application/pdf", "report.pdf");
    }
}
[ApiController]
[Route("[controller]")]
public class PdfController : ControllerBase
{
    [HttpGet("generate")]
    public IActionResult GeneratePdf()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Report</h1>");

        return File(pdf.BinaryData, "application/pdf", "report.pdf");
    }

    [HttpGet("generate-async")]
    public async Task<IActionResult> GeneratePdfAsync()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Report</h1>");

        return File(pdf.Stream, "application/pdf", "report.pdf");
    }
}
$vbLabelText   $csharpLabel

Post-Migration Checklist

After completing the code migration, verify the following:

  • Run all unit tests to verify PDF generation works correctly
  • Compare PDF output quality (IronPDF's Chromium engine may render slightly differently—usually better)
  • Verify text extraction accuracy
  • Test form filling functionality
  • Validate digital signatures if applicable
  • Performance test batch operations
  • Test in all target environments
  • Update CI/CD pipelines
  • Remove Docotic.Pdf license files

Future-Proofing Your PDF Infrastructure

With .NET 10 on the horizon and C# 14 introducing new language features, choosing a PDF library with a unified architecture simplifies dependency management and ensures consistent feature availability. IronPDF's single-package approach means you won't need to track multiple add-on version compatibility as projects extend into 2025 and 2026.

Additional Resources

Migrating from BitMiracle Docotic PDF to IronPDF eliminates the complexity of managing multiple add-on packages while providing the same Chromium-based HTML rendering capabilities. The transition from canvas-based drawing to HTML/CSS positioning leverages web development skills most .NET developers already possess, resulting in more maintainable PDF generation code.

Curtis Chau
Curtis Chau
  Chat with engineering team now
Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...

Read More

Related Articles

30-day trial → Full product. No limits. No card. Start Free Trial