将数据库查询结果导出为 PDF 是报告生成、数据归档和文档创建等常见应用场景中的需求。通常需要将 SQL 查询结果转换为结构清晰、易于阅读的文档，以便后续共享、存档或打印使用。
由于数据库中的数据通常以表格形式存储，因此在导出过程中保持其结构完整性对于确保文档的清晰度和可读性至关重要。若缺乏合理的布局控制，生成的 PDF 很容易变得杂乱，尤其是在处理大规模数据集时，这一问题会更加明显。
本文将演示如何使用 Spire.XLS for .NET 在 C# 中将数据库转换为 PDF，包括如何检索查询结果、将其组织为结构化表格，以及最终导出为格式清晰的 PDF 文档的完整实现过程。
目录
1. 数据库转 PDF 的基本流程
将数据库内容转换为 PDF 通常包含以下几个关键步骤：
- 数据检索：执行 SQL 查询并将结果加载到内存中
- 数据结构化：对查询结果进行整理，转换为统一的表格格式
- PDF 导出：生成保留结构与可读性的 PDF 文档
在实际应用中，这一流程通常用于生成报表、制作发票或归档查询结果等场景，其核心目标是确保数据以清晰、结构化的方式呈现，便于后续查看与使用。
2. 使用 C# 将数据库转换为 PDF（分步指南）
本节提供将数据库查询结果转换为 PDF 文档的完整工作流程，涵盖数据检索、表格构建、格式设置和导出等环节。
2.1 环境设置
在实现解决方案之前，请确保您的开发环境已准备就绪：
.NET 环境
安装 Visual Studio 或使用具有兼容 .NET 版本（例如 .NET 6 或更高版本）的 .NET CLI。数据库访问
准备一个 SQL Server 数据库（或任何关系型数据库），并确保您拥有有效的连接字符串。对于现代 .NET 应用程序，请使用推荐的 SQL 客户端库：dotnet add package Microsoft.Data.SqlClient此包提供了 SQL Server 的 ADO.NET 实现，并取代了传统的
System.Data.SqlClient。Spire.XLS for .NET 通过 NuGet 安装 Spire.XLS 以处理表格格式化和 PDF 导出：
dotnet add package Spire.XLS您也可以下载 Spire.XLS for .NET 包并手动将其添加到项目中。
配置完成后，您可以从数据库检索数据并使用 Spire.XLS 生成和导出 PDF 文档。
2.2 从数据库读取数据
第一步是执行 SQL 查询并将结果加载到 DataTable 中。这种数据结构能够保留查询结果的架构和数据类型，便于后续转换处理。
在本示例中，通过在 SQL 查询中为字段设置中文别名（如“订单编号”、“客户名称”等），可以使导出的报表更符合实际业务阅读习惯。这种方式避免了在导出阶段额外处理列名，同时提升了报表的可读性和专业性。
using System.Data;
using Microsoft.Data.SqlClient;
string connectionString = "Server=localhost\\SQLEXPRESS;Database=SalesDB;User ID=demouser;Password=YourPassword;Encrypt=true;TrustServerCertificate=true;";
string query = @"
SELECT
o.OrderID AS 订单编号,
c.CustomerName AS 客户名称,
o.OrderDate AS 订单日期,
o.TotalAmount AS 订单金额
FROM Orders o
JOIN Customers c ON o.CustomerID = c.CustomerID
WHERE YEAR(o.OrderDate) = 2026;
";
DataTable dataTable = new DataTable();
using (SqlConnection conn = new SqlConnection(connectionString))
{
SqlDataAdapter adapter = new SqlDataAdapter(query, conn);
adapter.Fill(dataTable);
}
此示例使用 Microsoft.Data.SqlClient，这是适用于 .NET 的现代 SQL 客户端库，推荐使用它来替代传统的 System.Data.SqlClient。
SqlDataAdapter 充当数据库与内存数据之间的桥梁。它负责执行查询并填充 DataTable，无需手动管理读取操作的连接。
在实际开发中，可以对此步骤进行扩展，包括：
- 参数化查询以避免 SQL 注入
- 用于复杂数据检索的存储过程
- 直接在 SQL 中进行数据过滤和聚合
通过在此阶段准备好干净且结构化的数据，可以降低后续格式处理的复杂度，并提升整体性能。
如需了解将数据库查询结果导出到 Excel（而非 PDF）的类似场景，可参考：在 C# 中将数据库导出到 Excel。
2.3 导入数据并以格式化方式导出为 PDF
获取数据后，下一步是将其映射到工作表、应用格式设置，然后导出为 PDF 文档。这里利用基于工作表的布局控制，确保输出内容保持结构化和可读性。
using Spire.Xls;
using System.Drawing;
// 创建工作簿和工作表
Workbook workbook = new Workbook();
Worksheet sheet = workbook.Worksheets[0];
// 导入包含标题的 DataTable
sheet.InsertDataTable(dataTable, true, 1, 1);
// 格式化表头
CellRange headerRange = sheet.Range[1, 1, 1, dataTable.Columns.Count];
headerRange.Style.Font.IsBold = true;
headerRange.Style.Font.Size = 11;
headerRange.Style.Color = Color.LightGray;
// 应用边框以增强表格结构
CellRange dataRange = sheet.AllocatedRange;
dataRange.BorderAround(LineStyleType.Thin);
dataRange.BorderInside(LineStyleType.Thin);
// 对齐内容以保持一致性
dataRange.Style.HorizontalAlignment = HorizontalAlignType.Center;
dataRange.Style.VerticalAlignment = VerticalAlignType.Center;
// 应用全局字体
sheet.AllocatedRange.Style.Font.FontName = "微软雅黑";
// 自动调整列宽以获得更好的布局
sheet.AllocatedRange.AutoFitColumns();
// 在页面中水平居中内容
sheet.PageSetup.CenterHorizontally = true;
// 导出为 PDF
workbook.SaveToFile("SalesReport_2026.pdf", FileFormat.PDF);
此步骤将布局控制和 PDF 生成整合到一个工作流程中。
需要注意的关键点：
工作表作为布局引擎 工作表充当结构化画布，数据库数据在其中按行和列排列。这确保了原始表格结构在最终文档中得以完整保留。
格式化直接影响 PDF 输出效果 列宽、字体样式和边框等调整不仅仅是视觉美化——它们直接决定了内容在 PDF 中的渲染效果。不当的格式设置可能导致文本被截断或布局难以阅读。
自动分页功能 导出时，工作表内容会根据布局和纸张大小自动进行分页处理，这对于处理大型数据集特别有用。
如需进一步优化布局，可以通过以下方式增强表格格式：
如果您的项目需要更灵活的 PDF 结构控制，还可以探索使用 Spire.PDF for .NET 直接将 DataTable 转换为 PDF，为复杂的报表需求提供更高级的文档级操作功能。
3. 将数据库转换为 PDF 的完整 C# 示例
以下是将数据库检索、数据格式化和 PDF 导出整合到单一工作流中的完整实现代码。
using System;
using System.Data;
using Microsoft.Data.SqlClient;
using Spire.Xls;
using System.Drawing;
class Program
{
static void Main()
{
// 步骤 1：从数据库检索数据
string connectionString = "Server=localhost\\SQLEXPRESS;Database=SalesDB;User ID=demouser;Password=YourPassword;Encrypt=true;TrustServerCertificate=true;";
string query = @"
SELECT
o.OrderID AS 订单编号,
c.CustomerName AS 客户名称,
o.OrderDate AS 订单日期,
o.TotalAmount AS 订单金额
FROM Orders o
JOIN Customers c ON o.CustomerID = c.CustomerID
WHERE YEAR(o.OrderDate) = 2026;
";
DataTable dataTable = new DataTable();
using (SqlConnection conn = new SqlConnection(connectionString))
{
SqlDataAdapter adapter = new SqlDataAdapter(query, conn);
adapter.Fill(dataTable);
}
// 步骤 2：创建工作簿并导入数据
Workbook workbook = new Workbook();
Worksheet sheet = workbook.Worksheets[0];
sheet.InsertDataTable(dataTable, true, 1, 1);
// 步骤 3：应用专业格式化
// 格式化表头
CellRange headerRange = sheet.Range[1, 1, 1, dataTable.Columns.Count];
headerRange.Style.Font.IsBold = true;
headerRange.Style.Font.Size = 11;
headerRange.Style.Color = Color.LightGray;
// 应用边框
CellRange dataRange = sheet.AllocatedRange;
dataRange.BorderAround(LineStyleType.Thin);
dataRange.BorderInside(LineStyleType.Thin);
// 设置对齐方式
dataRange.Style.HorizontalAlignment = HorizontalAlignType.Center;
dataRange.Style.VerticalAlignment = VerticalAlignType.Center;
// 应用全局字体
sheet.AllocatedRange.Style.Font.FontName = "微软雅黑";
// 自动调整列宽
sheet.AllocatedRange.AutoFitColumns();
// 在页面中水平居中内容
sheet.PageSetup.CenterHorizontally = true;
// 步骤 4：导出为 PDF
workbook.SaveToFile("SalesReport_2026.pdf", FileFormat.PDF);
Console.WriteLine("数据库查询结果已成功导出为 PDF。");
}
}
以下是生成的 PDF 预览：
此示例展示了从执行 SQL 查询到生成 PDF 的完整工作流程。
4. 高级场景
在实际应用中，将数据库数据导出为 PDF 往往不止于基本转换，还可能需要处理批量导出、提升文档可读性，或调整布局设置以获得更好的展示效果。以下示例展示了实际使用中常见的增强功能。
导出多个查询结果
对于批量报表生成或定时任务等场景，可能需要执行多个查询，并将每个查询结果导出为独立的 PDF 文档：
string[] queries = {
"SELECT * FROM Orders WHERE Status = 'Pending'",
"SELECT * FROM Customers WHERE Region = 'North'"
};
for (int i = 0; i < queries.Length; i++)
{
DataTable dt = ExecuteQuery(queries[i]);
Workbook wb = new Workbook();
Worksheet ws = wb.Worksheets[0];
ws.InsertDataTable(dt, true, 1, 1);
ws.AllocatedRange.AutoFitColumns();
wb.SaveToFile($"Report_{i + 1}.pdf", FileFormat.PDF);
}
这种方法适用于需要独立导出多个数据集的自动化报表生成场景。
添加标题和更多信息
为提升可读性并提供上下文信息，可以在导出数据之前，在数据上方添加标题行：
// 插入标题行
sheet.InsertRow(1);
sheet.Range[1, 1].Text = "销售报告 - 2026";
sheet.Range[1, 1].Style.Font.IsBold = true;
sheet.Range[1, 1].Style.Font.Size = 14;
// 合并标题单元格
sheet.Range[1, 1, 1, dataTable.Columns.Count].Merge();
// 自动调整标题行
sheet.AutoFitRow(1);
下图显示了应用标题行后生成的 PDF：
添加标题有助于用户快速理解文档内容，尤其在共享或打印报表时非常实用。
设置页面大小、方向和边距
为确保 PDF 布局能够很好地适配您的数据，可以在导出前配置页面大小、方向和边距：
// 设置页面大小和方向
sheet.PageSetup.PaperSize = PaperSizeType.PaperA4;
sheet.PageSetup.Orientation = PageOrientationType.Portrait;
// 设置页面边距
sheet.PageSetup.TopMargin = 0.5f;
sheet.PageSetup.BottomMargin = 0.2f;
sheet.PageSetup.LeftMargin = 0.2f;
sheet.PageSetup.RightMargin = 0.2f;
调整这些设置有助于防止内容溢出，并确保不同报表之间的布局保持一致。
控制页面布局和缩放
处理大型表格时，可能需要控制内容在页面间的分布方式。默认情况下，内容会自动分页，但也可以调整缩放行为，以便在单个页面中容纳更多数据。
// 将内容适应页面宽度
workbook.ConverterSetting.SheetFitToWidth = true;
// 将整个工作表适应单个页面（可能会降低可读性）
workbook.ConverterSetting.SheetFitToPage = true;
SheetFitToWidth确保表格宽度适应页面，同时允许垂直方向的分页SheetFitToPage将整个工作表缩放到单个页面内
这些设置在生成紧凑报表时很有用，但应谨慎使用，避免文字过小影响阅读。
添加页眉和页脚
页眉和页脚可用于添加上下文信息，如报表标题、生成时间或页码：
sheet.PageSetup.LeftHeader = "&\"微软雅黑,Bold\"&16 销售报告 - 2026";
sheet.PageSetup.RightHeader = "&\"微软雅黑,Italic\"&10 生成日期：&D";
sheet.PageSetup.CenterFooter = "&\"微软雅黑,Regular\"&16 第 &P 页，共 &N 页";
下图显示了应用页眉和页脚后生成的 PDF：
这些元素提升了文档的导航体验，对于多页报表尤其有价值。
加密 PDF
为了保护敏感数据，您可以对导出的 PDF 应用加密：
workbook.ConverterSetting.PdfSecurity.Encrypt("openpsd");
加密功能确保只有授权用户才能访问文档，这对于包含机密信息或关键业务数据的报表非常重要。
如需了解更多关于文档导出和 PDF 自定义的相关场景，还可探索C# 中的 Excel 转 PDF 转换。
5. 常见问题
数据库连接问题
请确保连接字符串正确无误，且数据库服务器可正常访问。验证身份验证设置（如 SQL 身份验证或集成安全性），并确认加密相关参数与环境配置相匹配。
空查询结果
在继续处理之前，请检查 DataTable 是否包含数据。空结果集可能导致生成空白 PDF 或出现意外的格式问题。
if (dataTable.Rows.Count == 0)
{
Console.WriteLine("未找到指定查询的数据。");
return;
}
在生产环境中，您还可以选择生成占位符 PDF 或记录错误日志，而不是直接退出程序。
列宽溢出
处理长文本字段时，AutoFitColumns() 可能会产生过宽的列，从而对 PDF 布局造成负面影响。
为提升可读性，建议考虑以下方案：
- 设置最大列宽
- 为长内容启用文本换行
- 根据数据类型手动调整关键列
这在导出包含可变长度文本的大型数据集时尤为重要。
缺少字体支持
如果导出的 PDF 包含特殊字符（如非拉丁文字）或自定义字体，请确保所需字体已安装且在运行时可访问。
缺少字体会导致文本渲染异常或使用替代字体，从而影响文档的外观和可读性。
意外的 PDF 布局
如果导出的 PDF 布局显得拥挤或缩放不当，请检查页面设置和缩放选项，如 SheetFitToWidth 或 SheetFitToPage。
不正确的缩放设置可能导致内容显示过小，或使原始表格结构变形。
总结
本文介绍了在 C# 中将数据库查询结果转换为 PDF 的实用方法。通过将结构化数据检索与基于工作表的格式设置相结合，您可以直接从 SQL 数据生成清晰、专业的文档。
这种方法在报表生成和数据呈现场景中特别有效，尤其是在需要保持表格结构和可读性的情况下。
如果您正在评估 Spire.XLS，可以申请免费临时许可证，以便在开发过程中去除评估限制。
常见问题解答
Spire.XLS 可以在不使用第三方工具的情况下将数据库数据导出为 PDF 吗？
是的。Spire.XLS 独立执行所有操作，不需要 Microsoft Office 或任何其他外部工具。
导出大型数据集到 PDF 时应如何处理？
对于大型数据集，建议对结果进行分页处理，或通过过滤查询仅检索必要的数据。此外，还可以调整 PDF 页面设置以优化输出文件大小。
我可以自定义 PDF 页面布局吗？
是的。Spire.XLS 允许您在导出为 PDF 之前配置页面设置，包括方向、边距和纸张大小等。
此方法是否适用于 SQL Server 以外的数据库？
是的。该方法适用于支持 ADO.NET 数据提供程序的任何数据库，包括 MySQL、PostgreSQL 和 Oracle。只需使用相应的连接类和数据适配器即可。
我应该使用 Microsoft.Data.SqlClient 还是 System.Data.SqlClient？
对于现代 .NET 应用程序，建议使用 Microsoft.Data.SqlClient。该库持续更新维护，并为新版 SQL Server 功能提供更好的支持；而 System.Data.SqlClient 被视为遗留库，不再接收主要功能更新。
