跳過到頁腳內容
MIGRATION GUIDES

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

BitMiracle Docotic PDF 是一個備受推崇的 .NET PDF 程式庫,以其 100% 託管程式碼架構和廣泛的程式化 PDF 操作功能而聞名。 然而,其模組化的附加結構(HTML 到 PDF 轉換、佈局功能和其他功能需要單獨的軟體包)增加了專案管理和授權的複雜性。 本綜合指南提供了從 BitMiracle Docotic PDF 到 IronPDF 的逐步遷移路徑——IronPDF 是一個統一的 .NET PDF 庫,內建基於 Chromium 的 HTML 渲染,所有功能都包含在一個 NuGet 套件中。

為什麼要從 BitMiracle Docotic PDF 遷移到 IronPDF?

雖然 BitMiracle Docot PDF 提供了強大的 PDF 操作功能,但多種因素促使開發團隊尋求架構更精簡的替代方案。

封裝架構比較

BitMiracle Docotic PDF 採用模組化外掛程式方式,需要多個軟體包才能達到全部功能:

方面 BitMiracle Docotic PDF IronPDF
HTML 轉 PDF 需要單獨的插件(HtmlToPdf) 內建核心功能
軟體包結構 核心 + 多個附加元件 單一 NuGet 套件
許可模式 按附加組件許可 包含所有功能
API複雜度 每個插件使用單獨的命名空間 統一 API
HTML引擎 Chromium(透過插件) Chromium(內建)
社區規模 更小 更大、更多的資源
文件 技術參考 豐富的教程

功能對等

這兩個庫都支援全面的PDF功能:

特徵 BitMiracle Docotic PDF IronPDF
從零開始建立 PDF
HTML 轉 PDF ✅(需另購) ✅(內建)
PDF檔案的URL ✅(需另購) ✅(內建)
PDF 處理
文字擷取
合併/拆分
數位簽名
加密
表格填寫
PDF/A 合規性

方法上的主要差異

BitMiracle Docot 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() 方法名稱更改
文件載入中 new PdfDocument(path) PdfDocument.FromFile(path) 建構函數 → 靜態方法
儲存 document.Save(path) pdf.SaveAs(path) 方法名稱更改
處理 IDisposable圖案 無需 更簡化的資源管理

逐步遷移過程

步驟 1:更新 NuGet 套件

移除 BitMiracle Docot 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:更新命名空間引用

將 BitMiracle Docot PDF 命名空間替換為 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

步驟 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()
從檔案載入 new PdfDocument(path) PdfDocument.FromFile(path)
從串流中載入 PdfDocument.Load(stream) PdfDocument.FromStream(stream)
從位元組加載 PdfDocument.Load(bytes) PdfDocument.FromBinaryData(bytes)
儲存到文件 document.Save(path) pdf.SaveAs(path)
取得頁數 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)
PDF檔案的URL 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)到新文檔 pdf.CopyPages(start, end)

程式碼遷移範例

HTML 轉 PDF

最常見的操作體現了 IronPDF 提供的顯著簡化功能。

BitMiracle Docot 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 is HTML 轉 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 轉 PDF conversion.</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 is HTML 轉 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 轉 PDF conversion.</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 Docot 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 Docot 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}等佔位符號標記進行動態頁碼編號。 更多選項請參閱頁首和頁尾文件

關鍵遷移說明

Canvas 到 HTML 的典範轉移

BitMiracle Docot PDF 基於 canvas 的繪圖方式必須轉換為使用 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 年,您無需追蹤多個插件版本的兼容性。

其他資源

IronPDF 文件


從 BitMiracle Docotic PDF 遷移到 IronPDF 可以消除管理多個附加軟體包的複雜性,同時提供相同的基於 Chromium 的 HTML 渲染功能。 從基於畫布的繪圖過渡到 HTML/CSS 定位,充分利用了大多數 .NET 開發人員已經具備的 Web 開發技能,從而產生更易於維護的 PDF 生成程式碼。

Curtis Chau
技術撰稿人

Curtis Chau 擁有電腦科學學士學位(卡爾頓大學),專長於前端開發,精通 Node.js、TypeScript、JavaScript 和 React。Curtis 對製作直覺且美觀的使用者介面充滿熱情,他喜歡使用現代化的架構,並製作結構良好且視覺上吸引人的手冊。

除了開發之外,Curtis 對物聯網 (IoT) 也有濃厚的興趣,他喜歡探索整合硬體與軟體的創新方式。在空閒時間,他喜歡玩遊戲和建立 Discord bots,將他對技術的熱愛與創意結合。