从 Haukcode.DinkToPdf 迁移到 IronPDF
Haukcode.DinkToPdf 是曾经流行的 DinkToPdf 库的延续,它使用 wkhtmltopdf 二进制文件将 HTML 转换为 PDF,供 .NET 应用程序使用。 尽管 Haukcode.DinkToPdf 在原项目停滞后继续支持 .NET Core,但它由于其上游依赖项而存在严重的安全问题。 wkhtmltopdf 项目已于 2023 年 1 月存档,因此这些问题将永远不会得到解决。
本指南提供了从 Haukcode.DinkToPdf 到IronPDF的完整迁移路径,包括分步说明、代码比较和实用示例,旨在帮助专业的 .NET 开发人员消除 PDF 生成工作流程中的安全风险。
关键安全警告:CVE-2022-35583。
Haukcode.DinkToPdf 从 wkhtmltopdf 继承了一个无法解决的重大安全漏洞:
CVE-2022-35583 - 严重 SSRF 漏洞 (CVSS 9.8)
wkhtmltopdf 库(以及包括 Haukcode.DinkToPdf 在内的所有封装程序)存在服务器端请求伪造 (SSRF) 漏洞:
攻击途径:恶意 HTML 内容可导致服务器获取内部资源。
- AWS 元数据攻击:可访问
http://169.254.169.254以窃取 AWS 凭证 -内部网络访问:可以扫描和访问内部服务 -本地文件包含:可通过file://协议读取本地文件 影响:可能完全接管基础设施
此漏洞没有修复程序,因为 wkhtmltopdf 已于 2023 年废弃并归档。最后一次发布是 2020 年的 0.12.6 版。
IronPDFvs Haukcode.DinkToPdf:功能比较
了解架构差异有助于技术决策者评估迁移投资:
| 方面 | Haukcode.DinkToPdf | IronPDF |
|---|---|---|
| 底层引擎 | wkhtmltopdf (Qt WebKit ~2015) | Chromium (定期更新) |
| 安全状态 | CVE-2022-35583(CRITICAL,不可修复) | 积极修补 |
| 项目状态 | 废弃项目的分叉 | 积极开发 |
| HTML5/CSS3 | 有限的 | 支持 |
| JavaScript语言 | 有限、不安全 | 完整的 V8 引擎 |
| 本地二进制文件 | 要求(特定平台) | 自成一体 |
| 线程安全 | 需要单例模式 | 线程安全设计 |
| 支持 | 仅限社区 | 专业支持 |
| 更新 | 无预期 | 定期发布 |
| 许可 | 麻省理工学院(免费) | 免费试用版商业版 |
快速入门:Haukcode.DinkToPdf 到IronPDF的迁移。
迁移工作可以通过以下基本步骤立即开始。
步骤 1:删除 DinkToPdf 和本地二进制文件
删除 Haukcode.DinkToPdf NuGet 软件包:
# Remove NuGet packages
dotnet remove package DinkToPdf
dotnet remove package Haukcode.DinkToPdf
dotnet remove package Haukcode.WkHtmlToPdf-DotNet
# Remove NuGet packages
dotnet remove package DinkToPdf
dotnet remove package Haukcode.DinkToPdf
dotnet remove package Haukcode.WkHtmlToPdf-DotNet
从您的项目中删除本地二进制文件:
libwkhtmltox.dll(Windows)libwkhtmltox.so(Linux)libwkhtmltox.dylib(macOS)
步骤2:安装IronPDF
# Install IronPDF
dotnet add package IronPdf
# Install IronPDF
dotnet add package IronPdf
步骤 3:更新命名空间
用IronPDF替换 DinkToPdf 命名空间:
// Before (Haukcode.DinkToPdf)
using DinkToPdf;
using DinkToPdf.Contracts;
// After (IronPDF)
using IronPdf;
using IronPdf.Rendering; // For RenderingOptions
// Before (Haukcode.DinkToPdf)
using DinkToPdf;
using DinkToPdf.Contracts;
// After (IronPDF)
using IronPdf;
using IronPdf.Rendering; // For RenderingOptions
Imports IronPdf
Imports IronPdf.Rendering
步骤 4:初始化许可证
在应用程序启动时添加许可证初始化:
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"
代码迁移示例
基本 HTML 到 PDF 的转换
最基本的操作揭示了这些 .NET PDF 库之间的复杂性差异。
Haukcode.DinkToPdf 方法:
// NuGet: Install-Package DinkToPdf
using DinkToPdf;
using DinkToPdf.Contracts;
using System.IO;
class Program
{
static void Main()
{
var converter = new SynchronizedConverter(new PdfTools());
var doc = new HtmlToPdfDocument()
{
GlobalSettings = {
ColorMode = ColorMode.Color,
Orientation = Orientation.Portrait,
PaperSize = PaperKind.A4,
},
Objects = {
new ObjectSettings() {
HtmlContent = "<html><body><h1>Hello World</h1></body></html>",
}
}
};
byte[] pdf = converter.Convert(doc);
File.WriteAllBytes("output.pdf", pdf);
}
}
// NuGet: Install-Package DinkToPdf
using DinkToPdf;
using DinkToPdf.Contracts;
using System.IO;
class Program
{
static void Main()
{
var converter = new SynchronizedConverter(new PdfTools());
var doc = new HtmlToPdfDocument()
{
GlobalSettings = {
ColorMode = ColorMode.Color,
Orientation = Orientation.Portrait,
PaperSize = PaperKind.A4,
},
Objects = {
new ObjectSettings() {
HtmlContent = "<html><body><h1>Hello World</h1></body></html>",
}
}
};
byte[] pdf = converter.Convert(doc);
File.WriteAllBytes("output.pdf", pdf);
}
}
Imports DinkToPdf
Imports DinkToPdf.Contracts
Imports System.IO
Module Program
Sub Main()
Dim converter = New SynchronizedConverter(New PdfTools())
Dim doc = New HtmlToPdfDocument() With {
.GlobalSettings = New GlobalSettings() With {
.ColorMode = ColorMode.Color,
.Orientation = Orientation.Portrait,
.PaperSize = PaperKind.A4
},
.Objects = New List(Of ObjectSettings) From {
New ObjectSettings() With {
.HtmlContent = "<html><body><h1>Hello World</h1></body></html>"
}
}
}
Dim pdf As Byte() = converter.Convert(doc)
File.WriteAllBytes("output.pdf", pdf)
End Sub
End Module
IronPDF 方法:
// NuGet: Install-Package IronPdf
using IronPdf;
using System.IO;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<html><body><h1>Hello World</h1></body></html>");
pdf.SaveAs("output.pdf");
}
}
// NuGet: Install-Package IronPdf
using IronPdf;
using System.IO;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf("<html><body><h1>Hello World</h1></body></html>");
pdf.SaveAs("output.pdf");
}
}
Imports IronPdf
Imports System.IO
Class Program
Shared Sub Main()
Dim renderer = New ChromePdfRenderer()
Dim pdf = renderer.RenderHtmlAsPdf("<html><body><h1>Hello World</h1></body></html>")
pdf.SaveAs("output.pdf")
End Sub
End Class
Haukcode.DinkToPdf 需要创建一个 SynchronizedConverter 和 PdfTools,构造一个 HtmlToPdfDocument 和嵌套的 GlobalSettings 和 Objects,添加一个 ObjectSettings 和 HtmlContent,调用 converter.Convert() 获取原始字节,并使用 File.WriteAllBytes() 手动写入文件。
IronPDF 将此简化为三行:创建一个 ChromePdfRenderer,调用 RenderHtmlAsPdf(),并使用内置的 SaveAs() 方法。
有关 HTML 转 PDF 的高级应用场景,请参阅 HTML 转 PDF 指南。
将 URL 转换为 PDF
URL 到 PDF 的转换也显示出类似的模式差异。
Haukcode.DinkToPdf 方法:
// NuGet: Install-Package DinkToPdf
using DinkToPdf;
using DinkToPdf.Contracts;
using System.IO;
class Program
{
static void Main()
{
var converter = new SynchronizedConverter(new PdfTools());
var doc = new HtmlToPdfDocument()
{
GlobalSettings = {
ColorMode = ColorMode.Color,
Orientation = Orientation.Portrait,
PaperSize = PaperKind.A4,
},
Objects = {
new ObjectSettings() {
Page = "https://www.example.com",
}
}
};
byte[] pdf = converter.Convert(doc);
File.WriteAllBytes("webpage.pdf", pdf);
}
}
// NuGet: Install-Package DinkToPdf
using DinkToPdf;
using DinkToPdf.Contracts;
using System.IO;
class Program
{
static void Main()
{
var converter = new SynchronizedConverter(new PdfTools());
var doc = new HtmlToPdfDocument()
{
GlobalSettings = {
ColorMode = ColorMode.Color,
Orientation = Orientation.Portrait,
PaperSize = PaperKind.A4,
},
Objects = {
new ObjectSettings() {
Page = "https://www.example.com",
}
}
};
byte[] pdf = converter.Convert(doc);
File.WriteAllBytes("webpage.pdf", pdf);
}
}
Imports DinkToPdf
Imports DinkToPdf.Contracts
Imports System.IO
Module Program
Sub Main()
Dim converter = New SynchronizedConverter(New PdfTools())
Dim doc = New HtmlToPdfDocument() With {
.GlobalSettings = New GlobalSettings() With {
.ColorMode = ColorMode.Color,
.Orientation = Orientation.Portrait,
.PaperSize = PaperKind.A4
},
.Objects = New List(Of ObjectSettings) From {
New ObjectSettings() With {
.Page = "https://www.example.com"
}
}
}
Dim pdf As Byte() = converter.Convert(doc)
File.WriteAllBytes("webpage.pdf", pdf)
End Sub
End Module
IronPDF 方法:
// NuGet: Install-Package IronPdf
using IronPdf;
using System;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderUrlAsPdf("https://www.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://www.example.com");
pdf.SaveAs("webpage.pdf");
}
}
Imports IronPdf
Imports System
Class Program
Shared Sub Main()
Dim renderer = New ChromePdfRenderer()
Dim pdf = renderer.RenderUrlAsPdf("https://www.example.com")
pdf.SaveAs("webpage.pdf")
End Sub
End Class
Haukcode.DinkToPdf 使用相同的文档构造模式,URL 为 ObjectSettings.Page。IronPDF提供了一个专门的 RenderUrlAsPdf() 方法,可以清晰地表达意图。
请浏览 URL to PDF 文档,了解身份验证和自定义页眉选项。
自定义页面设置
配置方向、纸张大小和页边距需要采用不同的方法。
Haukcode.DinkToPdf 方法:
// NuGet: Install-Package DinkToPdf
using DinkToPdf;
using DinkToPdf.Contracts;
using System.IO;
class Program
{
static void Main()
{
var converter = new SynchronizedConverter(new PdfTools());
var doc = new HtmlToPdfDocument()
{
GlobalSettings = {
ColorMode = ColorMode.Color,
Orientation = Orientation.Landscape,
PaperSize = PaperKind.Letter,
Margins = new MarginSettings() { Top = 10, Bottom = 10, Left = 10, Right = 10 }
},
Objects = {
new ObjectSettings() {
HtmlContent = "<html><body><h1>Landscape Document</h1><p>Custom page settings</p></body></html>",
}
}
};
byte[] pdf = converter.Convert(doc);
File.WriteAllBytes("landscape.pdf", pdf);
}
}
// NuGet: Install-Package DinkToPdf
using DinkToPdf;
using DinkToPdf.Contracts;
using System.IO;
class Program
{
static void Main()
{
var converter = new SynchronizedConverter(new PdfTools());
var doc = new HtmlToPdfDocument()
{
GlobalSettings = {
ColorMode = ColorMode.Color,
Orientation = Orientation.Landscape,
PaperSize = PaperKind.Letter,
Margins = new MarginSettings() { Top = 10, Bottom = 10, Left = 10, Right = 10 }
},
Objects = {
new ObjectSettings() {
HtmlContent = "<html><body><h1>Landscape Document</h1><p>Custom page settings</p></body></html>",
}
}
};
byte[] pdf = converter.Convert(doc);
File.WriteAllBytes("landscape.pdf", pdf);
}
}
Imports DinkToPdf
Imports DinkToPdf.Contracts
Imports System.IO
Module Program
Sub Main()
Dim converter = New SynchronizedConverter(New PdfTools())
Dim doc = New HtmlToPdfDocument() With {
.GlobalSettings = New GlobalSettings() With {
.ColorMode = ColorMode.Color,
.Orientation = Orientation.Landscape,
.PaperSize = PaperKind.Letter,
.Margins = New MarginSettings() With {.Top = 10, .Bottom = 10, .Left = 10, .Right = 10}
},
.Objects = {
New ObjectSettings() With {
.HtmlContent = "<html><body><h1>Landscape Document</h1><p>Custom page settings</p></body></html>"
}
}
}
Dim pdf As Byte() = converter.Convert(doc)
File.WriteAllBytes("landscape.pdf", pdf)
End Sub
End Module
IronPDF 方法:
// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.PaperSize = PdfPaperSize.Letter;
renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape;
renderer.RenderingOptions.MarginTop = 10;
renderer.RenderingOptions.MarginBottom = 10;
renderer.RenderingOptions.MarginLeft = 10;
renderer.RenderingOptions.MarginRight = 10;
var pdf = renderer.RenderHtmlAsPdf("<html><body><h1>Landscape Document</h1><p>Custom page settings</p></body></html>");
pdf.SaveAs("landscape.pdf");
}
}
// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;
class Program
{
static void Main()
{
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.PaperSize = PdfPaperSize.Letter;
renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape;
renderer.RenderingOptions.MarginTop = 10;
renderer.RenderingOptions.MarginBottom = 10;
renderer.RenderingOptions.MarginLeft = 10;
renderer.RenderingOptions.MarginRight = 10;
var pdf = renderer.RenderHtmlAsPdf("<html><body><h1>Landscape Document</h1><p>Custom page settings</p></body></html>");
pdf.SaveAs("landscape.pdf");
}
}
Imports IronPdf
Imports IronPdf.Rendering
Class Program
Shared Sub Main()
Dim renderer = New ChromePdfRenderer()
renderer.RenderingOptions.PaperSize = PdfPaperSize.Letter
renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape
renderer.RenderingOptions.MarginTop = 10
renderer.RenderingOptions.MarginBottom = 10
renderer.RenderingOptions.MarginLeft = 10
renderer.RenderingOptions.MarginRight = 10
Dim pdf = renderer.RenderHtmlAsPdf("<html><body><h1>Landscape Document</h1><p>Custom page settings</p></body></html>")
pdf.SaveAs("landscape.pdf")
End Sub
End Class
Haukcode.DinkToPdf 将设置嵌套在 GlobalSettings 中,并使用单独的 MarginSettings 对象。IronPDF提供直接的 RenderingOptions 属性,其名称清晰明了,例如 PaperSize、PaperOrientation 以及单独的边距属性。
Haukcode.DinkToPdf API 到IronPDF的映射参考
这种映射通过显示直接的 API 对应关系来加速迁移:
转换器类映射
| Haukcode.DinkToPdf | IronPDF |
|---|---|
SynchronizedConverter |
ChromePdfRenderer |
BasicConverter |
ChromePdfRenderer |
PdfTools |
不适用 |
IConverter |
不适用 |
文档配置映射
| Haukcode.DinkToPdf | IronPDF |
|---|---|
HtmlToPdfDocument |
方法调用 |
GlobalSettings |
RenderingOptions |
ObjectSettings |
RenderingOptions |
converter.Convert(doc) |
renderer.RenderHtmlAsPdf(html) |
GlobalSettings 属性映射
| 全局设置属性 | IronPDF 属性 |
|---|---|
ColorMode |
RenderingOptions.GrayScale |
Orientation |
RenderingOptions.PaperOrientation |
PaperSize |
RenderingOptions.PaperSize |
Margins.Top |
RenderingOptions.MarginTop |
Margins.Bottom |
RenderingOptions.MarginBottom |
Margins.Left |
RenderingOptions.MarginLeft |
Margins.Right |
RenderingOptions.MarginRight |
对象设置属性映射
| 对象设置属性 | IronPDF 同等产品 |
|---|---|
HtmlContent |
第一个参数给 RenderHtmlAsPdf() |
Page (URL) |
renderer.RenderUrlAsPdf(url) |
HeaderSettings.Right = "[page]" |
TextHeader.RightText = "{page}" |
占位符语法迁移
| Haukcode.DinkToPdf | IronPDF |
|---|---|
[page] |
{page} |
[toPage] |
{total-pages} |
[date] |
{date} |
常见迁移问题和解决方案
问题 1:单例需求
Haukcode.DinkToPdf:由于原生 wkhtmltopdf 二进制文件的线程安全问题,需要将 SynchronizedConverter 作为单例。
解决方案:IronPDF的 ChromePdfRenderer 从设计上就是线程安全的——不需要单例模式:
// Before (DinkToPdf) - MUST be singleton
services.AddSingleton(typeof(IConverter), new SynchronizedConverter(new PdfTools()));
// After (IronPDF) - Can be singleton or transient (both work)
services.AddSingleton<IPdfService, IronPdfService>();
// Or services.AddTransient<IPdfService, IronPdfService>() - both are safe!
// Before (DinkToPdf) - MUST be singleton
services.AddSingleton(typeof(IConverter), new SynchronizedConverter(new PdfTools()));
// After (IronPDF) - Can be singleton or transient (both work)
services.AddSingleton<IPdfService, IronPdfService>();
// Or services.AddTransient<IPdfService, IronPdfService>() - both are safe!
' Before (DinkToPdf) - MUST be singleton
services.AddSingleton(GetType(IConverter), New SynchronizedConverter(New PdfTools()))
' After (IronPDF) - Can be singleton or transient (both work)
services.AddSingleton(Of IPdfService, IronPdfService)()
' Or services.AddTransient(Of IPdfService, IronPdfService)() - both are safe!
问题 2:本地二进制依赖关系
Haukcode.DinkToPdf:需要特定平台的本地库(libwkhtmltox.dll/so/dylib)。
解决方案:IronPDF是独立的,没有本地二进制依赖关系。 迁移后删除这些文件:
libwkhtmltox.dll(Windows)libwkhtmltox.so(Linux)libwkhtmltox.dylib(macOS)
问题 3:返回类型差异
Haukcode.DinkToPdf: converter.Convert() 直接返回 byte[]。
解决方案:IronPDF返回一个包含多个输出选项的 PdfDocument 对象:
var pdf = renderer.RenderHtmlAsPdf(html);
byte[] bytes = pdf.BinaryData; // Get bytes
pdf.SaveAs("output.pdf"); // Or save directly
var pdf = renderer.RenderHtmlAsPdf(html);
byte[] bytes = pdf.BinaryData; // Get bytes
pdf.SaveAs("output.pdf"); // Or save directly
Dim pdf = renderer.RenderHtmlAsPdf(html)
Dim bytes As Byte() = pdf.BinaryData ' Get bytes
pdf.SaveAs("output.pdf") ' Or save directly
问题 4:页眉/页脚占位符语法
Haukcode.DinkToPdf:使用方括号语法,例如 [page] 和 [toPage]。
解决方案:更新IronPDF的大括号占位符:
// Before (DinkToPdf)
HeaderSettings = { Right = "Page [page] of [toPage]" }
// After (IronPDF)
renderer.RenderingOptions.TextHeader = new TextHeaderFooter
{
RightText = "Page {page} of {total-pages}"
};
// Before (DinkToPdf)
HeaderSettings = { Right = "Page [page] of [toPage]" }
// After (IronPDF)
renderer.RenderingOptions.TextHeader = new TextHeaderFooter
{
RightText = "Page {page} of {total-pages}"
};
' Before (DinkToPdf)
HeaderSettings = New With {.Right = "Page [page] of [toPage]"}
' After (IronPDF)
renderer.RenderingOptions.TextHeader = New TextHeaderFooter With {
.RightText = "Page {page} of {total-pages}"
}
Haukcode.DinkToPdf 迁移检查表
迁移前任务
审核您的代码库,确定所有 DinkToPdf 的使用情况:
# Find DinkToPdf namespace usage
grep -r "using DinkToPdf\|using Haukcode" --include="*.cs" .
# Find converter usage
grep -r "SynchronizedConverter\|BasicConverter\|HtmlToPdfDocument" --include="*.cs" .
# Find native library loading
grep -r "wkhtmltopdf\|libwkhtmltox" --include="*.cs" --include="*.csproj" .
# Find GlobalSettings/ObjectSettings usage
grep -r "GlobalSettings\|ObjectSettings\|MarginSettings" --include="*.cs" .
# Find DinkToPdf namespace usage
grep -r "using DinkToPdf\|using Haukcode" --include="*.cs" .
# Find converter usage
grep -r "SynchronizedConverter\|BasicConverter\|HtmlToPdfDocument" --include="*.cs" .
# Find native library loading
grep -r "wkhtmltopdf\|libwkhtmltox" --include="*.cs" --include="*.csproj" .
# Find GlobalSettings/ObjectSettings usage
grep -r "GlobalSettings\|ObjectSettings\|MarginSettings" --include="*.cs" .
记录当前的 GlobalSettings 和 ObjectSettings 配置。 确定任何可以删除的本地库加载代码。
代码更新任务
1.删除 DinkToPdf NuGet 软件包 2.安装IronPDFNuGet 软件包
- 将命名空间导入从
DinkToPdf更新为IronPdf - 将
SynchronizedConverter替换为ChromePdfRenderer - 将
HtmlToPdfDocument模式转换为直接方法调用 - 将
GlobalSettings转换为RenderingOptions - 将
ObjectSettings转换为RenderingOptions - 更新占位符语法(
[page]→{page},[toPage]→{total-pages}) 9.在启动时添加IronPDF许可证初始化功能
基础架构清理任务
1.删除本地二进制文件 (libwkhtmltox.*) 2.删除本地库加载代码 3.如果存在,移除 CustomAssemblyLoadContext 4.更新依赖注入(不再需要单例) 5.删除本地二进制文件的平台检测代码
迁移后测试
迁移后,验证这些方面:
- 测试 HTML 到 PDF 的转换
- 测试 URL 到 PDF 的转换
- 验证页面设置(大小、方向、页边距)
- 用占位符验证页眉和页脚
- 使用实际的 HTML 模板进行测试
- 负载下的性能测试
迁移到IronPDF的主要优势
从 Haukcode.DinkToPdf 迁移到IronPDF有几个关键优势:
安全性:消除 CVE-2022-35583 (SSRF) 和其他 wkhtmltopdf 漏洞,这些漏洞永远不会被修复。
现代渲染引擎:使用持续更新的 Chromium 内核,而不是 2015 年就已弃用的 Qt WebKit 内核。完全支持 HTML5、CSS3 和 JavaScript。
无本地二进制文件:自包含库,无需管理任何平台特定的 DLL 文件。 简化在 Windows、Linux 和 macOS 上的部署。
线程安全:没有单例要求——可以在任何模式中自由使用 ChromePdfRenderer,包括按请求实例化。
更简单的 API:直接方法调用(RenderHtmlAsPdf(),RenderUrlAsPdf()),而不是复杂的文档对象构造。
积极开发:随着 .NET 10 和 C# 14 的普及,IronPDF 将持续更新,确保与当前和未来的 .NET 版本兼容。

