跳至页脚内容
  1. IronPDF
  2. IronPDF博客
  3. 迁移指南
  4. 从 migradoc 迁移到 IronPDF
迁移指南

如何用 C# 从 MigraDoc 迁移到 IronPDF

Curtis Chau
Curtis Chau
已发布:

从MigraDoc迁移到IronPDF可将您的 .NET PDF 工作流程从需要手动逐个元素构建的冗长程序化文档模型转变为基于HTML/CSS的现代方法，从而充分利用现有的网络开发技能。 本指南为专业 .NET 开发人员提供了一个全面的、循序渐进的迁移路径，消除了MigraDoc专有文档对象模型的陡峭学习曲线。

为什么要从MigraDoc迁移到 IronPDF．

MigraDoc面临的挑战

MigraDoc 虽然在编程生成 PDF 方面功能强大，但其基本局限性影响了现代开发工作流程：

1.不支持 HTML：MigraDoc不直接支持 HTML。 您必须使用 Document, Section,<代码>段落</代码和<代码>表格</代码对象逐个元素手动构建文档--您不能利用现有的HTML/CSS设计。

2.专有文档模型：MigraDoc需要学习独特的文档模型，其中包含AddSection() 、 AddParagraph() 、 AddTable() 、 AddRow()和AddCell()等概念。 对于具有网络开发背景的开发人员来说，这种陡峭的学习曲线尤其具有挑战性。

3.样式选项有限：虽然MigraDoc提供了强大的文档结构管理功能，但与现代网络工具相比，其样式功能较为有限。 与完整的 CSS3 相比，Format.Font.Size、Format.Font.Bold 和 Format.Alignment 等属性是有限的。

4.冗长的代码：即使是创建简单的布局也需要几十行代码。 一个带标题的基本表格可能需要 15-20 行MigraDoc代码。

5.不支持 JavaScript：MigraDoc无法渲染动态内容或执行 JavaScript，限制了现代图表和交互元素的选择。

6.图表功能较为基础：与 Chart.js 或 D3 等现代JavaScript图表库相比，MigraDoc 的图表功能较为有限。

MigraDoc与IronPDF对比

特征MigraDocIronPDF
内容定义程序性（文件/章节/段落）HTML/CSS
学习曲线Steep（专有 DOM）简单（网络技能）
风格设计有限属性完整的 CSS3
JavaScript无全面执行 Chromium
表格手动定义列/行带 CSS 的 HTML <table>
图表基本MigraDoc图表任何JavaScript图表库
图片手册尺寸/定位标准 HTML <img>
响应式布局不支持Flexbox、网格
许可证开源（MIT）商业翻译

对于计划在 2025 年和 2026 年之前采用 .NET 10 和 C# 14 的团队来说，IronPDF 提供了一个面向未来的基础，使开发人员能够使用熟悉的HTML/CSS技能，而不是学习专有的文档模型。

迁移复杂性评估

按功能估算的工作量

特征迁移复杂性备注
简单文本极低段落 → HTML 元素
表格低表格/行/单元 → HTML <table>
页眉/页脚低章节.页眉 → 渲染选项
风格语言格式属性 → CSS 类
图片低AddImage → HTML <img>
图表语言需要JavaScript库

范式转换

此次MigraDoc迁移的根本转变是从程序化文档构建转向HTML 优先渲染：

MigraDoc：文档 → AddSection() → AddParagraph() → PdfDocumentRenderer → 保存()
IronPDF：   ChromePdfRenderer → RenderHtmlAsPdf(html) → SaveAs()

这种模式的转变大大降低了代码的复杂性，同时通过 CSS 提供了无限的样式功能。

开始之前

前提条件

  1. .NET 环境： .NET Framework 4.6.2+ 或 .NET Core 3.1+ / .NET 5/6/7/8/9+
  2. NuGet 访问权限：能够安装 NuGet 包
  3. IronPDF 许可证：请从ironpdf.com获取您的许可证密钥。

NuGet 软件包变更

# RemoveMigraDocpackages
dotnet remove package PdfSharp-MigraDoc
dotnet remove package PdfSharp-MigraDoc-GDI
dotnet remove package PDFsharp.MigraDoc.Standard

# Install IronPDF
dotnet add package IronPdf
# RemoveMigraDocpackages
dotnet remove package PdfSharp-MigraDoc
dotnet remove package PdfSharp-MigraDoc-GDI
dotnet remove package PDFsharp.MigraDoc.Standard

# Install IronPDF
dotnet add package IronPdf
SHELL

许可配置

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

确定MigraDoc的用途

# Find allMigraDocreferences
grep -r "using MigraDoc\|PdfDocumentRenderer\|AddSection\|AddParagraph" --include="*.cs" .
grep -r "AddTable\|AddRow\|AddColumn\|AddCell\|AddImage" --include="*.cs" .
# Find allMigraDocreferences
grep -r "using MigraDoc\|PdfDocumentRenderer\|AddSection\|AddParagraph" --include="*.cs" .
grep -r "AddTable\|AddRow\|AddColumn\|AddCell\|AddImage" --include="*.cs" .
SHELL

完整的 API 参考

类映射

MigraDoc 类IronPdf 同等产品备注
<代码>文档</代码<代码>ChromePdfRenderer</代码使用呈现器，而不是文档
<代码>部分</代码HTML <body> 或 <div>结构容器
<代码>段落</代码HTML <p>, <h1> 等。文本要素
<代码>格式化文本</代码HTML <span>, <strong> 等。内联格式
<代码>表格</代码HTML <table>使用 CSS 定型
<代码>行</代码HTML <tr>表格行
<代码>列</代码HTML <col> 或 CSS栏目样式
<代码>单元格</代码HTML <td>, <th>表格单元
<代码>PDFDocumentRenderer</代码<代码>ChromePdfRenderer</代码主呈现器

方法映射

</代码
MigraDoc 方法IronPdf 同等产品备注
<代码>document.AddSection()</代码HTML 结构使用 <div> 或 <section>
<代码>section.AddParagraph(text)</代码<代码>

文本

</代码		HTML 段落
<代码>section.AddTable()</代码<table>HTML 表格
<代码>table.AddColumn(width)</代码CSS width 属性<th> 或 <td> 上的样式
<代码>table.AddRow()</代码<tr>HTML 行
<代码>row.Cells[n].AddParagraph()</代码<代码>内容HTML 单元
<代码>renderer.RenderDocument()</代码<代码>RenderHtmlAsPdf(html)</代码渲染为 PDF
<代码>pdfDocument.Save(路径)</代码<代码>pdf.SaveAs(路径)</代码保存文件

占位符映射（页眉/页脚）

MigraDoc 方法IronPdf 占位符备注
<代码>添加页面字段()</代码{page}当前页码
<代码>AddNumPagesField()</代码<代码>{总页数}</代码总页数
<代码>添加日期字段()</代码<代码>{日期}</代码当前日期

代码迁移示例

示例 1：基本 HTML 到 PDF（根本区别）

之前 (MigraDoc)：

// NuGet: Install-Package PdfSharp-MigraDoc-GDI
using MigraDoc.DocumentObjectModel;
using MigraDoc.Rendering;
using System.Diagnostics;

class Program
{
    static void Main()
    {
        //MigraDocdoesn't support HTML directly
        // Must manually create document structure
        Document document = new Document();
        Section section = document.AddSection();

        Paragraph paragraph = section.AddParagraph();
        paragraph.AddFormattedText("Hello World", TextFormat.Bold);
        paragraph.Format.Font.Size = 16;

        PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
        pdfRenderer.Document = document;
        pdfRenderer.RenderDocument();
        pdfRenderer.PdfDocument.Save("output.pdf");
    }
}
// NuGet: Install-Package PdfSharp-MigraDoc-GDI
using MigraDoc.DocumentObjectModel;
using MigraDoc.Rendering;
using System.Diagnostics;

class Program
{
    static void Main()
    {
        //MigraDocdoesn't support HTML directly
        // Must manually create document structure
        Document document = new Document();
        Section section = document.AddSection();

        Paragraph paragraph = section.AddParagraph();
        paragraph.AddFormattedText("Hello World", TextFormat.Bold);
        paragraph.Format.Font.Size = 16;

        PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
        pdfRenderer.Document = document;
        pdfRenderer.RenderDocument();
        pdfRenderer.PdfDocument.Save("output.pdf");
    }
}
$vbLabelText   $csharpLabel

After (IronPDF)：

// NuGet: Install-Package IronPdf
using IronPdf;

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;

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

这个例子说明了MigraDoc和IronPDF的根本区别。MigraDoc要求创建 Document, 添加 Section, 添加 Paragraph, 使用 AddFormattedText() 和 TextFormat.粗体，设置 Format.Font.Size, 创建一个 PdfDocumentRenderer, 分配文档，调用 RenderDocument(), 最后保存。 这是 10 多行包含多个对象的代码。

IronPDF 只需 3 行即可实现相同的效果：创建呈现器、呈现 HTML 并保存。 HTML <h1> 标记自然提供了粗体大标题样式。 有关其他渲染选项，请参阅 HTML to PDF 文档。

示例 2：创建表格

之前 (MigraDoc)：

// NuGet: Install-Package PdfSharp-MigraDoc-GDI
using MigraDoc.DocumentObjectModel;
using MigraDoc.DocumentObjectModel.Tables;
using MigraDoc.Rendering;

class Program
{
    static void Main()
    {
        Document document = new Document();
        Section section = document.AddSection();

        Table table = section.AddTable();
        table.Borders.Width = 0.75;

        Column column1 = table.AddColumn("3cm");
        Column column2 = table.AddColumn("3cm");

        Row row1 = table.AddRow();
        row1.Cells[0].AddParagraph("Name");
        row1.Cells[1].AddParagraph("Age");

        Row row2 = table.AddRow();
        row2.Cells[0].AddParagraph("John");
        row2.Cells[1].AddParagraph("30");

        PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
        pdfRenderer.Document = document;
        pdfRenderer.RenderDocument();
        pdfRenderer.PdfDocument.Save("table.pdf");
    }
}
// NuGet: Install-Package PdfSharp-MigraDoc-GDI
using MigraDoc.DocumentObjectModel;
using MigraDoc.DocumentObjectModel.Tables;
using MigraDoc.Rendering;

class Program
{
    static void Main()
    {
        Document document = new Document();
        Section section = document.AddSection();

        Table table = section.AddTable();
        table.Borders.Width = 0.75;

        Column column1 = table.AddColumn("3cm");
        Column column2 = table.AddColumn("3cm");

        Row row1 = table.AddRow();
        row1.Cells[0].AddParagraph("Name");
        row1.Cells[1].AddParagraph("Age");

        Row row2 = table.AddRow();
        row2.Cells[0].AddParagraph("John");
        row2.Cells[1].AddParagraph("30");

        PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
        pdfRenderer.Document = document;
        pdfRenderer.RenderDocument();
        pdfRenderer.PdfDocument.Save("table.pdf");
    }
}
$vbLabelText   $csharpLabel

After (IronPDF)：

// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        string htmlTable = @"
            <table border='1'>
                <tr><th>Name</th><th>Age</th></tr>
                <tr><td>John</td><td>30</td></tr>
            </table>";

        var pdf = renderer.RenderHtmlAsPdf(htmlTable);
        pdf.SaveAs("table.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        string htmlTable = @"
            <table border='1'>
                <tr><th>Name</th><th>Age</th></tr>
                <tr><td>John</td><td>30</td></tr>
            </table>";

        var pdf = renderer.RenderHtmlAsPdf(htmlTable);
        pdf.SaveAs("table.pdf");
    }
}
$vbLabelText   $csharpLabel

创建MigraDoc表格需要了解 Table, Column,<代码>行</代码和<代码>单元格</代码层次结构。 您必须使用 AddColumn() 明确添加列，使用 AddRow() 创建行，使用 Cells[n] 通过索引访问单元格，以及使用 AddParagraph() 添加内容。 边框通过 table.Borders.Width 设置。

IronPdf 使用任何网络开发人员都知道的标准 HTML 表格语法。 border='1' 属性提供边框，<th> 元素创建标题单元格，<td> 元素创建数据单元格。 可以添加 CSS 以实现斑马线、悬停效果或响应式布局等高级样式。 了解有关在 PDF 中创建表格的更多信息。

示例 3：带页码的页眉和页脚

之前 (MigraDoc)：

// NuGet: Install-Package PdfSharp-MigraDoc-GDI
using MigraDoc.DocumentObjectModel;
using MigraDoc.Rendering;

class Program
{
    static void Main()
    {
        Document document = new Document();
        Section section = document.AddSection();

        // Add header
        Paragraph headerPara = section.Headers.Primary.AddParagraph();
        headerPara.AddText("Document Header");
        headerPara.Format.Font.Size = 12;
        headerPara.Format.Alignment = ParagraphAlignment.Center;

        // Add footer
        Paragraph footerPara = section.Footers.Primary.AddParagraph();
        footerPara.AddText("Page ");
        footerPara.AddPageField();
        footerPara.Format.Alignment = ParagraphAlignment.Center;

        // Add content
        section.AddParagraph("Main content of the document");

        PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
        pdfRenderer.Document = document;
        pdfRenderer.RenderDocument();
        pdfRenderer.PdfDocument.Save("header-footer.pdf");
    }
}
// NuGet: Install-Package PdfSharp-MigraDoc-GDI
using MigraDoc.DocumentObjectModel;
using MigraDoc.Rendering;

class Program
{
    static void Main()
    {
        Document document = new Document();
        Section section = document.AddSection();

        // Add header
        Paragraph headerPara = section.Headers.Primary.AddParagraph();
        headerPara.AddText("Document Header");
        headerPara.Format.Font.Size = 12;
        headerPara.Format.Alignment = ParagraphAlignment.Center;

        // Add footer
        Paragraph footerPara = section.Footers.Primary.AddParagraph();
        footerPara.AddText("Page ");
        footerPara.AddPageField();
        footerPara.Format.Alignment = ParagraphAlignment.Center;

        // Add content
        section.AddParagraph("Main content of the document");

        PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
        pdfRenderer.Document = document;
        pdfRenderer.RenderDocument();
        pdfRenderer.PdfDocument.Save("header-footer.pdf");
    }
}
$vbLabelText   $csharpLabel

After (IronPDF)：

// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Main content of the document</h1>");

        pdf.AddTextHeader("Document Header");
        pdf.AddTextFooter("Page {page}");

        pdf.SaveAs("header-footer.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main()
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Main content of the document</h1>");

        pdf.AddTextHeader("Document Header");
        pdf.AddTextFooter("Page {page}");

        pdf.SaveAs("header-footer.pdf");
    }
}
$vbLabelText   $csharpLabel

MigraDoc 页眉和页脚需要访问 section.Headers.Primary 和 section.Footers.Primary ，在其中创建段落，使用 AddText() 添加文本，并使用<代码>添加页面字段()</代码等特殊方法处理动态内容。 对齐要求设置 Format.Alignment.

IronPDF 在 PdfDocument 对象上提供了简单的 AddTextHeader() 和 AddTextFooter() 方法。{page}占位符会自动插入当前页码。 对于更复杂的标题，您可以使用完全支持HTML/CSS的 HtmlHeaderFooter 。 有关高级选项，请参见页眉和页脚文档。

关键迁移说明

页码占位符语法

页眉和页脚最重要的变化是占位符语法：

//MigraDocfield methods:
footerPara.AddPageField();       // Current page
footerPara.AddNumPagesField();   // Total pages

//IronPDFplaceholders:
"Page {page} of {total-pages}"
//MigraDocfield methods:
footerPara.AddPageField();       // Current page
footerPara.AddNumPagesField();   // Total pages

//IronPDFplaceholders:
"Page {page} of {total-pages}"
$vbLabelText   $csharpLabel

将属性格式化为 CSS.

MigraDoc 的 Format 属性映射到 CSS：

// MigraDoc:
paragraph.Format.Font.Size = 16;
paragraph.Format.Font.Bold = true;
paragraph.Format.Alignment = ParagraphAlignment.Center;

//IronPDF(CSS):
<p style="font-size: 16pt; font-weight: bold; text-align: center;">
// MigraDoc:
paragraph.Format.Font.Size = 16;
paragraph.Format.Font.Bold = true;
paragraph.Format.Alignment = ParagraphAlignment.Center;

//IronPDF(CSS):
<p style="font-size: 16pt; font-weight: bold; text-align: center;">
$vbLabelText   $csharpLabel

单位转换

MigraDoc 使用多种单位； IronPdf 页边距使用毫米：

  • "1 厘米" = 10 毫米
  • "1 英寸" = 25.4 毫米
  • "72pt" = 25.4毫米
// MigraDoc:
table.AddColumn("3cm");

//IronPDF(CSS):
<th style="width: 3cm;">
// MigraDoc:
table.AddColumn("3cm");

//IronPDF(CSS):
<th style="width: 3cm;">
$vbLabelText   $csharpLabel

渲染模式更改

整个渲染模式会发生变化：

//MigraDocpattern (DELETE):
PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
pdfRenderer.Document = document;
pdfRenderer.RenderDocument();
pdfRenderer.PdfDocument.Save("output.pdf");

//IronPDFpattern:
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");
//MigraDocpattern (DELETE):
PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
pdfRenderer.Document = document;
pdfRenderer.RenderDocument();
pdfRenderer.PdfDocument.Save("output.pdf");

//IronPDFpattern:
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");
$vbLabelText   $csharpLabel

故障排除

问题 1：未找到文档/章节

问题：IronPDF中不存在Document和Section类。

解决方案：替换为 HTML 结构：

// MigraDoc
Document document = new Document();
Section section = document.AddSection();

// IronPDF
string html = "<html><body>...</body></html>";
var pdf = renderer.RenderHtmlAsPdf(html);
// MigraDoc
Document document = new Document();
Section section = document.AddSection();

// IronPDF
string html = "<html><body>...</body></html>";
var pdf = renderer.RenderHtmlAsPdf(html);
$vbLabelText   $csharpLabel

问题 2：未找到添加段落

问题： AddParagraph()方法不存在。

解决方案：使用 HTML 元素：

// MigraDoc
section.AddParagraph("Hello World");

// IronPDF
"<p>Hello World</p>"
// MigraDoc
section.AddParagraph("Hello World");

// IronPDF
"<p>Hello World</p>"
$vbLabelText   $csharpLabel

问题 3：未找到 PdfDocumentRenderer

问题： PdfDocumentRenderer类不存在。

解决方案：使用ChromePdfRenderer ：

// MigraDoc
PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();

// IronPDF
var renderer = new ChromePdfRenderer();
// MigraDoc
PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();

// IronPDF
var renderer = new ChromePdfRenderer();
$vbLabelText   $csharpLabel

问题 4：AddPageField 无法工作

问题： AddPageField()方法不存在。

解决方法：使用IronPDF占位符语法：

// MigraDoc
footerPara.AddPageField();

// IronPDF
pdf.AddTextFooter("Page {page}");
// MigraDoc
footerPara.AddPageField();

// IronPDF
pdf.AddTextFooter("Page {page}");
$vbLabelText   $csharpLabel

迁移清单

迁移前

  • using语句识别所有 MigraDoc
  • 文档表格结构（列、行、样式）
  • 注意页眉/页脚内容和页面字段的使用
  • 列出使用document.Styles定义的自定义样式
  • 获取IronPDF许可证密钥

软件包变更

  • 移除PdfSharp-MigraDoc软件包
  • 删除PdfSharp-MigraDoc-GDI软件包 安装IronPdf NuGet 包： dotnet add package IronPdf
  • 更新命名空间导入

代码更改

  • 在启动时添加许可证密钥配置
  • 将Document / Section替换为 HTML 结构 将AddParagraph()转换为 HTML<p>元素 将Table /<代码>行</代码/ Cell转换为 HTML<table>结构
  • 将AddPageField()替换为{page}占位符
  • 将AddNumPagesField()替换为{total-pages}占位符 将Format属性转换为 CSS 样式
  • 将PdfDocumentRenderer替换为ChromePdfRenderer

测试

  • 对比新旧PDF文件的视觉效果
  • 验证分页符是否正常工作 检查页眉/页脚渲染和页码
  • 检查表格格式和边框
  • 使用复杂的多页文档进行测试

后迁移

  • 删除与MigraDoc相关的文档
  • 更新团队培训材料
  • 记录新的 HTML 模板位置
Curtis Chau
Curtis Chau
  立即与工程团队聊天
技术作家

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

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

相关文章

30天试用 → 完整产品。无限制。无卡。 免费试用