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

Email-to-PDF 轉換是 GroupDocs.Conversion 在 .NET 上的工作流程,能將 Outlook 訊息及其附件轉換成一個或多個 PDF 檔案,且不會因為某個附件覆寫另一個或某個不支援的檔案導致整個執行失敗。它取代了手動匯出與重新命名的程序,只需幾行程式碼即可知道每個項目的來源以及是否成功轉換。

以前的方式很痛苦

想像一個支援收件匣,每封案件郵件都帶有兩三個附件——這裡有報告, 那裡有螢幕截圖,有時還會出現團隊中沒有人認識的檔案格式。這種情況並不罕見。處理這類案件意味著要開啟訊息,手動儲存每個附件,因為兩個系統都匯出了名為 report.csv 的檔案而必須重新命名,並且還要祈禱檔案集合中沒有你的 PDF 檢視器無法開啟的格式。每週要做五十次,所謂的「快速匯出」就會變成工作中最慢的部分,也是最容易草率處理的環節,而錯誤正是在這時發生。

手動執行不僅浪費時間——也是檔案悄悄遺失的根源。將兩個同名為 report.csv 的附件儲存到同一資料夾而未先重新命名,第二次儲存會覆寫第一次;直到九月的數據找不到才會有人注意。即使只有一個附件的格式沒有人有轉換器,也會讓整個匯出卡住,直到有人決定要怎麼處理它。

手動操作的真正代價:被重新命名且被覆寫的附件不會拋出錯誤——它只是靜默消失,案件檔案看起來完整,直到有人需要其中的資料時才會發現問題。

有更好的方法

GroupDocs.Conversion for .NET 能把這一切縮減為幾行程式碼。無需手動重新命名。其 EmailLoadOptions 類別可控制是只轉換訊息、只轉換附件,或兩者皆轉換,而 SaveContext 回呼則能為每個輸出項目提供足夠資訊,使得兩個同名 report.csv 的附件永不衝突,且沒有 PDF 轉換路徑的附件也不會阻止其餘項目的執行。每次呼叫此回呼都會回報 ItemIndex(從 1 開始的遞增計數)、HierarchyLevel(訊息為 0,附件為 1)以及 SourceFileName(原始檔名),這些資訊足以在不寫額外帳務程式的情況下產生不會衝突的輸出名稱。

在開始之前,您需要:

  • .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-),以及來源檔名。

前後對照

以往(手動) 之後(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 偏移。
  • 僅訊息輸出:將 ConvertOwned 設為 false,當 PDF 只需要代表訊息本身時,仍可在標頭列出附件名稱作為參考。

請參閱完整的 EmailLoadOptions 參考文件 了解所有選項。

結論

過去需要手動開啟訊息、手動儲存附件、再檢查是否有被覆寫的繁瑣流程,現在只要使用 SaveContext 回呼與幾行程式碼即可完成。GroupDocs.Conversion for .NET 為每個輸出項目——訊息與每個附件——賦予永不衝突的名稱,並在沒有 PDF 轉換路徑時保留附件而不是讓整個執行失敗。這三個建構塊——ConvertOwner、ConvertOwned 與 SaveContext 回呼——可從單一摘要 PDF 擴展到完整、避免衝突的訊息與所有附件的分解,讓您可以從小規模開始,隨著收件匣需求成長而逐步擴充工作流程。

準備好自動化您的 Email-to-PDF 工作流程了嗎?

其他資源