Skip to footer content
MIGRATION GUIDES

How to Migrate from Easy PDF SDK to IronPDF in C#

Easy PDF SDK relies on several legacy technologies that create significant deployment and maintenance challenges in modern development environments.

Common Easy PDF SDK Deployment Issues

Developers frequently encounter these issues when working with Easy PDF SDK:

  • bcl.easypdf.interop.easypdfprinter.dll error loading
  • COM object that has been separated from its underlying RCW cannot be used
  • Timeout expired waiting for print job to complete
  • The printer operation failed because the service is not running
  • Error: Access denied (interactive session required)
  • Cannot find printer: BCL easyPDF Printer

These errors stem from Easy PDF SDK's fundamental architecture—it requires virtual printer drivers, COM interop, and interactive Windows sessions that simply don't exist in modern server environments.

Easy PDF SDK vs. IronPDF: Key Differences

FeatureEasy PDF SDKIronPDF
PlatformWindows-onlyWindows, Linux, macOS, Docker
Office DependencyRequiredNone
InstallationComplex MSI + printer driver + COMSimple NuGet package
Server SupportRequires interactive sessionRuns headless
HTML RenderingBasic (Office-based)Full Chromium (CSS3, JS)
.NET SupportLimited .NET CoreFull .NET 5/6/7/8/9
Async PatternCallback-basedNative async/await
Container SupportCannot runFull Docker/Kubernetes

Platform Limitations

Easy PDF SDK's exclusive reliance on Windows systems, requiring Microsoft Office installations for conversions, precludes support for Linux, macOS, or containerized environments like Docker. This dependency makes server setups cumbersome and limits service adoption to Windows environments—a significant constraint for teams practicing multi-platform DevOps or using containers for deployment.

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 Easy PDF SDK Usage

Run these commands in your solution directory to identify all Easy PDF SDK references:

# Find all BCL using statements
grep -r "using BCL" --include="*.cs" .

# Find Printer/PDFDocument usage
grep -r "Printer\|PDFDocument\|PDFConverter\|HTMLConverter" --include="*.cs" .

# Find COM interop references
grep -r "easyPDF\|BCL.easyPDF" --include="*.csproj" .

# Find configuration settings
grep -r "PageOrientation\|TimeOut\|PrintOffice" --include="*.cs" .
# Find all BCL using statements
grep -r "using BCL" --include="*.cs" .

# Find Printer/PDFDocument usage
grep -r "Printer\|PDFDocument\|PDFConverter\|HTMLConverter" --include="*.cs" .

# Find COM interop references
grep -r "easyPDF\|BCL.easyPDF" --include="*.csproj" .

# Find configuration settings
grep -r "PageOrientation\|TimeOut\|PrintOffice" --include="*.cs" .
SHELL

Breaking Changes to Anticipate

Easy PDF SDK PatternChange Required
new Printer()Use ChromePdfRenderer
PrintOfficeDocToPDF()Office conversion handled differently
RenderHTMLToPDF()RenderHtmlAsPdf()
COM interop referencesRemove entirely
Printer driver configNot needed
BeginPrintToFile() callbacksNative async/await
Interactive session requirementsRuns headless
1-based page indexing0-based indexing
Timeout in secondsTimeout in milliseconds

Step-by-Step Migration Process

Step 1: Remove Easy PDF SDK

Easy PDF SDK is typically installed via MSI installer, manual DLL references, or GAC registration. Remove all references:

  1. Uninstall BCL EasyPDF SDK from Programs and Features
  2. Remove DLL references from your project
  3. Remove COM interop references
  4. Clean up GAC entries if present

Step 2: Install IronPDF

# Install IronPDF
dotnet add package IronPdf
# Install IronPDF
dotnet add package IronPdf
SHELL

Or via Package Manager Console:

Install-Package IronPdf

Step 3: Update Namespace References

Replace Easy PDF SDK namespaces with IronPDF:

// Remove these
using BCL.easyPDF;
using BCL.easyPDF.Interop;
using BCL.easyPDF.PDFConverter;
using BCL.easyPDF.Printer;

// Add these
using IronPdf;
using IronPdf.Rendering;
// Remove these
using BCL.easyPDF;
using BCL.easyPDF.Interop;
using BCL.easyPDF.PDFConverter;
using BCL.easyPDF.Printer;

// Add these
using IronPdf;
using IronPdf.Rendering;
$vbLabelText   $csharpLabel

Complete API Migration Reference

Core Class Mapping

Easy PDF SDK ClassIronPDF EquivalentNotes
PrinterChromePdfRendererMain conversion class
PDFDocumentPdfDocumentDocument manipulation
HTMLConverterChromePdfRendererHTML conversion
PrinterConfigurationChromePdfRenderOptionsRendering options
PageOrientationPdfPaperOrientationPage orientation
PageSizePdfPaperSizePaper size
SecurityHandlerPdfDocument.SecuritySettingsSecurity options

PDF Creation Methods

Easy PDF SDK MethodIronPDF MethodNotes
printer.RenderHTMLToPDF(html, path)renderer.RenderHtmlAsPdf(html).SaveAs(path)HTML string
printer.RenderUrlToPDF(url, path)renderer.RenderUrlAsPdf(url).SaveAs(path)URL conversion
htmlConverter.ConvertHTML(html, doc)renderer.RenderHtmlAsPdf(html)HTML to PDF
htmlConverter.ConvertURL(url, doc)renderer.RenderUrlAsPdf(url)URL to PDF

PDF Manipulation Methods

Easy PDF SDK MethodIronPDF MethodNotes
doc.Append(doc2)PdfDocument.Merge(pdf1, pdf2)Merge PDFs
doc.ExtractPages(start, end)pdf.CopyPages(start, end)Extract pages
doc.DeletePage(index)pdf.RemovePage(index)Remove page
doc.GetPageCount()pdf.PageCountPage count
doc.Save(path)pdf.SaveAs(path)Save PDF
doc.Close()pdf.Dispose() or usingCleanup
doc.ExtractText()pdf.ExtractAllText()Text extraction

Configuration Options

Easy PDF SDK OptionIronPDF OptionNotes
config.TimeOutRenderingOptions.TimeoutTimeout (ms)
config.PageOrientation = LandscapeRenderingOptions.PaperOrientation = LandscapeOrientation
config.PageSize = A4RenderingOptions.PaperSize = PdfPaperSize.A4Paper size
config.MarginTop/Bottom/Left/RightRenderingOptions.MarginTop, etc.Margins

Code Migration Examples

HTML String to PDF

Easy PDF SDK Implementation:

// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf = new PDFDocument();
        var htmlConverter = new HTMLConverter();
        htmlConverter.ConvertHTML("<h1>Hello World</h1>", pdf);
        pdf.Save("output.pdf");
        pdf.Close();
    }
}
// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf = new PDFDocument();
        var htmlConverter = new HTMLConverter();
        htmlConverter.ConvertHTML("<h1>Hello World</h1>", pdf);
        pdf.Save("output.pdf");
        pdf.Close();
    }
}
$vbLabelText   $csharpLabel

IronPDF Implementation:

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");
        pdf.SaveAs("output.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");
        pdf.SaveAs("output.pdf");
    }
}
$vbLabelText   $csharpLabel

IronPDF eliminates the separate HTMLConverter class and manual Close() calls—resulting in cleaner, more maintainable code.

URL to PDF Conversion

Easy PDF SDK Implementation:

// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf = new PDFDocument();
        var htmlConverter = new HTMLConverter();
        htmlConverter.ConvertURL("https://example.com", pdf);
        pdf.Save("webpage.pdf");
        pdf.Close();
    }
}
// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf = new PDFDocument();
        var htmlConverter = new HTMLConverter();
        htmlConverter.ConvertURL("https://example.com", pdf);
        pdf.Save("webpage.pdf");
        pdf.Close();
    }
}
$vbLabelText   $csharpLabel

IronPDF Implementation:

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

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderUrlAsPdf("https://example.com");
        pdf.SaveAs("webpage.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderUrlAsPdf("https://example.com");
        pdf.SaveAs("webpage.pdf");
    }
}
$vbLabelText   $csharpLabel

Merging Multiple PDFs

Easy PDF SDK Implementation:

// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf1 = new PDFDocument("document1.pdf");
        var pdf2 = new PDFDocument("document2.pdf");
        pdf1.Append(pdf2);
        pdf1.Save("merged.pdf");
        pdf1.Close();
        pdf2.Close();
    }
}
// NuGet: Install-Package BCL.EasyPDF
using BCL.EasyPDF;
using System;

class Program
{
    static void Main()
    {
        var pdf1 = new PDFDocument("document1.pdf");
        var pdf2 = new PDFDocument("document2.pdf");
        pdf1.Append(pdf2);
        pdf1.Save("merged.pdf");
        pdf1.Close();
        pdf2.Close();
    }
}
$vbLabelText   $csharpLabel

IronPDF Implementation:

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

class Program
{
    static void Main()
    {
        var pdfs = new List<PdfDocument>
        {
            PdfDocument.FromFile("document1.pdf"),
            PdfDocument.FromFile("document2.pdf")
        };
        var merged = PdfDocument.Merge(pdfs);
        merged.SaveAs("merged.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var pdfs = new List<PdfDocument>
        {
            PdfDocument.FromFile("document1.pdf"),
            PdfDocument.FromFile("document2.pdf")
        };
        var merged = PdfDocument.Merge(pdfs);
        merged.SaveAs("merged.pdf");
    }
}
$vbLabelText   $csharpLabel

IronPDF's static Merge method accepts multiple documents directly, eliminating the manual Append loop pattern.

Password Protection

IronPDF Implementation:

using IronPdf;

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

// Set security
pdf.SecuritySettings.UserPassword = "user123";
pdf.SecuritySettings.OwnerPassword = "owner456";
pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.NoPrint;
pdf.SecuritySettings.AllowUserCopyPasteContent = false;
pdf.SecuritySettings.AllowUserEdits = PdfEditSecurity.NoEdit;

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

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

// Set security
pdf.SecuritySettings.UserPassword = "user123";
pdf.SecuritySettings.OwnerPassword = "owner456";
pdf.SecuritySettings.AllowUserPrinting = PdfPrintSecurity.NoPrint;
pdf.SecuritySettings.AllowUserCopyPasteContent = false;
pdf.SecuritySettings.AllowUserEdits = PdfEditSecurity.NoEdit;

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

Headers and Footers

Easy PDF SDK doesn't have native header/footer support—headers and footers must be included in the source HTML. IronPDF provides dedicated functionality:

using IronPdf;

var renderer = new ChromePdfRenderer();

renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='text-align:center; font-size:12px; font-family:Arial;'>
            Company Name - 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>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; font-family:Arial;'>
            Company Name - 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>Content</h1>");
pdf.SaveAs("with_headers.pdf");
$vbLabelText   $csharpLabel

For more options, see the headers and footers documentation.

Async PDF Generation

Easy PDF SDK uses callback-based async patterns. IronPDF supports native async/await:

Easy PDF SDK Implementation:

using BCL.easyPDF;

Printer printer = new Printer();

// BCL uses callback-based async
printer.BeginPrintToFile(
    "https://example.com",
    "output.pdf",
    OnPrintComplete,
    OnPrintError
);

Console.ReadLine();
printer.Dispose();
using BCL.easyPDF;

Printer printer = new Printer();

// BCL uses callback-based async
printer.BeginPrintToFile(
    "https://example.com",
    "output.pdf",
    OnPrintComplete,
    OnPrintError
);

Console.ReadLine();
printer.Dispose();
$vbLabelText   $csharpLabel

IronPDF Implementation:

using IronPdf;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var renderer = new ChromePdfRenderer();

        // Native async/await
        var pdf = await renderer.RenderUrlAsPdfAsync("https://example.com");
        await pdf.SaveAsAsync("output.pdf");

        Console.WriteLine("PDF created: output.pdf");
    }
}
using IronPdf;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var renderer = new ChromePdfRenderer();

        // Native async/await
        var pdf = await renderer.RenderUrlAsPdfAsync("https://example.com");
        await pdf.SaveAsAsync("output.pdf");

        Console.WriteLine("PDF created: output.pdf");
    }
}
$vbLabelText   $csharpLabel

Critical Migration Notes

Page Index Change

Easy PDF SDK uses 1-based indexing. IronPDF uses 0-based indexing:

// Easy PDF SDK: 1-based
doc.ExtractPages(1, 5);

// IronPDF: 0-based
pdf.CopyPages(0, 4);
// Easy PDF SDK: 1-based
doc.ExtractPages(1, 5);

// IronPDF: 0-based
pdf.CopyPages(0, 4);
$vbLabelText   $csharpLabel

Timeout in Milliseconds

Easy PDF SDK uses seconds for timeout values. IronPDF uses milliseconds:

// Easy PDF SDK: seconds
config.TimeOut = 120;

// IronPDF: milliseconds
renderer.RenderingOptions.Timeout = 120000;
// Easy PDF SDK: seconds
config.TimeOut = 120;

// IronPDF: milliseconds
renderer.RenderingOptions.Timeout = 120000;
$vbLabelText   $csharpLabel

ASP.NET Core Integration

Easy PDF SDK struggles in web contexts due to interactive session requirements.

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

Docker Deployment

Easy PDF SDK cannot run in Docker containers—it requires Windows containers, Microsoft Office, virtual printer drivers, and interactive desktop sessions. This is fundamentally incompatible with containerization.

IronPDF Docker Configuration:

FROM mcr.microsoft.com/dotnet/aspnet:8.0

# Install Chromium dependencies
RUN apt-get update && apt-get install -y \
    libc6 libgdiplus libx11-6 libxcomposite1 \
    libxdamage1 libxrandr2 libxss1 libxtst6 \
    libnss3 libatk-bridge2.0-0 libgtk-3-0 \
    libgbm1 libasound2 fonts-liberation \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Troubleshooting Common Migration Issues

Issue: Printer Not Found

Symptom: Cannot find printer: BCL easyPDF Printer

Solution: IronPDF doesn't need printer drivers:

// Just use the renderer directly
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
// Just use the renderer directly
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
$vbLabelText   $csharpLabel

Issue: COM Interop Errors

Symptom: DLL error loading or RCW errors

Solution: Remove all COM references and use IronPDF's managed API.

Issue: Timeout on Server

Symptom: PDF generation hangs on web server

Solution: IronPDF runs headless without interactive sessions:

var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.Timeout = 60000; // Reliable timeout
var pdf = renderer.RenderHtmlAsPdf(html);
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.Timeout = 60000; // Reliable timeout
var pdf = renderer.RenderHtmlAsPdf(html);
$vbLabelText   $csharpLabel

Issue: Background Not Printing

Symptom: CSS backgrounds missing

Solution: Enable background printing:

renderer.RenderingOptions.PrintHtmlBackgrounds = true;
renderer.RenderingOptions.PrintHtmlBackgrounds = true;
$vbLabelText   $csharpLabel

Post-Migration Checklist

After completing the code migration, verify the following:

  • Verify PDF output quality with IronPDF's Chromium engine
  • Test all edge cases with complex HTML/CSS
  • Validate server deployment works without interactive sessions
  • Test Docker/container deployment
  • Remove BCL EasyPDF installer from deployment
  • Remove Office installation from servers (no longer needed)
  • Update CI/CD pipelines with new NuGet package

Future-Proofing Your PDF Infrastructure

With .NET 10 on the horizon and C# 14 introducing new language features, choosing a cross-platform PDF library ensures compatibility with evolving deployment models. IronPDF's support for Linux, Docker, and cloud-native architectures means your migration investment pays dividends as projects extend into 2025 and 2026—without the Windows-only constraints of Easy PDF SDK.

Additional Resources


Migrating from Easy PDF SDK to IronPDF eliminates virtual printer dependencies, COM interop issues, and Windows-only constraints. The transition to Chromium-based rendering delivers superior CSS3 and JavaScript support while enabling deployment to Docker, Kubernetes, and cloud environments that were previously impossible with Easy PDF SDK's legacy architecture.

Curtis Chau
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