💡 完整的工作示例可在 GitHub 上获取: convert-email-and-attachments-to-pdf-dotnet

Email-to-PDF 转换是一个针对 .NET 的 GroupDocs.Conversion 工作流, 可以将 Outlook 邮件及其附件转换为一个或多个 PDF 文件, 并且不会出现一个附件覆盖另一个附件,或因不支持的文件导致整个运行中断的情况。它用几行代码取代了手动导出并重命名的流程,这些代码能够知道每个项目的来源以及是否成功转换。

旧方法很痛苦

想象一下一个支持收件箱,每个案例邮件都会带有两三个附件——这里有报告,那里有截图,有时还有团队成员不认识的文件格式。这并不罕见。处理该案例意味着打开邮件, 手动保存每个附件,因两个系统都导出了名为 report.csv 的文件而对冲突的文件进行重命名,并且希望集合中没有任何你的 PDF 查看器无法打开的格式。每周这样做五十次,“快速导出”就会成为工作中最慢的环节,也是最容易匆忙处理的环节,而这正是错误发生的时机。

手动完成这些工作不仅耗时——它也是文件悄然丢失的地方。将两个同名为 report.csv 的附件保存到同一文件夹而不先重命名,第二次保存会覆盖第一次;没人注意到,直到九月份的数据找不到为止。即使只有一个附件的格式没有转换器,也会导致整个导出卡住,直到有人决定如何处理它。

手动操作的真实代价:被重命名并覆盖的附件不会抛出错误——它只是悄然消失,案例文件看起来完整,直到有人需要其中的数据时才发现问题。

有更好的方法

GroupDocs.Conversion for .NET 将此过程简化为几行代码。无需手动重命名。其 EmailLoadOptions 类控制是仅转换邮件、仅转换附件,还是两者都转换,而 SaveContext 回调能够为每个输出项提供足够的信息,使得两个同名为 report.csv 的附件永不冲突,且没有 PDF 路径的附件也不会阻止其余流程。每次调用该回调都会报告 ItemIndex(从 1 开始的递增计数),HierarchyLevel(消息为 0,附件为 1)以及 SourceFileName(原始文件名),这些信息足以在不编写额外 bookkeeping 代码的情况下生成不冲突的输出名称。

在开始之前,你需要:

  • .NET SDK 8.0 或更高版本
  • GroupDocs.Conversion for .NET 26.10.0(获取临时许可证 以移除评估限制)
  • 一个待转换的 Outlook .msg 或 .eml 邮件

使用一条命令安装:

dotnet add package GroupDocs.Conversion --version 26.10.0

新方法:转换邮件及其附件

下面展示了使用 GroupDocs.Conversion 完成相同任务的代码示例。该示例将 Outlook 邮件及其每个附件分别转换为 PDF,文件名永不冲突。

步骤 1 - 决定要转换的内容

EmailLoadOptions.ConvertOwner 和 ConvertOwned 分别控制消息本身和其附件的开关;Depth(默认 2)限制了嵌套附件的追踪深度。

// Convert the message itself and every attachment it carries
var loadOptions = new EmailLoadOptions
{
    ConvertOwner = true,
    ConvertOwned = true,
    Depth = 2
};

步骤 2 - 使用 SaveContext 为每个输出命名

将 SaveContext 回调传递给 Converter.Convert,而不是使用固定的输出路径。回调会对每个项目触发一次,ItemIndex 对每个项目都是唯一的,即使两个附件共享同一文件名。

using (var converter = new Converter(messagePath, (LoadContext _) => loadOptions))
{
    converter.Convert((SaveContext item) =>
    {
        // ItemIndex is 1 for the message, then counts up per attachment
        string name = $"{item.ItemIndex:D2}-{item.SourceFileName}.pdf";
        return File.Create(Path.Combine(outputFolder, name));
    }, new PdfConvertOptions());
}

步骤 3 - 处理没有 PDF 路径的附件

并非所有附件都能转换为 PDF。检查 SaveContext.TargetFormat 是否等于 FileType.Unknown,如果是,则按原名称保存该项目,而不是进行转换。

converter.Convert((SaveContext item) =>
{
    bool passedThrough = item.TargetFormat == FileType.Unknown;
    string baseName = $"{item.ItemIndex:D2}-{item.SourceFileName}";
    string name = passedThrough
        ? baseName
        : $"{baseName}.{item.TargetFormat.Extension}";
    return File.Create(Path.Combine(outputFolder, name));
}, new PdfConvertOptions());

将此代码指向一封包含两个同名 report.csv 附件和一个不受支持格式附件的示例支持邮件。会生成三个 PDF:邮件本身以及两个 CSV 报告。不受支持的文件也会被保存下来,保持原样——将其与原文件并排打开,所有 32 字节都对应。

如何避免覆盖具有相同文件名的附件?

单独的文件名无法作为安全的输出键,因为两个附件可能携带完全相同的名称。将 SaveContext.ItemIndex 与 SaveContext.SourceFileName 组合进名称中,两个同名 report.csv 的附件就不会争夺同一个磁盘位置;每个附件都会得到自己的零填充前缀(示例中为 02- 和 03-,在消息的 01- 之后)以及各自的文件,无论源文件名为何。

对比:之前 vs. 之后

之前(手动) 之后(GroupDocs.Conversion)
时间 每封邮件几分钟,手工操作 几行代码,任意数量的邮件
重复名称 静默覆盖 通过 ItemIndex 保持分离
不支持的附件 中断整个转换(26.10 之前) 以原名保存,继续运行
输出 你的 PDF 查看器能保存的内容 结构化的 PDF,便于归档或索引

示例中的支持邮件正是由这种组合构成:两个同名的月度 CSV 导出,以及一个没有转换器识别的捕获文件。

真实案例:支持案例归档

一个支持团队将每个客户案例记录为带有一个或多个电子表格附件的邮件,案例跟踪系统需要将每个附件单独归档为可搜索的 PDF,且与邮件分离。对每个来件调用一次 KeepAttachmentsWithoutPdfRoute,即可将邮件及其附件转换为编号文件集,即使两个报告同名也永不覆盖。包含两个月度 report.csv 导出和一个无人能转换的捕获文件的案例邮件会生成四个文件:邮件本身、两个 CSV 报告的 PDF,以及以原名保存的捕获文件——没有丢失、没有合并、没有静默覆盖。

// One call per case e-mail - no manual export, no renamed duplicates
int kept = KeepAttachmentsWithoutPdfRoute(caseMessagePath, caseOutputFolder);

GroupDocs.Conversion for .NET 还能做什么?

除了将消息与附件分离之外,EmailLoadOptions 还覆盖了更多关于消息本身的选项:

  • 字段可见性:使用 DisplayHeader 以及相关的 Display* 选项(默认隐藏 Cc 和 Bcc)来显示或隐藏标题及其 From、To、Cc、Bcc 行。
  • 本地化标题:通过 FieldTextMap 将每个 EmailField 映射为不同的标题,例如将 Subject 和 Attachments 翻译成其他语言。
  • 日期格式:Sent 行遵循运行转换的机器的文化设置,TimeZoneOffset 设置用于消息日期的 UTC 偏移量。
  • 仅消息输出:当 PDF 只需代表邮件本身时,将 ConvertOwned 设置为 false,附件名称仍会列在标题中以供参考。

请参阅完整的 EmailLoadOptions reference 了解所有选项。

结论

过去需要打开邮件、手动保存附件并检查是否有重复覆盖的工作,现在只需一个 SaveContext 回调和几行代码即可完成。GroupDocs.Conversion for .NET 为每个输出项——邮件本身以及每个附件——提供了永不冲突的名称,并在没有 PDF 路径的情况下保存附件而不是让整个运行失败。相同的三个构建块——ConvertOwner、ConvertOwned 和 SaveContext 回调——可以从单个汇总 PDF 扩展到完整、无冲突的消息及其所有附件的拆分,帮助你从小规模起步,随着收件箱需求的增长逐步构建完整工作流。

准备好自动化您的电子邮件转 PDF 工作流了吗?

其他资源