從文件檢索註解 – 載入 .NET 版本

介紹

如果您需要快速且可靠地 從文件檢索註解 版本，您來對地方了。無論您是構建法律審查門戶、協作設計系統，或是稽核追蹤儀表板，處理多個註解修訂都是核心需求。GroupDocs.Annotation for .NET 為您提供簡潔的 API，以載入任意版本的註解——無論是第一稿、最新審查，或任何中間檢查點。

在本教學中，我們將逐步說明完整流程，從安裝函式庫到儲存特定版本的文件，並提供實務技巧，讓您避免常見的陷阱。

快速解答

  • 「從文件檢索註解」是什麼意思？ 這表示僅載入附加於檔案特定修訂的註解資料。
  • 哪個函式庫支援此功能？ GroupDocs.Annotation for .NET，支援超過 30 種檔案格式。
  • 我需要授權嗎？ 免費試用可用於測試；正式環境需購買商業授權。
  • 我只能載入第一版或最後一版嗎？ 可以——使用 Version 選項，值為 "FIRST" 或 "LAST"。
  • 大型 PDF 安全嗎？ 可以——載入單一版本時，500 頁 PDF 的記憶體使用量仍低於 200 MB。

何時使用此功能

在深入程式碼之前，請先考慮載入特定註解版本的關鍵情境：

  • 文件審查工作流程 – 比較不同審查週期的回饋意見。
  • 合規與稽核 – 為監管機構保留每套註解的不可變更紀錄。
  • 協作編輯 – 讓使用者在「草稿」與「最終」註解層之間切換。
  • 回滾情境 – 若後續編輯產生錯誤，可回復至已知良好的註解狀態。

前置條件

  1. 安裝 GroupDocs.Annotation for .NET
    從 releases page 下載套件。您也可以前往主發行網站 here。依照您的 IDE 參考安裝指南。

    專業提示：如果您偏好使用 NuGet，請在套件管理員主控台執行以下指令：

Install-Package GroupDocs.Annotation


2. **取得含有註解的文件**  
   使用已包含多個註解版本的 PDF、DOCX 或任何 30+ 支援格式。若是首次測試，可手動建立幾個版本。

## 匯入命名空間

`GroupDocs.Annotation` 命名空間提供核心物件與載入選項的存取。  
`Annotator` 類別是載入與操作文件註解的主要入口。

```csharp
using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using GroupDocs.Annotation.Models;
using GroupDocs.Annotation.Models.AnnotationModels;
using GroupDocs.Annotation.Options;

定義說明：Annotator 是主要類別，用於開啟檔案、套用載入選項，並提供取得或儲存註解的方法。

步驟實作說明

以下是載入特定註解版本的完整步驟順序。

步驟 1：定義輸出路徑

string outputPath = Path.Combine("Your Document Directory", "result" + Path.GetExtension("input.pdf"));

我們使用 Path.Combine 來建立跨平台的檔案路徑，並使用 Path.GetExtension 保留原始副檔名。

步驟 2：指定載入選項

LoadOptions loadOptions = new LoadOptions { Version = "FIRST" };

LoadOptions 物件設定文件及其註解的載入方式，包含版本選擇。Version 屬性決定載入哪一套註解。可接受的值有：

  • "FIRST" – 最早的註解版本。
  • "LAST" – 最新的註解版本。
  • 任意您在文件中繼存的自訂版本識別碼。

步驟 3：初始化 Annotator

using (Annotator annotator = new Annotator("annotated_with_versions.pdf", loadOptions))

using 陳述式確保 Annotator 實例在使用完畢後被釋放，釋放檔案句柄與非受控資源。

步驟 4：取得註解

var annotations = annotator.Get();

Get() 會回傳載入版本的註解物件集合。您可以依需求遍歷、修改或匯出它們。

步驟 5：儲存含註解的文件

annotator.Save(outputPath);

Save() 將目前的註解寫回檔案，並可選擇保留原始格式。

步驟 6：顯示確認訊息

Console.WriteLine($"\nDocument saved successfully.\nCheck output in {outputPath}.");

提供使用者回饋（例如主控台輸出、UI toast）可提升整體使用體驗。

如何載入特定註解版本？

使用 new Annotator(filePath, loadOptions) 載入文件，並將 loadOptions.Version 設為目標識別碼，接著呼叫 annotator.Get() 取得該版本的註解。此單行做法可在不觸及其他修訂的情況下，僅取得所需版本。您亦可使用 Version.First 或 Version.Last 等常數指定版本，以確保精確取得預期的註解集合。

Annotator 類別是什麼？

Annotator 是 GroupDocs.Annotation 的入口類別，負責開啟檔案、套用 LoadOptions，並提供 Get()、Save()、GetVersionsList() 等方法。所有註解操作皆透過此物件執行。它管理文件的生命週期、處理資源清理，並提供執行緒安全的註解資料存取，適用於桌面與 Web 應用程式。

常見問題與除錯

找不到版本錯誤

問題：當請求的版本識別碼不存在時拋出例外。
解決方案：先呼叫 annotator.GetVersionsList() 列出可用版本，然後選取有效的識別碼。

註解集合為空

問題：Get() 回傳空清單。
解決方案：確認所選版本確實包含註解，且來源檔案在先前儲存時未被移除註解中繼資料。

大型文件的效能問題

問題：載入 500 頁、含數千註解的 PDF 需要數秒。
解決方案：

  • 依註解類型過濾 (LoadOptions.AnnotationTypes)。
  • 使用 annotator.Get(pageIndex, pageSize) 實作分頁。
  • 若工作流程允許，可將常用版本快取於記憶體中。

檔案路徑問題

問題：「找不到檔案」或存取被拒錯誤。
解決方案：

  • 開發期間使用絕對路徑。
  • 確認應用程式的服務帳號對來源與目標資料夾均具讀寫權限。
  • 若輸出目錄可能不存在，請事先建立。

效能考量

  • 記憶體占用：載入單一版本時，對於一般 500 頁 PDF，記憶體使用量維持在 200 MB 以下。
  • I/O 最佳化：使用共享的 Annotator 池批次處理文件，以降低檔案開啟開銷。
  • 網路延遲：若檔案位於雲端儲存，請將呼叫包裹於重試機制，並考慮先將檔案串流至本機暫存資料夾再載入。

最佳實踐

版本命名慣例

採用清晰的命名規則，例如 v1.0、v1.1-review 或 ISO 日期戳記（2025-01-02），讓最終使用者能直觀選擇版本。

錯誤處理

將所有註解程式碼包裹於 try‑catch 區塊，並記錄詳細錯誤資訊。

try 
{
    using (Annotator annotator = new Annotator(documentPath, loadOptions))
    {
        var annotations = annotator.Get();
        // Process annotations
    }
}
catch (Exception ex)
{
    // Log error and provide user-friendly message
    Console.WriteLine($"Error loading annotations: {ex.Message}");
}

資源管理

由於 Annotator 實作 IDisposable，請始終使用 using 陳述式或明確呼叫 Dispose()，以即時釋放檔案句柄。

與現有工作流程的整合

  • 文件管理系統 – 提供接受版本 ID 並回傳對應註解文件的 API 端點。
  • RESTful 服務 – 將註解集合以 JSON 形式回傳給前端渲染。
  • 背景工作 – 排程夜間作業，抽取每個版本的註解以供合規報告。
  • 使用者介面 – 使用 annotator.GetVersionsList() 填充下拉選單，讓使用者選擇欲檢視的版本。

結論

您現在已掌握使用 GroupDocs.Annotation for .NET 從文件檢索註解 版本的完整、可投入生產的模式。請記得：

  1. 在 LoadOptions 中設定正確的 Version。
  2. 正確釋放 Annotator。
  3. 使用過濾或分頁方式處理大型檔案。

透過上述步驟，您即可打造穩健、具版本感知的註解功能，提升協作、稽核可追溯性與無縫回滾能力。

最後更新： 2026-07-30
測試環境： GroupDocs.Annotation 2.3.0 for .NET
作者： GroupDocs

常見問題

Q: 我可以使用 GroupDocs.Annotation for .NET 為各種格式的文件加註嗎？
A: 可以，函式庫支援超過 30 種格式，包括 PDF、DOCX、PPTX、XLSX 以及多種影像類型。

Q: GroupDocs.Annotation for .NET 有提供免費試用嗎？
A: 有，您可從 here 下載完整功能的試用版。

Q: 我在哪裡可以找到 GroupDocs.Annotation for .NET 的官方文件？
A: 完整文件可在 here 取得。

Q: 我如何取得開發用的臨時授權？
A: 可從 this link 申請臨時金鑰。

Q: 我可以在哪裡提問技術問題或取得支援？
A: 社群論壇是最佳去處——請前往 here。

Q: 我如何列出文件中所有註解版本？
A: 使用 annotator.GetVersionsList()；它會回傳檔案中儲存的所有版本識別碼。

Q: 載入特定版本會影響其他版本嗎？
A: 不會——載入僅為唯讀。除非您明確修改並儲存，否則其他版本保持不變。

相關教學