💡 完整的可運作範例可在 GitHub 上取得: one-line-document-merge-and-split-dotnet

後勤部門文件工作實際所在位置

財務後勤部門會在上個月的對帳單 PDF 上釘上一張封面頁以結算本月。合約團隊在將簽署的修訂案加入原始協議後再歸檔。業務營運助理會從六十張投影片的簡報中抽出兩張,因為只有一位利害關係人需要價格頁面。紀錄文員會在檔案離開大樓前移除一頁本不該寄出的頁面。

這些都不是合併專案。每次執行工作時,都是單一檔案、單一操作,且每次都以相同方式完成,通常由對學習通用文件 API 完全沒興趣的人執行。

GroupDocs.Merger.LowCode 是一個 .NET 套件,將此類工作(合併、分割或移除頁面)轉換為一次建構子呼叫,與永遠不需要的通用 Merger 類別區隔開來。其七個產品皆在建構子中以 C# 接收來源與選項,僅在呼叫 Save 時執行,無論是 PDF、Word 文件或 PowerPoint 簡報,都遵循相同的「建構子 → Save」模式。

為何通用解決方案在此無法奏效

面對這類工作時,團隊通常在尋找專用套件之前會嘗試以下三種做法:

  • 手動使用桌面編輯器:對單一文件而言尚可接受,但無法排程,且沒有人會批准在凌晨 2 點執行的手動步驟。
  • 針對原始檔案 API 撰寫一次性腳本:能用到下一個輸入格式出現之前,但腳本最終會演變成原本想避免的通用客戶端。
  • 為單次呼叫使用完整的 Merger 類別:雖然正確,卻會帶來比單一操作所需更廣的 API 表面。

GroupDocs.Merger.LowCode 正是為了解決最後這個缺口:每次操作只需一次呼叫,無需先學習其他東西。


解決方案:GroupDocs.Merger.LowCode 用於後勤管線

GroupDocs.Merger.LowCode 將七個單一功能的產品封裝在「建構子 → Save」的形態中。JoinPdf 與 JoinDocx 可將文件附加到另一份文件;JoinPptx 亦同理於簡報;SplitPdf、SplitDocx 與 SplitPptx 可將選取的頁面或投影片分割成各自的檔案;RemovePagesPdf 可在不觸碰來源檔的情況下移除頁面。七個產品皆接受路徑或串流作為來源,並在寫入前檢查來源及所有提供的檔案是否符合其格式,確保管線永遠不必猜測輸出錯誤的原因。

若要跟隨以下實作範例,您需要:

  • .NET 6.0 或更新版本(此範例的專案目標為 net8.0)
  • 獨立的 GroupDocs.Merger.LowCode NuGet 套件
  • 一個暫時授權,若您想在不受評估限制的情況下查看輸出
dotnet add package GroupDocs.Merger.LowCode

此套件在 NuGet 上與主要的 GroupDocs.Merger 程式庫分開發布。


逐步實作 Reporting-Pack 工作

以下說明七個產品共同遵循的形態,以將封面頁附加至每月 PDF 的合併為例說明。

步驟 1:將產品指向來源

JoinPdf 的建構子接受來源文件、所有要附加的檔案,以及一個 JoinOptions 實例;此時尚未執行任何動作。

var join = new JoinPdf("report.pdf", new[] { "appendix.pdf" }, new JoinOptions());

步驟 2:決定結果的輸出位置

Save(outputPath) 才是真正提交工作的地方。相對路徑會以執行程序的工作目錄為基礎解析,且 Save 會在輸出資料夾不存在時自動建立,因此每次寫入新月份資料夾的管線不需要額外的建立步驟。

string outputPath = "output/monthly/report-with-appendix.pdf";

為何這對無人值守工作很重要:

  • 可控的路徑:請從設定或工作參數組合輸出路徑,絕不要直接使用未驗證的輸入;Save 會在路徑為 null 或空字串時拋出 ArgumentNullException。
  • 它會自行建立資料夾:排程工作每次寫入新目的地時,不必自行加入「確保資料夾存在」的步驟。

步驟 3:執行並取得回傳結果

呼叫 Save 會立即執行合併,沒有「建構 → 執行」的分離步驟。

join.Save(outputPath);
var sizeInBytes = new FileInfo(outputPath).Length;

在我們使用範例檔案執行時,該呼叫將 2 頁的 report.pdf 與 2 頁的 appendix.pdf 合併為 4 頁、257987 位元組的 report-with-appendix.pdf。

步驟 4:將結果回饋至管線

Save 後立即讀取的檔案大小通常就是排程器在標記工作完成前,或在與最小尺寸比較以判斷輸出是否可信時所需的全部資訊。

if (sizeInBytes == 0)
{
    throw new InvalidOperationException("Join produced an empty file.");
}

GroupDocs.Merger.LowCode 能接受串流而非檔案路徑嗎?

可以,僅在輸入端支援。七個產品皆可在建構子中以串流取代檔案路徑,這在輸入來自 Blob 儲存或佇列而非本機磁碟時相當有用。Save 仍會將結果寫入指定的路徑字串;若要串流輸出本身,仍須使用完整的 Merger 類別。


真實工作流程:在檔案進入歸檔前先拒絕不合格檔案

合約團隊在將修訂案附加至已簽署的協議時,絕不能接受任何進入收件匣的檔案;若把 .docx 修訂案錯放在 PDF 合併旁,將導致破損的歸檔項目。JoinPdf 會在寫入前檢查來源與所有附加檔案是否符合 PDF 格式,若不符合即拋出 FileTypeNotSupportedException。

try
{
    new JoinPdf("report.pdf", new[] { "contract.docx" }, new JoinOptions())
        .Save("output/mixed.pdf");
}
catch (FileTypeNotSupportedException exception)
{
    Console.WriteLine(exception.Message);
}

在範例執行中,路徑是從 resources 資料夾組合而來,訊息為:Input format does not match the expected format 'PDF'; the joined file 'resources\contract.docx' is 'Microsoft Word Open XML Document (.docx)'.

當例外被捕獲時,上述工作不會產生 output/mixed.pdf,因此合約管線可以直接將此訊息送入既有的警示或工單佇列,而不必等到數天後才發現歸檔錯誤。


其他適用此模式的後勤情境

只要上述合併範例可正常運作,同樣的「建構子 → Save」形態即可支援後勤部門排程執行的多項工作:

  • 在文件離開大樓前裁剪頁面:RemovePagesPdf 會移除指定頁面並寫入新檔案,且不觸碰來源檔,讓原始檔仍可供稽核使用。於我們的測試中,從 report.pdf 移除第 2 頁產生了 1 頁、86647 位元組的 report-without-page-2.pdf,而 report.pdf 本身保持不變。
  • 為單一利害關係人分割簡報:SplitPptx 會將要求的投影片抽出成各自的檔案,檔名依輸出模式中的 {0} 代碼命名,若未使用代碼則以附加的部份編號命名,與 SplitPdf 分割 PDF 頁面的命名規則相同。
  • 合併 Word 文件而非 PDF:JoinDocx 完全遵循與 JoinPdf 相同的建構子 → Save 形態,將附加文件放在來源文件的最後一頁之後。

若未取得授權,以上所有工作皆會在評估模式下執行。我們在未授權的測試中,合併後的 PDF 與 Word 輸出皆被裁減至 3 頁,雖然仍產生了全部六個範例檔案;請在正式環境的無人值守執行前,以 License.Set 設定授權以移除評估限制。


在您的後勤管線中快速上手

您已擁有一套端對端的低程式碼文件合併模式,且每次呼叫都會執行格式檢查。接下來可以這樣進一步:

  • 查看完整全貌:伴隨的使用案例指南 逐步說明範例的六項操作,並提供完整 FAQ。
  • 工作量增長時深入探索:完整的 GroupDocs.Merger API 能涵蓋超出此模式的需求,適用於管線超出單一操作時。
  • 瀏覽程式碼:在GitHub 上的完整範例 中可找到本文使用的所有輸入檔案。
  • 安裝套件:請參考安裝說明頁面,了解獨立套件及其支援的目標框架。
  • 移除評估限制:在正式環境執行前,先取得暫時授權。
  • 問題諮詢:支援論壇 是團隊回應實作問題的所在。

資源