如何使用 GroupDocs 從 Azure Blob 載入文件 (.NET)

介紹

如果您需要從 Azure Blob Storage 讀取檔案並在不將檔案拉到本機磁碟的情況下進行註解，您來對地方了。在本教學中，我們將示範 如何使用 GroupDocs 直接從 Azure 載入 PDF（或任何支援的格式），加入註解，並將結果儲存回雲端。完成後，您將擁有一段可在 .NET 6+ 環境下使用的生產等級程式碼，遵循安全最佳實踐，且可擴展至每日處理數千份文件。

快速回答

  • 哪個函式庫負責註解？ GroupDocs.Annotation for .NET。
  • 可以串流檔案嗎？ 可以 – SDK 直接使用 MemoryStream。
  • 需要本機副本嗎？ 不需要，整個流程皆在記憶體中完成。
  • 哪種 Azure 層級最適合？ 活躍編輯使用 Hot storage；歸檔則使用 Cool。
  • 支援 async 嗎？ 當然 – Azure SDK 提供可直接套用的非同步方法。

Azure Blob Storage 在文件處理上的優勢

Azure Blob Storage 為大規模、耐用且安全的物件儲存而設計，提供以下特點：

  • 可擴展性： 支援 數億 個物件與 PB 級容量。
  • 成本效益： 三種儲存層級（Hot、Cool、Archive）讓您僅為實際存取模式付費。
  • 全球覆蓋： 超過 60 個區域可將資料放置於靠近使用者的地方，降低延遲。
  • 安全性： 靜態自動 AES‑256 加密與傳輸層 TLS 1.2，加上細緻的 RBAC 控制。
  • 生態系整合： 原生 .NET SDK、Event Grid 觸發器，與 Azure Functions 無縫連接。

將上述與 GroupDocs.Annotation 結合，即可得到一條雲端原生的管線，能為 PDF、Word、PowerPoint 等文件加入註解，且永不寫入暫存檔至磁碟。

前置條件

開始之前，請確保您具備以下項目：

  1. .NET 6+ 執行環境 – 最新 LTS 版確保相容最新的 GroupDocs 版本。
  2. GroupDocs.Annotation for .NET – 透過 NuGet 安裝 (Install-Package GroupDocs.Annotation)。
  3. Azure Storage SDK – 從 NuGet 安裝 Azure.Storage.Blobs。
  4. Azure Storage 帳號 – 具備至少 Blob Data Reader 與 Blob Data Contributor 權限的連接字串。
  5. 已上傳至您控制的容器中的 PDF（或支援的文件）。

專業提示： 在原型開發階段可使用 Azure 免費層（5 GB Blob 儲存），之後可在不更改程式碼的情況下升級。

匯入命名空間

using 陳述式讓您在整個教學中取得所需的類別。

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using GroupDocs.Annotation;
using GroupDocs.Annotation.Options;
using System.IO;

重要： 必須先將 Azure Storage 用戶端函式庫加入專案，才能引用其命名空間。

GroupDocs.Annotation for .NET 概觀

GroupDocs.Annotation 是一套 .NET 函式庫，支援對超過 50 種文件格式（包括 PDF、DOCX、PPTX 以及影像）進行 讀寫註解，且不需在伺服器上安裝 Microsoft Office 或 Adobe Acrobat。

從 Azure Blob Storage 載入文件

MemoryStream 是 .NET 類別，提供以記憶體為後端的串流，允許快速的記憶體內讀寫操作。
Annotation 是 GroupDocs.Annotation 函式庫的核心類別，用於載入、修改與儲存文件註解。

直接將文件載入 MemoryStream，再交給 Annotation API。此方式可消除磁碟 I/O，讓操作更快且更安全。

步驟實作

步驟 1：設定輸出路徑

定義註解後檔案的儲存位置。您可以在同一容器內加上副檔名，或寫入不同容器以實現版本管理。

最佳實踐： 使用 Path.Combine（或 System.IO.Path）組合檔案路徑，以兼容 Windows、Linux 與 macOS。

步驟 2：下載文件

將 Blob 以 MemoryStream 形式取得。using 陳述式確保串流正確釋放，避免記憶體泄漏。

效能說明： 串流可避免在處理大型 PDF 時一次載入整個檔案；SDK 會按需讀取。

步驟 3：註解文件

建立 Annotation 實例，加入文字註解，然後將結果儲存至新串流。

小技巧： GroupDocs 提供超過 30 種註解類型（如高亮、底線、便利貼等），可依 UI 需求選擇。

步驟 4：上傳註解後檔案

將註解後的串流推回 Azure。您可以覆寫原始 Blob，或儲存為新版本。

版本化建議： 在檔名加入時間戳記 (yyyyMMdd_HHmmss) 以保留變更歷史。

從 Azure Blob Storage 下載檔案

以下輔助方法封裝下載邏輯，回傳已重設位置的 MemoryStream，即可供 GroupDocs 使用。

取得 Blob

定位要處理的容器與特定 Blob。

下載 Blob 內容

將 Blob 的位元組複製至 MemoryStream。將位置重設為 0 至關重要，因為註解函式庫會從串流起始讀取。

取得 Azure Blob Storage 容器

此方法負責建立與 Azure 的連線，並確保容器在任何讀寫操作前已存在。

初始化儲存認證

千萬不要在原始碼中硬編碼帳號金鑰。請使用 Azure Key Vault、環境變數 或 受控身分。

建立 Blob Service 客戶端

使用連接字串實例化 BlobServiceClient。

取得容器參考

取得目標容器的參考（例如 documents）。

若不存在則建立容器

呼叫 CreateIfNotExists 可保證在開發與測試期間容器已存在，避免執行時例外。

常見實作挑戰

記憶體管理

  • 大型 PDF（>200 MB） 可能對 GC 造成壓力。可考慮分頁處理或使用 Annotation 的串流模式。
  • 請務必將串流包在 using 區塊中，以即時釋放原生資源。

網路延遲

  • 將應用程式部署至與儲存帳號相同的 Azure 區域。
  • 為讀取密集的情境啟用 Azure CDN，將 Blob 快取於邊緣位置。

驗證與授權

  • 於正式環境建議使用 Azure AD 搭配 受控身分。
  • 臨時、細緻的存取可使用 共享存取簽章 (SAS)。

效能最佳化技巧

  1. Async/Await： 使用 BlobClient.DownloadAsync 與 UploadAsync 讓執行緒池保持回應。
  2. 重試策略： 利用 Azure SDK 內建的指數退避機制，應對瞬間失敗。
  3. Blob 命名慣例： 以租戶 ID 或日期作為前綴 (tenant1/2024/09/invoice_12345.pdf) 以提升列舉效率。
  4. CDN 整合： 對於讀取頻繁但變更少的文件，CDN 可大幅降低延遲。
  5. 批次操作： 處理多筆檔案時，使用 BlobBatchClient 一次性上傳，可減少往返次數。

安全最佳實踐

  • 靜態加密： Azure 會自動以 AES‑256 加密 Blob，您亦可加入客戶管理金鑰以加強控制。
  • HTTPS‑Only： 強制所有儲存端點使用 TLS 1.2 以上。
  • RBAC 與 IAM： 為服務主體指派最小權限角色 (Storage Blob Data Reader/Contributor)。
  • 稽核日誌： 啟用 Azure Monitor 與 Storage Analytics 以追蹤讀寫操作。
  • 金鑰輪替： 每季輪替儲存帳號金鑰，並將金鑰安全存放於 Azure Key Vault。

常見問題排除

「找不到容器」錯誤

確認容器名稱符合 Azure 命名規則（全小寫、數字、連字號），且使用的帳號金鑰屬於正確的儲存帳號。

驗證失敗

檢查連接字串是否對應正確環境（開發 vs. 正式），以及所使用的身分是否具備所需 RBAC 角色。

記憶體不足例外

若遭遇記憶體限制，可改用 Annotation 的 LoadOptions 進行 分頁載入，或將 Blob 暫寫至高效能 SSD 上的臨時檔案。

效能緩慢

  • 確認對於活躍編輯使用 Hot 層級。
  • 使用 BlobClient.OpenReadAsync 搭配適當的 BufferSize 啟用平行下載。
  • 考慮使用 Azure Front Door 進行全球負載平衡。

進階使用情境

批次處理

遍歷容器內的 Blob，使用 Parallel.ForEachAsync 並行註解，最後寫回結果。此模式在一般 VM 上即可每分鐘處理 數百份文件。

文件版本管理

為每個註解後的版本加上時間戳記副檔名。Azure Blob 的 軟刪除 功能可防止意外覆寫。

協作註解

結合 GroupDocs 與 SignalR，即時廣播註解變更。可在同一容器內放置鎖定檔（例如 document.lock）以避免寫入衝突。

Azure Functions 整合

建立 Blob Trigger 函式，於新檔案上傳至容器時觸發。函式串流檔案、加入預設的「已審核」印章，並儲存至 processed 資料夾。

結論

使用 GroupDocs.Annotation for .NET 從 Azure Blob Storage 載入並註解文件，提供雲端原生、可擴展且安全的解決方案，適用於任何以文件為中心的應用程式。透過檔案串流、遵循 Azure 安全模型，以及利用豐富的註解 API，您可以打造從簡易 PDF 檢視器到完整協作編輯平台的各種應用。

請記得：

  • 將憑證移出原始碼。
  • 使用非同步模式提升回應性。
  • 於正式環境監控記憶體與網路指標。
  • 套用安全檢查清單以保護敏感資料。

遵循上述作法，即可交付一條穩健、企業級的文件處理管線。

常見問答

Q: GroupDocs.Annotation for .NET 是否支援所有文件格式？
A: 是的，支援 50+ 種格式，包括 PDF、DOCX、PPTX、XLSX 以及常見影像類型。部分進階註解工具為特定格式專屬，請參考官方矩陣取得詳細資訊。

Q: 我可以自訂註解的外觀嗎？
A: 當然可以。您可以透過 AnnotationOptions 物件設定字型大小、顏色、不透明度，甚至嵌入自訂圖示。

Q: GroupDocs 是否內建協作註解功能？
A: 函式庫提供具併發安全性的 API，結合 Azure Blob Storage 後，您可自行實作即時協作，處理版本衝突並使用 SignalR 更新 UI。

Q: 支援哪些 .NET 執行環境？
A: GroupDocs.Annotation for .NET 相容 .NET Framework 4.6.2+、.NET Core 3.1+、.NET 5、.NET 6、.NET 7。

Q: 函式庫如何處理大型檔案？
A: 它採用串流方式，允許在標準 VM 上以 200 MB 以下 記憶體註解 500+ 頁 的 PDF。您亦可啟用 LoadOptions 以按需處理頁面。

Q: 若 Azure 網路呼叫偶爾失敗，該怎麼辦？
A: 實作 Azure SDK 內建的重試政策或自訂指數退避策略。亦可考慮使用斷路器模式，以防止連鎖失敗。

Q: GroupDocs 使用者是否提供技術支援？
A: 有的，GroupDocs 提供專屬支援票證、社群論壇，並有完整文件與每個主要情境的程式碼範例。

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

using GroupDocs.Annotation.Models;
using GroupDocs.Annotation.Models.AnnotationModels;
using Microsoft.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.Auth;
using Microsoft.WindowsAzure.Storage.Blob;
using System;
using System.IO;

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

using (Annotator annotator = new Annotator(DownloadFile(blobName)))
{
    // Annotation Logic
    annotator.Save(outputPath);
}

CloudBlobContainer container = GetContainer();
CloudBlob blob = container.GetBlobReference(blobName);

MemoryStream memoryStream = new MemoryStream();
blob.DownloadToStream(memoryStream);
memoryStream.Position = 0;
return memoryStream;

string accountName = "***";
string accountKey = "***";
string endpoint = $"https://{accountName}.blob.core.windows.net/";

CloudStorageAccount cloudStorageAccount = new CloudStorageAccount(storageCredentials, new Uri(endpoint), null, null, null);
CloudBlobClient cloudBlobClient = cloudStorageAccount.CreateCloudBlobClient();

CloudBlobContainer container = cloudBlobClient.GetContainerReference(containerName);

container.CreateIfNotExists();

相關教學