在许多 Web 应用中，PDF 文件不仅仅是可下载的附件，它们往往是业务流程的最终输出结果。无论是发票、财务报表、合同、证书，还是需要在不同设备上保持版式一致的数据导出文件，PDF 都扮演着至关重要的角色。
对于 ASP.NET 开发者而言，在服务器端直接生成 PDF 文件是一项非常常见的需求。无论你是在维护传统的 ASP.NET MVC 应用，还是构建现代化的 ASP.NET Core 服务，通过代码方式生成 PDF，都可以确保输出文档在结构、排版和打印效果上的一致性。
但在实际开发中，ASP.NET 的 PDF 生成功能并不总是“开箱即用”，开发者往往会遇到一些现实问题，例如：
- 如何精确控制文档布局和分页
- 如何正确处理文本和字体
- 如何高效地将 PDF 返回给浏览器
- 如何同时兼容 ASP.NET Framework 与 ASP.NET Core
围绕这些问题，本文将结合 Spire.PDF for .NET，系统介绍在 ASP.NET 与 ASP.NET Core 环境中通过 C# 生成 PDF 的实用方案，涵盖 MVC 与 Web API 等常见项目类型。读完本文后，你将能够对 ASP.NET 中的 PDF 生成机制有一个清晰、可落地的认识，并将其直接应用到实际业务场景中。
快速导航
- ASP.NET PDF 生成的环境准备
- 在 ASP.NET Framework 中使用 C# 创建 PDF
- 在 ASP.NET Core 应用中生成 PDF
- ASP.NET PDF 生成的进阶场景
- 如何选择 ASP.NET PDF 库
- 为什么选择 Spire.PDF 用于 ASP.NET PDF 创建
- 常见问题解答
1. ASP.NET PDF 生成的环境准备
在 ASP.NET 或 ASP.NET Core 项目中开始生成 PDF 之前，首先需要确保开发环境配置正确，这有助于避免常见问题并保证项目顺利运行。
1.1 .NET SDK 要求
- ASP.NET Framework：项目目标框架需为 .NET Framework 4.6.1 或更高版本
- ASP.NET Core：根据项目需求安装 .NET 6 或 .NET 7 SDK
- 可通过以下命令检查当前已安装的 SDK 版本：
dotnet --version
1.2 安装 Spire.PDF for .NET 库
要生成 PDF，你需要使用一个与项目兼容的 PDF 库。Spire.PDF for .NET 是一个常用选择，它同时支持 ASP.NET Framework 与 ASP.NET Core。
- 在 Visual Studio 中通过 NuGet 安装：
Install-Package Spire.PDF
你也可以直接 下载 Spire.PDF for .NET 并手动安装。
- 安装完成后，请确认项目中已正确引用 Spire.Pdf.dll。
1.3 项目模板注意事项
- ASP.NET Framework：建议使用 MVC 或 Web Forms 项目，并确保已引用必要程序集（如 System.Web）
- ASP.NET Core：可使用 MVC 或 Web API 项目，并根据需要配置相关服务
同时请确保运行环境具备文件写入权限（如需保存文件），并支持文档所需的字体。
2. 在 ASP.NET Framework 中使用 C# 创建 PDF
本节将演示如何在 ASP.NET Framework 应用中使用 C# 创建 PDF 文件，适用于传统的 ASP.NET Web Forms 和 ASP.NET MVC 项目。
2.1 在 ASP.NET 中创建一个简单的 PDF 文件
在 ASP.NET 中生成 PDF 的基本流程如下：
- 创建 PdfDocument 对象
- 添加页面并绘制内容
- 使用 PdfDocument.SaveToFile() 保存文件，或直接将其返回给客户端
下面是一个简单示例，展示如何创建 PDF 并将其保存到服务器端：
using Spire.Pdf;
using Spire.Pdf.Graphics;
using System.Drawing;
PdfDocument document = new PdfDocument();
PdfPageBase page = document.Pages.Add();
PdfTrueTypeFont font = new PdfTrueTypeFont(new Font("微软雅黑", 12f, FontStyle.Regular), true);
page.Canvas.DrawString(
"本文件为系统自动生成的 PDF 文档，用于业务数据导出。",
font,
PdfBrushes.Black,
new PointF(40, 40)
);
document.SaveToFile(Server.MapPath("~/Output/Sample.pdf"));
document.Close();
该示例展示了在 ASP.NET 中通过 C# 创建 PDF 的核心流程：所有内容均由代码生成，开发者可以精确控制页面、文本和布局。你可以根据业务需要，在此基础上添加文本、表格或图片等内容，从而灵活构建完整的 PDF 文档。
如果需要在 PDF 中插入图片，可以参考教程：使用 C# 向 PDF 中插入图片。
2.2 在 ASP.NET MVC 中生成 PDF
在 ASP.NET MVC 项目中，PDF 通常在控制器的 Action 中生成，并直接返回给浏览器，从而实现在线预览或下载，而无需永久保存到服务器。
典型的 MVC PDF 生成实现如下所示：
using Spire.Pdf;
using Spire.Pdf.Graphics;
using System.Drawing;
using System.IO;
using System.Web.Mvc;
namespace WebApplication.Controllers
{
public class DefaultController : Controller
{
public ActionResult GeneratePdf()
{
// 创建 PDF 文档
using (PdfDocument document = new PdfDocument())
{
PdfPageBase page = document.Pages.Add();
PdfTrueTypeFont font = new PdfTrueTypeFont(new Font("微软雅黑", 12f, FontStyle.Regular), true);
page.Canvas.DrawString(
"在 ASP.NET MVC 中生成的 PDF 文档。",
font,
PdfBrushes.Black,
new PointF(40, 40)
);
// 将文档保存到内存流并返回给浏览器
using (MemoryStream stream = new MemoryStream())
{
document.SaveToStream(stream);
return File(
stream.ToArray(),
"application/pdf",
"MvcSample.pdf"
);
}
}
}
}
}
生成的 PDF 文档预览如下：
MVC 项目的实用说明
- 在 MVC 控制器中直接返回 FileResult，可以避免额外的中间层处理，适合将 PDF 作为最终响应返回给浏览器
- 对于临时生成的 PDF，优先使用 MemoryStream 而非本地文件，可减少磁盘 I/O 并简化文件清理逻辑；若文件体积较大或并发较高，应评估内存占用情况
- 该模式更适合由用户请求即时触发的 PDF 生成（如报表导出、发票下载），不建议用于长时间运行或批量生成任务
提示：在需要直接在线预览 PDF 的场景中，可通过 Spire.PDFViewer for ASP.NET 在 Web 环境中展示生成的文档。
</a
3. 在 ASP.NET Core 应用中生成 PDF
在 ASP.NET Core 中生成 PDF 的核心 API 与 ASP.NET Framework 基本一致，但在文件返回方式、路径处理以及运行环境假设上存在明显差异。例如，ASP.NET Core 不再依赖 System.Web，也不推荐使用基于物理路径的文件输出方式。
本节将结合具体示例，演示如何在 ASP.NET Core MVC 和 ASP.NET Core Web API 项目中，通过流（Stream）的方式生成并返回 PDF 文件，并说明这种实现方式在跨平台和云部署场景下的优势。
3.1 在 ASP.NET Core Web 应用中生成 PDF
在 ASP.NET Core Web 应用中，PDF 通常在控制器的 Action 中生成，并以文件形式返回。与 ASP.NET Framework 不同，ASP.NET Core 不再依赖 System.Web，文件处理一般基于流（Stream）实现。
下面示例演示了在控制器中生成 PDF 的基本做法。
在 IDE 中创建一个 ASP.NET Core Web App（MVC）项目，并在 Controllers 文件夹下新建一个名为 PdfController 的控制器，添加 CreatePdf() 方法：
using Microsoft.AspNetCore.Mvc;
using Spire.Pdf;
using Spire.Pdf.Graphics;
using System.Drawing;
namespace CoreWebApplication.Controllers
{
public class PdfController : Controller
{
public IActionResult CreatePdf()
{
using (PdfDocument document = new PdfDocument())
{
PdfPageBase page = document.Pages.Add();
PdfTrueTypeFont font = new PdfTrueTypeFont(new Font("微软雅黑", 14f, FontStyle.Bold), true);
page.Canvas.DrawString(
"在 ASP.NET Core 中生成的 PDF 文档。",
font,
PdfBrushes.DarkRed,
new PointF(40, 40)
);
using (MemoryStream stream = new MemoryStream())
{
document.SaveToStream(stream);
return File(
stream.ToArray(),
"application/pdf",
"AspNetCoreSample.pdf"
);
}
}
}
}
}
生成的 PDF 文档效果如下：
与 ASP.NET Framework 的主要区别
- 在 ASP.NET Core 中不再依赖 Server.MapPath 等服务器路径映射方式，更推荐直接基于流生成并返回 PDF，避免对物理路径的依赖
- 采用流式处理可以更好地适配无状态的 Web 服务架构，尤其是在容器化或云环境中，有助于减少文件系统相关的问题
- 由于 ASP.NET Core 可运行于 Windows、Linux 及 Docker 环境，PDF 生成逻辑应尽量避免依赖特定平台的字体路径或本地资源
这种基于流的 PDF 生成方式，更适合在后台管理系统或内部系统中使用，可由用户在界面上直接触发生成并下载结果，且无需在服务器端保留中间文件。
如果你需要在 PDF 中创建结构化表格，可以参考教程：在 ASP.NET Core 中使用 C# 生成 PDF 表格。
3.2 在 ASP.NET Core Web API 中生成 PDF
在前后端分离架构中，PDF 生成功能通常由 ASP.NET Core Web API 实现。此时，API 接口会以二进制流的形式返回 PDF 文件，供 Web 前端、移动端或其他服务调用。
下面是一个典型的 Web API PDF 生成示例。
在 Controllers 文件夹中创建名为 PdfApiController 的控制器，并添加如下代码：
using Microsoft.AspNetCore.Mvc;
using Spire.Pdf;
using Spire.Pdf.Graphics;
using System.Drawing;
[ApiController]
[Route("api/pdf")]
public class PdfApiController : ControllerBase
{
[HttpGet("generate")]
public IActionResult GeneratePdf()
{
PdfDocument document = new PdfDocument();
PdfPageBase page = document.Pages.Add();
PdfTrueTypeFont font = new PdfTrueTypeFont(new Font("微软雅黑", 14f, FontStyle.Bold), true);
page.Canvas.DrawString(
"由 ASP.NET Core Web API 生成的 PDF 文档。",
font,
PdfBrushes.BlueViolet,
new PointF(40, 40)
);
using (MemoryStream stream = new MemoryStream())
{
document.SaveToStream(stream);
document.Close();
return File(
stream.ToArray(),
"application/pdf",
"ApiGenerated.pdf"
);
}
}
}
生成的 PDF 预览效果如下：
Web API 场景下的注意事项
- 在 Web API 中生成 PDF 时，通常以文件流或字节数据作为响应返回，而非直接面向浏览器渲染页面
- 对于同步接口，应控制生成逻辑的执行时间，避免将复杂或耗时的 PDF 生成过程直接放在请求链路中
- 在微服务或分布式架构中，PDF 生成更常作为后台任务或自动化流程的一部分，由接口触发而非用户直接下载
当 PDF 生成被纳入自动化流程（例如定时任务或服务间调用）时，采用 Web API 的方式更有利于解耦前端交互与文档生成逻辑。
4. ASP.NET PDF 生成的进阶场景示例
前面的示例主要演示了 PDF 的基本创建流程，但在真实项目中，PDF 往往并不是静态内容，而是需要根据运行时数据动态生成，并对页面布局和分页行为进行控制。
本节将通过几个常见场景，展示在 ASP.NET 应用中如何将业务数据逐条写入 PDF，并在内容增多时保持文档结构和版式的稳定性。
4.1 将动态数据导出为 PDF
在实际业务中，PDF 通常需要根据数据库查询或接口返回的数据动态生成，而不是在代码中写死固定内容。这类场景的关键在于：如何在循环写入数据时，正确控制内容位置，并为后续分页预留空间。
下面示例演示了如何基于动态数据生成一个简单的类表格布局：
PdfDocument document = new PdfDocument();
PdfPageBase page = document.Pages.Add();
PdfTrueTypeFont headerFont = new PdfTrueTypeFont(new Font("微软雅黑", 12f, FontStyle.Bold), true);
PdfTrueTypeFont bodyFont = new PdfTrueTypeFont(new Font("微软雅黑", 10f, FontStyle.Regular), true);
float startY = 40;
float y = startY;
float pageHeight = page.Canvas.ClientSize.Height - 40;
// 标题
page.Canvas.DrawString("订单报表", headerFont, PdfBrushes.Black, 40, y);
y += 30;
// 示例动态数据
string[] orders = {
"订单编号 1001 - 金额 ¥2500",
"订单编号 1002 - 金额 ¥1800",
"订单编号 1003 - 金额 ¥3200"
};
foreach (string order in orders)
{
// 分页判断（示例数据不足以触发，但逻辑完整）
if (y > pageHeight)
{
page = document.Pages.Add();
y = startY;
}
page.Canvas.DrawString(order, bodyFont, PdfBrushes.Black, 40, y);
y += 20;
}
document.SaveToFile("OrderReport.pdf");
document.Close();
输出效果预览：
这种基于代码的生成方式，允许在运行时将数据库或接口返回的数据逐条绘制到 PDF 页面中。通过显式控制纵向位置和分页逻辑，即使数据行数发生变化，也能保证文档结构和版式的一致性，更适合用于报表和清单类输出。
4.2 PDF 样式与布局控制
在通过代码生成 PDF 时，页面布局并不会自动适配内容变化，开发者需要显式控制页眉、页脚以及内容的绘制位置。这一点在多页文档或需要打印输出的场景中尤为重要。
下面的示例演示如何添加页眉和页脚：
PdfPageBase page = document.Pages.Add();
PdfTrueTypeFont font = new PdfTrueTypeFont(new Font("微软雅黑", 12f), true);
page.Canvas.DrawString(
"公司内部资料",
font,
PdfBrushes.Gray,
new PointF(40, 15)
);
page.Canvas.DrawString(
"第 1 页",
font,
PdfBrushes.Gray,
new PointF(
page.Canvas.ClientSize.Width - 60,
page.Canvas.ClientSize.Height - 30
)
);
输出效果预览：
在多页 PDF 文档生成场景下，通过统一控制纵向位置的计算，并在写入内容前判断剩余空间，可以在数据超出单页容量时安全地切换到新页面。同时，将页眉、行距和分页规则集中管理，有助于保持跨页布局的一致性，使生成的文档既适合屏幕查看，也符合打印需求。
4.3 更多 C# 生成 PDF 方案
除了直接通过 C# 创建 PDF，一些 ASP.NET 应用还会根据需求采用其他 PDF 处理方式。你可以参考以下相关文章了解更多示例：
5. 如何在 ASP.NET 项目中选择合适的 PDF 库
在 ASP.NET 或 ASP.NET Core 中实现 PDF 生成功能时，选择合适的 PDF 库至关重要。它将直接影响开发效率、后期维护成本以及运行时性能。
与其只关注功能列表，不如从实际应用角度评估 ASP.NET PDF 库 是否符合项目需求。
关键考量因素
- API 易用性
优秀的 PDF 库应提供：
- 清晰的对象模型（文档、页面、字体、图形等）
- 易于理解的文本绘制与布局 API
- 常见操作所需的样板代码尽量少
这对于 PDF 逻辑需要长期演进的项目尤为重要。
- ASP.NET 与 ASP.NET Core 兼容性
许多团队同时维护旧版 ASP.NET 应用和新的 ASP.NET Core 服务。选择一个在以下环境中表现一致的库，可以显著降低迁移和维护成本：
- ASP.NET Framework
- ASP.NET Core
- MVC 与 Web API 项目
- 性能与稳定性
在生产环境中，PDF 生成通常运行于：
一个合格的 ASP.NET PDF 生成器 应在高负载下保持稳定，并能高效处理多页文档，避免过度占用内存。
从实践来看，PDF 库大致可分为基于 HTML 渲染和基于代码生成两类。对于需要精确控制输出结果和版式的应用，通过 C# 代码直接生成 PDF 往往是更优选择。
6. 为什么选择 Spire.PDF 用于 ASP.NET PDF 创建
得益于一致的 API 设计，Spire.PDF for .NET 中的示例代码与实际工程场景高度一致，开发者可以在理解基本用法后，自然过渡到生产级应用。
在 ASP.NET 场景下的实际优势
原生支持 ASP.NET 与 ASP.NET Core
同一套 API 可用于传统 ASP.NET、MVC、ASP.NET Core Web 应用以及 Web API 项目。
基于代码的 PDF 生成方式
无需依赖外部渲染引擎或浏览器组件，直接通过 C# 创建 PDF。
丰富的 PDF 功能
支持文本、图片、表格、分页、页眉页脚，适合报表、发票及各类业务文档。
部署友好
可稳定运行于服务器环境，包括容器化和云端托管的 ASP.NET Core 应用。
正因如此，Spire.PDF 非常适合对稳定性、布局控制以及跨版本兼容性要求较高的 ASP.NET PDF 生成场景，而不仅仅是快速 HTML 转换。
如需查看所有可用类和方法，可参考官方 API 文档：Spire.PDF for .NET API 参考。
7. 常见问题解答
是否可以在不使用 MVC 的情况下在 ASP.NET Core 中生成 PDF？
可以。ASP.NET Core 中生成 PDF 并不强制依赖 MVC，除了 MVC 控制器外，还可以在以下场景中生成并返回 PDF：
- ASP.NET Core Web API 控制器
- Minimal API
- 后台服务
只要返回的是合法的 PDF 字节流，并设置正确的 Content-Type，即可正常工作。
在 ASP.NET 和 ASP.NET Core 中生成 PDF 有什么区别？
PDF 创建的核心逻辑基本一致，但仍存在一些差异：
- ASP.NET Framework 依赖 System.Web（如 Server.MapPath）
- ASP.NET Core 采用基于流的文件处理方式
- ASP.NET Core 跨平台，更适合现代部署模式
从 PDF API 的角度来看，大部分代码逻辑是可以复用的。
是否可以在 ASP.NET 中完全通过 C# 代码生成 PDF？
可以。许多生产系统都是完全通过 C# 代码生成 PDF，这种方式具有以下优势：
- 避免 HTML 渲染带来的不一致问题
- 提供精确的版式控制
- 非常适合报表、发票等结构化文档
在强调一致性和可靠性的 ASP.NET PDF 解决方案中，这是非常常见的实现模式。
总结
在 ASP.NET 与 ASP.NET Core 应用中，生成 PDF 文件是一个非常普遍的需求，尤其适用于报表、发票和数据导出等场景。通过 C# 代码直接创建 PDF，可以对文档结构、布局和输出行为进行完全控制。
本文系统介绍了在 ASP.NET Framework 与 ASP.NET Core 中生成 PDF 的方法，涵盖了 MVC 和 Web API 场景、动态数据输出以及基础布局控制，并讨论了如何从实际项目需求出发选择合适的 PDF 库。
如果你希望在真实项目环境中完整测试这些示例、且不受功能限制，可以 申请临时许可证，以便在评估阶段解锁全部功能。
