如何在 .NET 合并 PDF 文件
IronPDF 使用基于 Chrome 的渲染引擎在 ASP.NET 中将 HTML 转换为 PDF,只需几行 C# 代码即可将您的 HTML 字符串、文件或 URL 转换为像素级完美的 PDF 文档。
当您的 ASP.NET 应用程序需要按需生成发票、报告或合规性文件时,PDF 输出的质量至关重要。 最终用户希望输出的格式与原始 HTML 完全一致——包括 CSS 样式、自定义字体和表格布局。 挑战在于找到一个能够处理这种转换的库,而无需对现代 CSS 或 JavaScript 密集型内容进行复杂的变通处理。
IronPDF是一个专为应对这一挑战而构建的 C# PDF 库。 它的 Chrome 渲染引擎以与真实浏览器相同的方式处理 HTML,这意味着您的 CSS3 属性、媒体查询和 JavaScript 渲染的内容都会在最终文档中正确显示。 以下各节将介绍安装、三种核心渲染方法、表单数据处理、高级格式化功能和身份验证支持——将生产就绪的 PDF 生成功能集成到您的 ASP.NET Core 应用程序中所需的一切。
如何在 ASP.NET Core 中快速将 HTML 转换为 PDF?
在 ASP.NET Core 中开始进行HTML 到 PDF 的转换只需要几行代码。 首先,通过 NuGet 包管理器安装 IronPDF:
Install-Package IronPdf
安装后,ChromePdfRenderer 类是所有渲染操作的主要入口点。 以下是一个完整的示例,展示了如何在 ASP.NET Core MVC 控制器中将 HTML 字符串转换为可下载的 PDF:
-
使用 NuGet 包管理器安装 https://www.nuget.org/packages/IronPdf
-
复制并运行这段代码。
using IronPdf; using Microsoft.AspNetCore.Mvc; // program.cs var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllersWithViews(); var app = builder.Build(); app.MapControllerRoute( name: "default", pattern: "{controller=Home}/{action=Index}/{id?}"); app.Run(); // PdfController.cs public class PdfController : Controller { public IActionResult GeneratePdf() { var renderer = new ChromePdfRenderer(); string html = @" <h1>Invoice #2024-001</h1> <p>Generated on: " + DateTime.Now.ToString("yyyy-MM-dd") + @"</p> <table> <tr><th>Item</th><th>Price</th></tr> <tr><td>Professional License</td><td>$999</td></tr> </table>"; var pdf = renderer.RenderHtmlAsPdf(html); return File(pdf.BinaryData, "application/pdf", "invoice.pdf"); } } -
部署到您的生产环境中进行测试
通过免费试用立即在您的项目中开始使用IronPDF
生成的 PDF 看起来像什么?

ChromePdfRenderer 类处理所有复杂的渲染,确保您的 HTML 结构、CSS 样式甚至JavaScript 在最终的 PDF 输出中正确渲染。 返回值是一个 PdfDocument 对象,其 BinaryData 属性可以直接流式传输到浏览器作为文件下载。
如何为您的源选择合适的渲染方法?
IronPDF 提供三种主要的渲染方法,每种方法都针对特定的内容源而设计。 了解哪种方法适合您的场景,可以避免不必要的复杂性,并保持控制器代码的简洁。
| 来源类型 | 方法 | 最适合 |
|---|---|---|
| 内存中的 HTML 字符串 | RenderHtmlAsPdf |
数据库驱动的报告、模板化的发票、动态内容 |
| 磁盘上的 HTML 文件 | RenderHtmlFileAsPdf |
wwwroot 中的静态模板,设计机构提供的布局 |
| 实时网页网址 | RenderUrlAsPdf |
页面归档,在 JavaScript 渲染后捕获单页应用程序 (SPA) |
如何转换动态HTML字符串?
在处理像数据库驱动报告这样的动态内容时,使用 RenderHtmlAsPdf 直接转换 HTML 字符串。 此方法接受任何有效的 HTML 标记,并返回完全渲染的 PDF 文件:
var renderer = new ChromePdfRenderer();
string htmlContent = BuildDynamicHtml(); // your method to generate HTML
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("dynamic-report.pdf");
var renderer = new ChromePdfRenderer();
string htmlContent = BuildDynamicHtml(); // your method to generate HTML
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("dynamic-report.pdf");
Dim renderer As New ChromePdfRenderer()
Dim htmlContent As String = BuildDynamicHtml() ' your method to generate HTML
Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)
pdf.SaveAs("dynamic-report.pdf")

这种方法非常适合从填充了实时数据、表单提交内容或任何动态生成内容的 HTML 模板生成 PDF 文档。 渲染引擎会保留所有 CSS 样式,包括自定义字体、颜色和表格格式。 当 HTML 使用相对路径引用外部样式表或图像时,请传递一个 baseUrl 作为第二个参数,以便渲染器可以正确解析这些资产。
如何将磁盘上的静态HTML文件转换为文本格式?
对于存储为物理文件的 HTML 模板,使用 RenderHtmlFileAsPdf 转换它们,而不需要先将它们加载到内存。这对于大型模板是高效的,并避免了字符串连接:
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlFileAsPdf("wwwroot/templates/report-template.html");
pdf.SaveAs("report.pdf");
var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlFileAsPdf("wwwroot/templates/report-template.html");
pdf.SaveAs("report.pdf");
Dim renderer As New ChromePdfRenderer()
Dim pdf = renderer.RenderHtmlFileAsPdf("wwwroot/templates/report-template.html")
pdf.SaveAs("report.pdf")
此方法会自动解析文件中引用的 CSS 样式表、图像和其他外部资源的相对路径。当您的设计团队在应用程序的 C# 代码库之外维护单独的 HTML 模板文件时,此方法非常有效。 该方法支持CSS 打印媒体查询和自定义字体,因此为打印环境构建的模板无需额外配置即可忠实呈现。
如何将网页URL转换为PDF?
要捕获实时网页或将可访问URL的页面渲染为 PDF,请使用 RenderUrlAsPdf。 该方法启动 Chrome 浏览器引擎,导航到 URL,等待页面完全加载,然后捕获渲染后的输出:
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.EnableJavaScript = true;
renderer.RenderingOptions.WaitFor.RenderDelay(1000);
renderer.RenderingOptions.CssMediaType = PdfCssMediaType.Screen;
var pdf = renderer.RenderUrlAsPdf("https://en.wikipedia.org/wiki/PDF");
pdf.SaveAs("webpage.pdf");
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.EnableJavaScript = true;
renderer.RenderingOptions.WaitFor.RenderDelay(1000);
renderer.RenderingOptions.CssMediaType = PdfCssMediaType.Screen;
var pdf = renderer.RenderUrlAsPdf("https://en.wikipedia.org/wiki/PDF");
pdf.SaveAs("webpage.pdf");
Dim renderer = New ChromePdfRenderer()
renderer.RenderingOptions.EnableJavaScript = True
renderer.RenderingOptions.WaitFor.RenderDelay(1000)
renderer.RenderingOptions.CssMediaType = PdfCssMediaType.Screen
Dim pdf = renderer.RenderUrlAsPdf("https://en.wikipedia.org/wiki/PDF")
pdf.SaveAs("webpage.pdf")

WaitFor.RenderDelay 选项告诉渲染器在加载页面后暂停,然后再捕获。 对于在初始 HTML 响应到达后通过 JavaScript 构建 DOM 的单页应用程序来说,这很有价值。 设置 EnableJavaScript = true 启用完整的 Chrome JavaScript 引擎,因此图表、数据网格和其他用 JavaScript 渲染的组件在 PDF 中显示得像在浏览器中一样。
如何处理表单数据和 POST 请求?
在 ASP.NET 应用程序中,在生成 PDF 之前处理表单数据是一种常见的模式——订单确认、送货单和收据都遵循这种模式。 该方法是将提交的表单数据绑定到一个模型,根据该模型构建一个 HTML 字符串,然后将该字符串渲染为 PDF:
[HttpPost]
public IActionResult ProcessFormToPdf(OrderModel model)
{
var renderer = new ChromePdfRenderer();
string html = $@"
<h2>Order Confirmation</h2>
<p>Customer: {model.CustomerName}</p>
<p>Order Date: {model.OrderDate:yyyy-MM-dd}</p>
<ul>
{string.Join("", model.Items.Select(i => $"<li>{i.Name} -- ${i.Price}</li>"))}
</ul>
<p><strong>Total: ${model.Total}</strong></p>";
var pdf = renderer.RenderHtmlAsPdf(html);
string fileName = $"order-{model.OrderId}.pdf";
return File(pdf.BinaryData, "application/pdf", fileName);
}
[HttpPost]
public IActionResult ProcessFormToPdf(OrderModel model)
{
var renderer = new ChromePdfRenderer();
string html = $@"
<h2>Order Confirmation</h2>
<p>Customer: {model.CustomerName}</p>
<p>Order Date: {model.OrderDate:yyyy-MM-dd}</p>
<ul>
{string.Join("", model.Items.Select(i => $"<li>{i.Name} -- ${i.Price}</li>"))}
</ul>
<p><strong>Total: ${model.Total}</strong></p>";
var pdf = renderer.RenderHtmlAsPdf(html);
string fileName = $"order-{model.OrderId}.pdf";
return File(pdf.BinaryData, "application/pdf", fileName);
}
Imports System
Imports System.Linq
Imports Microsoft.AspNetCore.Mvc
<HttpPost>
Public Function ProcessFormToPdf(model As OrderModel) As IActionResult
Dim renderer = New ChromePdfRenderer()
Dim html As String = $"
<h2>Order Confirmation</h2>
<p>Customer: {model.CustomerName}</p>
<p>Order Date: {model.OrderDate:yyyy-MM-dd}</p>
<ul>
{String.Join("", model.Items.Select(Function(i) $"<li>{i.Name} -- ${i.Price}</li>"))}
</ul>
<p><strong>Total: ${model.Total}</strong></p>"
Dim pdf = renderer.RenderHtmlAsPdf(html)
Dim fileName As String = $"order-{model.OrderId}.pdf"
Return File(pdf.BinaryData, "application/pdf", fileName)
End Function
表单界面是什么样的?

表单数据在生成的PDF文件中如何显示?

对于更高级的文档应用场景,您可以集成PDF 表单或编辑带有预填充字段的现有 PDF 模板。 该库还支持法律文件和合同的数字签名,允许您向任何生成的文档添加加密可验证的签名。
将用户数据嵌入 HTML 字符串时,一个重要的考虑因素是数据清理。 为防止注入问题,在将用户提供的字符串插入 HTML 之前,务必对其进行转义。 在每个字段上简单的 System.Web.HttpUtility.HtmlEncode(model.CustomerName) 调用会在将模板传递给渲染器之前保持其安全。
如何添加专业格式、页眉和水印?
如何配置页眉、页脚和水印?
专业的 PDF 文档通常需要在每一页上添加页眉和页脚,草稿或机密文档还需要添加水印。 IronPDF 通过 RenderingOptions 对象的属性和生成的 PdfDocument 上的 ApplyWatermark 方法处理两者:
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
MaxHeight = 25,
HtmlFragment = "<div style='text-align:center'>Annual Report 2024</div>"
};
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
MaxHeight = 20,
HtmlFragment = "<div style='text-align:center'>Page {page} of {total-pages}</div>"
};
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.ApplyWatermark("<h2 style='color:red;opacity:0.3'>CONFIDENTIAL</h2>",
30, VerticalAlignment.Middle, HorizontalAlignment.Center);
pdf.SaveAs("report-with-watermark.pdf");
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
MaxHeight = 25,
HtmlFragment = "<div style='text-align:center'>Annual Report 2024</div>"
};
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
MaxHeight = 20,
HtmlFragment = "<div style='text-align:center'>Page {page} of {total-pages}</div>"
};
var pdf = renderer.RenderHtmlAsPdf(htmlContent);
pdf.ApplyWatermark("<h2 style='color:red;opacity:0.3'>CONFIDENTIAL</h2>",
30, VerticalAlignment.Middle, HorizontalAlignment.Center);
pdf.SaveAs("report-with-watermark.pdf");
Imports IronPdf
Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.HtmlHeader = New HtmlHeaderFooter With {
.MaxHeight = 25,
.HtmlFragment = "<div style='text-align:center'>Annual Report 2024</div>"
}
renderer.RenderingOptions.HtmlFooter = New HtmlHeaderFooter With {
.MaxHeight = 20,
.HtmlFragment = "<div style='text-align:center'>Page {page} of {total-pages}</div>"
}
Dim pdf = renderer.RenderHtmlAsPdf(htmlContent)
pdf.ApplyWatermark("<h2 style='color:red;opacity:0.3'>CONFIDENTIAL</h2>", 30, VerticalAlignment.Middle, HorizontalAlignment.Center)
pdf.SaveAs("report-with-watermark.pdf")

页脚 HTML 中的 {page} 和 {total-pages} 占位符在渲染时自动替换,因此可以获得正确的页码而无需后处理。 您还可以添加页码、背景图像或前景叠加层,以及自定义文本或图像印章。
如何使用 CSS 打印媒体进行 PDF 布局控制?
为了确保 PDF 输出符合预期,请使用 CSS @media print 规则和 PdfCssMediaType.Print 设置。 IronPDF 完全支持分页控制和自定义纸张尺寸:
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.CssMediaType = PdfCssMediaType.Print;
renderer.RenderingOptions.ViewPortWidth = 1024;
renderer.RenderingOptions.MarginTop = 10;
renderer.RenderingOptions.MarginBottom = 10;
renderer.RenderingOptions.MarginLeft = 10;
renderer.RenderingOptions.MarginRight = 10;
string html = @"
<style>
@media print {
.no-print { display: none; }
body { font-size: 12pt; }
.page-break { page-break-after: always; }
}
@page {
size: A4;
margin: 1cm;
}
</style>
<div class='content'>
<h1>Professional Report</h1>
<div class='page-break'></div>
<h2>Section 2</h2>
</div>";
var pdf = renderer.RenderHtmlAsPdf(html);
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.CssMediaType = PdfCssMediaType.Print;
renderer.RenderingOptions.ViewPortWidth = 1024;
renderer.RenderingOptions.MarginTop = 10;
renderer.RenderingOptions.MarginBottom = 10;
renderer.RenderingOptions.MarginLeft = 10;
renderer.RenderingOptions.MarginRight = 10;
string html = @"
<style>
@media print {
.no-print { display: none; }
body { font-size: 12pt; }
.page-break { page-break-after: always; }
}
@page {
size: A4;
margin: 1cm;
}
</style>
<div class='content'>
<h1>Professional Report</h1>
<div class='page-break'></div>
<h2>Section 2</h2>
</div>";
var pdf = renderer.RenderHtmlAsPdf(html);
Imports IronPdf
Dim renderer As New ChromePdfRenderer()
renderer.RenderingOptions.CssMediaType = PdfCssMediaType.Print
renderer.RenderingOptions.ViewPortWidth = 1024
renderer.RenderingOptions.MarginTop = 10
renderer.RenderingOptions.MarginBottom = 10
renderer.RenderingOptions.MarginLeft = 10
renderer.RenderingOptions.MarginRight = 10
Dim html As String = "
<style>
@media print {
.no-print { display: none; }
body { font-size: 12pt; }
.page-break { page-break-after: always; }
}
@page {
size: A4;
margin: 1cm;
}
</style>
<div class='content'>
<h1>Professional Report</h1>
<div class='page-break'></div>
<h2>Section 2</h2>
</div>"
Dim pdf = renderer.RenderHtmlAsPdf(html)

使用打印 CSS 可确保您的 PDF 文档保持专业格式,同时隐藏不必要的网络元素,如导航菜单或交互式按钮。 设置 CssMediaType = PdfCssMediaType.Print 会告诉渲染器应用您的 @media print 规则而不是屏幕样式,这通常会移除背景装饰并调整排版以适应打印输出。 您还可以配置每页的自定义边距,并控制宽幅或旋转报表的页面方向和旋转。
W3C CSS 页面媒体规范 定义了像 page-break-before 和 widows 这样的属性应该在分页输出中如何表现。 IronPDF 的 Chrome 引擎严格遵循此规范,因此按照 CSS 标准编写的样式可以准确地转换为 PDF,无需手动调整。
如何处理受保护页面的身份验证?
对于安全应用程序,IronPDF 支持各种身份验证方法,包括cookie 、 HTTP 请求标头和网络凭据。 这样,您就可以渲染需要登录会话或基本身份验证的页面:
var renderer = new ChromePdfRenderer();
renderer.RequestContext.Cookies.Add(new Cookie
{
Name = "SessionId",
Value = "your-session-token",
Domain = "example.com"
});
renderer.ChromePdfRenderOptions.HttpLoginCredentials = new HttpLoginCredentials
{
Username = "user",
Password = "password"
};
var pdf = renderer.RenderUrlAsPdf("https://app.example.com/protected/report");
var renderer = new ChromePdfRenderer();
renderer.RequestContext.Cookies.Add(new Cookie
{
Name = "SessionId",
Value = "your-session-token",
Domain = "example.com"
});
renderer.ChromePdfRenderOptions.HttpLoginCredentials = new HttpLoginCredentials
{
Username = "user",
Password = "password"
};
var pdf = renderer.RenderUrlAsPdf("https://app.example.com/protected/report");
Dim renderer = New ChromePdfRenderer()
renderer.RequestContext.Cookies.Add(New Cookie With {
.Name = "SessionId",
.Value = "your-session-token",
.Domain = "example.com"
})
renderer.ChromePdfRenderOptions.HttpLoginCredentials = New HttpLoginCredentials With {
.Username = "user",
.Password = "password"
}
Dim pdf = renderer.RenderUrlAsPdf("https://app.example.com/protected/report")
您还可以使用所有者密码和用户密码对生成的 PDF 文件进行加密,从而限制打印、复制或编辑等操作。 将基于身份验证的渲染与 PDF 级别的权限相结合,您可以控制谁可以生成文档以及收件人获得文档后可以对其进行哪些操作。
对于企业环境,在 Web 请求处理程序中生成 PDF 时,请考虑使用异步渲染 API 。 异步渲染使 ASP.NET 线程池在 Chrome 引擎处理文档时保持空闲,从而提高了并发负载下的吞吐量。 该库还支持多线程渲染,适用于批量文档生成场景。
为什么 Chrome 渲染引擎对 HTML 转 PDF 很重要?
大多数 PDF 生成库都使用自定义引擎自行解析 HTML。这意味着它们仅支持部分 CSS 属性,缺乏 JavaScript 执行能力,并且难以处理 CSS Grid 或 Flexbox 等现代布局技术。 IronPDF 采用了不同的方法,它嵌入了 Chrome 引擎——与 Google Chrome 浏览器相同的技术。
实际结果是,任何在 Chrome 中正确显示的 HTML 页面都可以通过 IronPDF 正确渲染成 PDF。 这样就消除了一类常见的错误,即由于渲染引擎对 CSS 的解释与开发人员在设计时使用的浏览器不同,导致 PDF 输出与预期外观出现偏差。
MDN Web Docs 中关于 CSS 分页媒体的参考文档和Microsoft 的 ASP.NET Core 文档都描述了 IronPDF 通过其基于 Chrome 的基础所支持的功能。 已经熟悉标准 HTML、CSS 和 JavaScript 的开发人员可以直接将这些知识应用于 PDF 生成,而无需学习单独的文档布局语言。
IronPDF 的渲染选项提供了纸张大小、边距、JavaScript 执行和渲染延迟的控制选项。 该库可以处理 UTF-8 文本和国际字符集,引用 Google Fonts 或本地文件的 Web 字体,甚至可以将Markdown 文档转换为 PDF 。 为了满足存档或无障碍合规性要求,它支持PDF/A和PDF/UA输出格式。 该库可在Windows、Linux 和 macOS上运行,无需额外配置即可部署到Azure和AWS 。
下一步计划是什么?
using IronPDF 在 ASP.NET C# 中将 HTML 转换为 PDF,可以为您的应用程序提供可靠且与浏览器兼容的文档生成流程。三种渲染方式——HTML 字符串、HTML 文件和 URL——涵盖了您在实践中会遇到的所有内容源。诸如页眉、页脚、水印和打印 CSS 等高级功能,让您无需手动对 PDF 进行后处理即可生成专业的输出。
下一步是安装 NuGet 包并运行本指南第一部分中的快速入门示例。之后,您可以阅读完整的 C# PDF 教程,深入了解文档结构,或者查看PDF 编辑指南,学习如何合并、拆分、注释和提取现有 PDF 的内容。
如果您的项目以 Blazor 为目标, Blazor PDF 教程将逐步介绍服务器端和 WebAssembly 集成。 对于 MVC 项目,MVC Core PDF 指南 和 Razor Pages 指南 涵盖了使用 .cshtml 视图的基于模板的渲染。 为了进行调试和性能调优,IronPDF 提供自定义日志记录和性能指导,帮助识别高容量文档生成工作流程中的瓶颈。
在购买许可证之前,先开始免费试用,在您自己的项目中测试库的每个功能。 对于生产部署,可用的许可选项适用于个人开发者、团队和企业再分发场景。
常见问题解答
如何在 ASP.NET Core 中将 HTML 转换为 PDF?
通过NuGet安装IronPDF,创建一个ChromePdfRenderer实例,并使用HTML字符串调用RenderHtmlAsPdf。渲染器返回一个PdfDocument,其BinaryData可以流式传输到浏览器。
IronPDF 为何适用于 HTML 到 PDF 的转换?
IronPDF嵌入了Chrome渲染引擎,因此任何在Chrome中正确显示的HTML页面都可以正确呈现为PDF。这包括CSS3、JavaScript生成的内容、网页字体和响应式布局。
是否可以在 ASP.NET 中使用 IronPDF 生成发票和报告?
是的。从数据模型构建HTML字符串,将其传递给RenderHtmlAsPdf,并将BinaryData作为文件下载返回。IronPDF在输出中保留了表格格式、自定义字体和CSS样式。
IronPDF支持CSS打印媒体查询吗?
是的。设置RenderingOptions.CssMediaType = PdfCssMediaType.Print以激活@media打印规则,隐藏导航元素并应用打印优化的排版。
IronPDF可以处理JavaScript生成的内容吗?
是的。设置RenderingOptions.EnableJavaScript = true并使用WaitFor.RenderDelay在页面加载后暂停,以便JavaScript引擎有时间在PDF被捕获之前构建DOM。
IronPDF如何处理受保护页面的身份验证?
IronPDF通过RequestContext.Cookies和ChromePdfRenderOptions.HttpLoginCredentials属性支持会话cookie、HTTP头和基本身份验证凭据。
IronPDF 支持哪些平台?
IronPDF运行在Windows、Linux和macOS上,可以部署到Azure和AWS。它支持.NET 6、.NET 7、.NET 8以及.NET Framework 4.6.2及更高版本。
IronPDF支持用于归档的PDF/A输出吗?
是的。IronPDF支持长期归档的PDF/A合规性和可访问性的PDF/UA。这些输出模式可以通过SaveAsPdfA和SaveAsPdfUA方法配置。

