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 loadingCOM object that has been separated from its underlying RCW cannot be usedTimeout expired waiting for print job to completeThe printer operation failed because the service is not runningError: 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
| Feature | Easy PDF SDK | IronPDF |
|---|---|---|
| Platform | Windows-only | Windows, Linux, macOS, Docker |
| Office Dependency | Required | None |
| Installation | Complex MSI + printer driver + COM | Simple NuGet package |
| Server Support | Requires interactive session | Runs headless |
| HTML Rendering | Basic (Office-based) | Full Chromium (CSS3, JS) |
| .NET Support | Limited .NET Core | Full .NET 5/6/7/8/9 |
| Async Pattern | Callback-based | Native async/await |
| Container Support | Cannot run | Full 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" .Breaking Changes to Anticipate
| Easy PDF SDK Pattern | Change Required |
|---|---|
new Printer() | Use ChromePdfRenderer |
PrintOfficeDocToPDF() | Office conversion handled differently |
RenderHTMLToPDF() | RenderHtmlAsPdf() |
| COM interop references | Remove entirely |
| Printer driver config | Not needed |
BeginPrintToFile() callbacks | Native async/await |
| Interactive session requirements | Runs headless |
| 1-based page indexing | 0-based indexing |
| Timeout in seconds | Timeout 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:
- Uninstall BCL EasyPDF SDK from Programs and Features
- Remove DLL references from your project
- Remove COM interop references
- Clean up GAC entries if present
Step 2: Install IronPDF
# Install IronPDF
dotnet add package IronPdf# Install IronPDF
dotnet add package IronPdfOr via Package Manager Console:
Install-Package IronPdfStep 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;Complete API Migration Reference
Core Class Mapping
| Easy PDF SDK Class | IronPDF Equivalent | Notes |
|---|---|---|
Printer | ChromePdfRenderer | Main conversion class |
PDFDocument | PdfDocument | Document manipulation |
HTMLConverter | ChromePdfRenderer | HTML conversion |
PrinterConfiguration | ChromePdfRenderOptions | Rendering options |
PageOrientation | PdfPaperOrientation | Page orientation |
PageSize | PdfPaperSize | Paper size |
SecurityHandler | PdfDocument.SecuritySettings | Security options |
PDF Creation Methods
| Easy PDF SDK Method | IronPDF Method | Notes |
|---|---|---|
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 Method | IronPDF Method | Notes |
|---|---|---|
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.PageCount | Page count |
doc.Save(path) | pdf.SaveAs(path) | Save PDF |
doc.Close() | pdf.Dispose() or using | Cleanup |
doc.ExtractText() | pdf.ExtractAllText() | Text extraction |
Configuration Options
| Easy PDF SDK Option | IronPDF Option | Notes |
|---|---|---|
config.TimeOut | RenderingOptions.Timeout | Timeout (ms) |
config.PageOrientation = Landscape | RenderingOptions.PaperOrientation = Landscape | Orientation |
config.PageSize = A4 | RenderingOptions.PaperSize = PdfPaperSize.A4 | Paper size |
config.MarginTop/Bottom/Left/Right | RenderingOptions.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();
}
}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");
}
}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();
}
}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");
}
}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();
}
}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");
}
}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");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");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();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");
}
}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);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;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");
}
}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);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);Issue: Background Not Printing
Symptom: CSS backgrounds missing
Solution: Enable background printing:
renderer.RenderingOptions.PrintHtmlBackgrounds = true;renderer.RenderingOptions.PrintHtmlBackgrounds = true;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.






