C#实现HTML转PDF/XPS/XML的完整方案与实战

1. 为什么需要将HTML转换为多种格式？

在软件开发领域，HTML到PDF/XPS/XML的转换是一个高频需求场景。我最近接手的一个企业报表系统项目就遇到了典型用例：需要将动态生成的HTML报表导出为PDF供财务存档，同时要生成XPS格式用于数字签名，还要保留XML结构化数据供下游系统分析。

这种需求在以下场景特别常见：

• 企业OA系统中的公文流转（红头文件需要PDF固化）
• 电商平台的电子发票生成（法律要求PDF格式）
• 医疗系统的检验报告输出（需要XPS的数字墨水特性）
• 数据分析系统的可视化报表导出（同时保留机器可读的XML）

1.1 各格式的特性对比

选择转换格式时需要考虑这些技术特性：

提示：XPS虽然在通用性上不如PDF，但在Windows平台打印保真度方面有独特优势，特别适合医疗手写板等数字墨水场景。

2. C#生态中的转换方案选型

经过多个项目的实践验证，我总结出C#实现HTML转换的三大技术路线：

2.1 基于浏览器引擎的方案

csharp复制// 使用PuppeteerSharp的示例
var browser = await Puppeteer.LaunchAsync(new LaunchOptions {
    Headless = true
});
var page = await browser.NewPageAsync();
await page.SetContentAsync(htmlContent);
await page.PdfAsync("output.pdf");

优势：

• 完美支持现代CSS/JavaScript
• 渲染效果与浏览器一致
• 支持动态页面转换

坑点：

• 需要部署浏览器环境
• 内存占用较高（实测单个转换约占用200MB）

2.2 专用转换库方案

csharp复制// 使用SelectPdf的示例
var converter = new SelectPdf.HtmlToPdf();
converter.Options.PdfPageSize = PdfPageSize.A4;
var doc = converter.ConvertHtmlString(html);
doc.Save("output.pdf");

选型建议：

• SelectPdf：商业方案中性价比最高
• EvoPdf：对复杂CSS支持更好
• Winnovative：已停止更新，不推荐新项目使用

2.3 系统原生组件方案

csharp复制// 使用XpsDocument的示例
var xpsDoc = new XpsDocument("output.xps", FileAccess.Write);
var writer = XpsDocument.CreateXpsDocumentWriter(xpsDoc);
writer.Write(visual); // 需要先将HTML转为Visual对象

适用场景：

• 需要与WPF深度集成时
• 对Windows平台有强依赖的项目
• 需要利用XPS打印特性的场景

3. 实战：完整转换流水线实现

下面以企业级应用标准，演示一个支持三种格式转换的完整服务实现：

3.1 基础架构设计

csharp复制public interface IHtmlConverter 
{
    byte[] ToPdf(string html);
    byte[] ToXps(string html);
    XDocument ToXml(string html);
}

public class HtmlConversionService : IHtmlConverter
{
    // 具体实现后文展开
}

3.2 PDF转换核心实现

csharp复制public byte[] ToPdf(string html)
{
    var converter = new HtmlToPdf();
    
    // 关键配置项
    converter.Options.MarginTop = 20;
    converter.Options.EmbedFonts = true;
    converter.Options.WebPageWidth = 1024;
    
    // 中文支持
    converter.Options.FontEmbedding = true;
    converter.Options.CustomWkHtmlArgs = "--encoding utf-8";
    
    return converter.ConvertHtmlString(html);
}

字体处理要点：

1. 必须启用FontEmbedding
2. 服务器需安装所需字体
3. 通过CustomWkHtmlArgs指定编码

3.3 XPS转换特殊处理

csharp复制public byte[] ToXps(string html)
{
    // 先将HTML转为FixedDocument
    var flowDoc = (FlowDocument)XamlReader.Parse(html);
    var document = new FixedDocument();
    var pageContent = new PageContent();
    
    // 尺寸配置
    var fixedPage = new FixedPage();
    fixedPage.Width = 96 * 8.5; // 8.5英寸
    fixedPage.Children.Add(flowDoc);
    
    document.Pages.Add(pageContent);
    
    // 转为XPS
    using var ms = new MemoryStream();
    var package = Package.Open(ms, FileMode.Create);
    var xpsDoc = new XpsDocument(package);
    XpsDocumentWriter writer = XpsDocument.CreateXpsDocumentWriter(xpsDoc);
    writer.Write(document);
    
    return ms.ToArray();
}

注意：XPS转换需要处理DPI问题，96DPI是WPF的标准值，与实际打印尺寸换算时需特别注意。

3.4 XML结构化转换技巧

csharp复制public XDocument ToXml(string html)
{
    // 使用HtmlAgilityPack解析
    var doc = new HtmlDocument();
    doc.LoadHtml(html);
    
    // 构建XML结构
    var xdoc = new XDocument(
        new XElement("root",
            doc.DocumentNode.SelectNodes("//div[@class='section']")
                .Select(node => new XElement("section",
                    new XAttribute("title", node.Attributes["title"]?.Value),
                    node.InnerText
                ))
        )
    );
    
    return xdoc;
}

元素定位策略：

• 给HTML元素添加data-role属性辅助定位
• 使用XPath比CSS选择器更可靠
• 对表格数据建议转为结构

4. 企业级应用的关键问题处理

在实际项目落地时，这些问题的处理决定成败：

4.1 批量转换的性能优化

csharp复制// 并行处理示例
Parallel.ForEach(htmlFiles, file => {
    var pdf = converter.ToPdf(File.ReadAllText(file));
    File.WriteAllBytes(Path.ChangeExtension(file, ".pdf"), pdf);
});

优化指标：

• 单次转换控制在3秒内
• 内存占用不超过500MB
• 支持至少10个并发转换

4.2 样式一致性保障方案

通过引入CSS规范化策略：

1. 重置样式表（normalize.css）
2. 打印专用样式表（@media print）
3. 强制字体嵌入（@font-face）
4. 使用相对单位（rem/em）

4.3 异常处理机制

csharp复制try 
{
    return converter.ConvertHtmlString(html);
}
catch (HtmlConversionException ex)
{
    _logger.LogError(ex, "转换失败");
    return FallbackConvert(html); // 降级方案
}

典型异常：

• 字体缺失（FontNotFoundException）
• 布局溢出（ContentOverflowException）
• 超时（ConversionTimeoutException）

5. 高级应用场景扩展

5.1 动态水印实现

csharp复制converter.BeforeRender = (doc, args) => {
    var page = args.Page;
    page.Canvas.DrawString("CONFIDENTIAL", 
        new XFont("Arial", 20, XFontStyle.Bold),
        XBrushes.Red, 
        new XPoint(100, 100),
        new XStringFormat {
            Alignment = XStringAlignment.Center
        });
};

水印类型：

• 文本水印（支持旋转）
• 图片水印（PNG透明图层）
• 动态二维码（含业务数据）

5.2 文档安全加固

csharp复制var securityOptions = new PdfSecurityOptions {
    UserPassword = "user123",
    OwnerPassword = "owner456",
    Permissions = PdfPermissions.Print | PdfPermissions.CopyContent
};
converter.Options.SecurityOptions = securityOptions;

安全策略：

• 密码分级保护
• 权限精细化控制
• 数字签名（需X509证书）

5.3 与工作流引擎集成

在Camunda等BPMN引擎中，可以通过C#委托任务实现自动转换：

xml复制<serviceTask id="pdfTask" name="Generate PDF" 
  implementation="CSharp"
  class="MyProject.HtmlToPdfDelegate" />

对应的委托类：

csharp复制public class HtmlToPdfDelegate : IJavaDelegate 
{
    public void Execute(DelegateExecution execution) {
        var html = (string)execution.GetVariable("htmlContent");
        var pdf = new HtmlConverter().ToPdf(html);
        execution.SetVariable("pdfOutput", pdf);
    }
}

6. 实测性能对比数据

在Dell PowerEdge R740服务器上测试（100次转换取平均值）：

选型建议：

• 高并发场景：SelectPdf商业版
• 需要精确渲染：Puppeteer方案
• Windows环境专用：XPS原生方案

7. 常见问题解决方案

Q：中文显示为方框？

• 确保系统安装中文字体
• 在CSS中显式指定font-family
• 检查转换工具的编码设置

Q：CSS样式丢失？

• 使用内联样式替代外部样式表
• 检查媒体查询是否包含print类型
• 验证CSS选择器是否被转换工具支持

Q：分页位置错误？

• 添加page-break-before/after控制
• 避免在浮动元素处分页
• 调整转换器的页面高度参数

在最近的一个政务项目里，我们通过组合使用PuppeteerSharp和HtmlAgilityPack，实现了98%以上的样式保真度。关键是在转换前先用JavaScript动态计算布局，通过data属性将计算结果传递给C#端，这种前后端协作的方式解决了复杂表格的分页难题。