如何用 C# 从 MigraDoc 迁移到 IronPDF
从MigraDoc迁移到 IronPDF:完整的 C# 迁移指南
从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对比
| 特征 | MigraDoc | IronPDF |
|---|---|---|
| 内容定义 | 程序性(文件/章节/段落) | 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许可配置
// 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";IRON VB CONVERTER ERROR developers@ironsoftware.com确定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" .完整的 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");
}
}IRON VB CONVERTER ERROR developers@ironsoftware.comAfter (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");
}
}IRON VB CONVERTER ERROR developers@ironsoftware.com这个例子说明了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");
}
}IRON VB CONVERTER ERROR developers@ironsoftware.comAfter (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");
}
}IRON VB CONVERTER ERROR developers@ironsoftware.com创建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");
}
}IRON VB CONVERTER ERROR developers@ironsoftware.comAfter (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");
}
}IRON VB CONVERTER ERROR developers@ironsoftware.comMigraDoc 页眉和页脚需要访问 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}"IRON VB CONVERTER ERROR developers@ironsoftware.com将属性格式化为 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;">IRON VB CONVERTER ERROR developers@ironsoftware.com单位转换
MigraDoc 使用多种单位; IronPdf 页边距使用毫米:
- "1 厘米" = 10 毫米
- "1 英寸" = 25.4 毫米
- "72pt" = 25.4mm
// MigraDoc:
table.AddColumn("3cm");
//IronPDF(CSS):
<th style="width: 3cm;">// MigraDoc:
table.AddColumn("3cm");
//IronPDF(CSS):
<th style="width: 3cm;">IRON VB CONVERTER ERROR developers@ironsoftware.com渲染模式更改
整个渲染模式会发生变化:
//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");IRON VB CONVERTER ERROR developers@ironsoftware.com故障排除
问题 1:未找到文档/章节
问题:IronPDF 中不存在<代码>文档</代码和<代码>部分</代码类。
解决方案:替换为 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);IRON VB CONVERTER ERROR developers@ironsoftware.com问题 2:未找到添加段落
问题:AddParagraph() 方法不存在。
解决方案:使用 HTML 元素:
// MigraDoc
section.AddParagraph("Hello World");
// IronPDF
"<p>Hello World</p>"// MigraDoc
section.AddParagraph("Hello World");
// IronPDF
"<p>Hello World</p>"IRON VB CONVERTER ERROR developers@ironsoftware.com问题 3:未找到 PdfDocumentRenderer
问题:PdfDocumentRenderer 类不存在。
解决方案:使用 ChromePdfRenderer:
// MigraDoc
PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
// IronPDF
var renderer = new ChromePdfRenderer();// MigraDoc
PdfDocumentRenderer pdfRenderer = new PdfDocumentRenderer();
// IronPDF
var renderer = new ChromePdfRenderer();IRON VB CONVERTER ERROR developers@ironsoftware.com问题 4:AddPageField 无法工作
问题:AddPageField() 方法不存在。
解决方案:使用 IronPdf 占位符语法:
// MigraDoc
footerPara.AddPageField();
// IronPDF
pdf.AddTextFooter("Page {page}");// MigraDoc
footerPara.AddPageField();
// IronPDF
pdf.AddTextFooter("Page {page}");IRON VB CONVERTER ERROR developers@ironsoftware.com迁移清单
迁移前
- [ ] 识别所有MigraDoc
using语句 - [ ] 文档表格结构(列、行、样式)
- [ ] 注意页眉/页脚内容和页面字段用法
- [ ] 列出使用
document.Styles定义的自定义样式 - [ ] 获取 IronPdf 许可证密钥
软件包变更
- [ ] 删除
PdfSharp-MigraDoc包 - [ ] 删除
PdfSharp-MigraDoc-GDI包 - [ ] 安装
IronPDFNuGet 软件包:<代码>dotnet 添加软件包 IronPdf - [更新命名空间导入
代码更改
- [ ] 在启动时添加许可证密钥配置
- [ ] 将
Document/Section替换为 HTML 结构 - [ ] 将
AddParagraph()转换为 HTML<p>元素 - [ ] 将
Table/Row/Cell转换为HTML<table>结构 - [ ] 将<代码>添加页面字段()</代码替换为
{page}占位符 - [ ] 将<代码>AddNumPagesField()</代码替换为<代码>{总页数}</代码占位符
- [ ] 将
Format属性转换为 CSS 样式 - [ ] 将<代码>PDFDocumentRenderer</代码替换为
ChromePdfRenderer
测试
- [ ] 比较新旧 PDF 之间的视觉输出
- [ ] 验证分页符是否正常工作
- [ ] 检查页眉/页脚渲染和页码
- [ ] 验证表格格式和边框
- [ ] 测试复杂的多页文档
后迁移
- [ ] 删除MigraDoc相关文档
- [ ] 更新团队培训材料
- [ ] 文档新 HTML 模板位置
结论
从MigraDoc迁移到IronPDF可以消除MigraDoc专有文档对象模型的陡峭学习曲线,同时提供完整的 CSS3 风格功能。 从程序化文档构建到 HTML 优先渲染的范式转变极大地降低了代码的复杂性,对于复杂的布局而言,复杂性通常会降低 80% 或更多。
本次迁移的主要变化有 1.内容模型:Document/Section/Paragraph → HTML 元素 2.排版:<代码>格式</代码>属性 → CSS 3.表格:AddTable()/AddRow()/AddColumn() → HTML <table>. 4.占位符:<代码>AddPageField()</代码> → <代码>{page}</代码 5.渲染器:<代码>PDFDocumentRenderer</代码> → <代码>ChromePdfRenderer</代码






