跳至页脚内容
迁移指南

如何用 C# 从 BitMiracle Docotic PDF 迁移到 IronPDF

BitMiracle Docotic PDF 是一个广受好评的 .NET PDF 库,以其 100% 的托管代码架构和广泛的 PDF 编程操作能力而闻名。 然而,其模块化附加结构--需要单独的软件包来实现 HTML 到 PDF 的转换、布局功能和其他功能--增加了项目管理和许可的复杂性。 本综合指南提供了从BitMiracle Docotic PDF逐步迁移到IronPDF的路径--IronPDF 是一个统一的 .NET PDF 库,内置基于 Chromium 的 HTML 渲染功能,所有功能都包含在一个 NuGet 包中。

为什么要从BitMiracle Docotic PDF迁移到 IronPDF?

虽然BitMiracle Docotic PDF提供了强大的 PDF 操作功能,但有几个因素促使开发团队寻求具有更精简架构的替代产品。

软件包架构比较

BitMiracle Docotic PDF 采用模块化附加方法,需要多个软件包才能实现全部功能:

方面 BitMiracle Docotic PDF IronPDF
HTML-to-PDF 需要单独的插件 (HtmlToPdf) 内置核心功能
软件包结构 核心 + 多个附加组件 单个 NuGet 软件包
许可模式 按次许可 所有功能包括
API 复杂性 每个附加组件都有独立的命名空间 统一 API
HTML 引擎 Chromium (通过附加组件) Chromium (内置)
社区规模 较小 规模更大、资源更多
文档 技术参考 广泛的教程

功能对等

这两个库都支持全面的 PDF 功能:

特征 BitMiracle Docotic PDF IronPDF
从零开始创建 PDF
HTML 至 PDF ✅(需要插件) ✅(内置)
URL 至 PDF ✅(需要插件) ✅(内置)
PDF 操作
文本提取
合并/拆分
数字签名
加密
表格填写
符合 PDF/A 标准

方法上的主要差异

BitMiracle Docotic PDF 使用基于画布的绘图和坐标定位(canvas.DrawString(x, y, text)),而IronPDF则利用 HTML/CSS 进行布局和定位。 这代表了一种模式的转变,简化了熟悉网络技术的开发人员的内容创建。

迁移前准备

前提条件

确保您的环境符合这些要求:

  • .NET Framework 4.6.2+ 或 .NET Core 3.1 / .NET 5-9
  • Visual Studio 2019+ 或带有 C# 扩展的 VS Code
  • 访问 NuGet 包管理器 -IronPDF许可证密钥(可在ironpdf.com免费试用)

审计BitMiracle Docotic PDF的使用情况

在解决方案目录中运行这些命令,以识别所有 Docotic.Pdf 引用:

# 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

值得期待的重大变化

变更 BitMiracle Docotic PDF IronPDF 影响
HTML 渲染 需要 HtmlToPdf 附加组件 内置 删除附加软件包
页面索引 基于 0 (Pages[0]) 基于 0 (Pages[0]) 无需改动
坐标系 左下方原点 HTML/CSS 流程 使用 CSS 进行定位
画布绘图 PdfCanvas.DrawText() HTML 标记 范式转换
文本提取 page.GetText() pdf.ExtractAllText() 方法名称更改
文档加载 新建 PdfDocument(path) PdfDocument.FromFile(路径) 构造函数 → 静态方法
节约 document.Save(路径) pdf.SaveAs(路径) 方法名称更改
处置 IDisposable 模式 不要求 简化资源管理

逐步迁移过程

步骤 1:更新 NuGet 软件包

删除BitMiracle Docotic PDF软件包并安装 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

步骤 2:更新命名空间引用

用IronPDF替换BitMiracle Docotic PDF命名空间:

// 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

步骤 3:配置许可证

// 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

完整的 API 迁移参考

文档操作

任务 BitMiracle Docotic PDF IronPDF
创建空文档 new PdfDocument() new PdfDocument()
从文件加载 新建 PdfDocument(path) PdfDocument.FromFile(路径)
从流加载 PdfDocument.Load(stream) PdfDocument.FromStream(流)
从字节加载 PdfDocument.Load(bytes) PdfDocument.FromBinaryData(字节)
保存到文件 document.Save(路径) pdf.SaveAs(路径)
获取页数 document.PageCount pdf.PageCount
关闭/处置 document.Dispose() 不要求

HTML 到 PDF 转换

任务 BitMiracle Docotic PDF(HtmlToPdf 附加组件) IronPDF
HTML 字符串到 PDF HtmlConverter.Create(html).ToPdf() renderer.RenderHtmlAsPdf(html)
HTML 文件到 PDF HtmlConverter.Create(new Uri(filePath)).ToPdf() renderer.RenderHtmlFileAsPdf(path)
URL 至 PDF HtmlConverter.Create(new Uri(url)).ToPdf() renderer.RenderUrlAsPdf(url)
设置页面大小 options.PageSize = PageSize.A4 renderer.RenderingOptions.PaperSize = PdfPaperSize.A4
设置页边距 options.PageMargins = new Margins(20) renderer.RenderingOptions.MarginTop = 20

合并和拆分操作

任务 BitMiracle Docotic PDF IronPDF
合并文件 doc1.Append(doc2) PdfDocument.Merge(pdf1, pdf2)
拆分文件 document.CopyPage(index)</code>到新文档|<code>pdf.CopyPages(start, end)

代码迁移示例

HTML 到 PDF 转换

最常见的操作展示了 IronPdf 带来的显著简化。

BitMiracle Docotic PDF 实现:

// 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 isHTML 至 PDFconversion.</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 isHTML 至 PDFconversion.</p></body></html>";

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

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

IronPDF 实现:

// 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 isHTML 至 PDFconversion.</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 isHTML 至 PDFconversion.</p></body></html>";

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

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

IronPDF 消除了 using 语句的要求,并提供了一个专用的 ChromePdfRenderer 类,明确指出其基于 Chromium 的渲染能力。 有关更多 HTML 转换选项,请参阅 HTML 转 PDF 文档

合并多个 PDF 文件

BitMiracle Docotic PDF 实现:

// 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 实现:

// 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 的静态 Merge 方法可直接接受多个文档,与迭代 Append 模式相比,提供了一个更简洁的 API。 更多选项请参阅PDF 合并文档

文本提取

BitMiracle Docotic PDF 实现:

// 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 实现:

// 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 将文本提取从多行循环减少到单个方法调用。 有关更多提取选项,请参阅文本提取文档

密码保护和加密

IronPDF 实现:

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

有关全面的安全选项,请参阅加密文档

页眉和页脚

IronPDF 实现:

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 支持占位符标记,如用于动态页码的 {page}{total-pages} 。 有关更多选项,请参阅页眉和页脚文档

关键迁移说明

画布到 HTML 的范式转变

BitMiracle Docotic PDF 基于画布的绘图方法必须通过 CSS 定位转换为 HTML:

BitMiracle Docotic PDF 模式:

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

IronPdf模式:

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

同页索引

这两个库都使用基于 0 的索引(Pages[0] 是第一页)--无需更改页面访问代码。

无需处理

IronPdf 不需要 using 语句进行内存管理,从而简化了代码结构:

//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

同步支持

BitMiracle Docotic PDF 的 HtmlToPdf 附加组件要求处处采用异步模式。IronPDF支持同步和异步方法:

// 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 集成

IronPdf模式:

[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

迁移后核对表

完成代码迁移后,请验证以下内容:

运行所有单元测试以验证 PDF 生成功能是否正常。

  • 比较 PDF 输出质量(IronPDF 的 Chromium 引擎渲染效果可能略有不同——通常更好)
  • 验证文本提取准确性
  • 测试表单填写功能
  • 如适用,验证数字签名
  • 性能测试批量操作
  • 在所有目标环境中进行测试
  • 更新 CI/CD 流水线
  • 删除 Docotic.Pdf 许可证文件

未来保护您的 PDF 基础架构

随着 .NET 10 即将推出,C# 14 也将引入新的语言特性,选择具有统一架构的 PDF 库可以简化依赖性管理,并确保功能的一致性。 IronPdf 的单包方法意味着当项目延伸到 2025 年和 2026 年时,您无需跟踪多个附加版本的兼容性。

其他资源


从BitMiracle Docotic PDF迁移到IronPDF可以消除管理多个附加软件包的复杂性,同时提供相同的基于 Chromium 的 HTML 渲染功能。 从基于画布的绘图过渡到 HTML/CSS 定位,利用了大多数 .NET 开发人员已经掌握的网络开发技能,从而使 PDF 生成代码更具可维护性。

Curtis Chau
技术作家

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

除了开发之外,Curtis 对物联网 (IoT) 有浓厚的兴趣,探索将硬件和软件集成的新方法。在空闲时间,他喜欢玩游戏和构建 Discord 机器人,将他对技术的热爱与创造力相结合。