在 .NET 中設定 GroupDocs Annotation 授權 – 完整指南

正確設定 set groupdocs annotation license 是解鎖 GroupDocs Annotation .NET 函式庫完整、無浮水印功能的第一步。無論您是建立法律審查平台、電子學習註解工具，或是協作回饋系統，妥善套用授權可確保每項功能如預期運作，且使用者能享有無評估限制的完善體驗。接下來的幾分鐘內，您將看到如何從檔案載入授權、如何防範常見陷阱，以及為何這對生產等級的應用程式至關重要。

快速解答

• 授權檔案的作用是什麼？ 它告訴 GroupDocs.Annotation 引擎以完整功能模式運行，移除浮水印與頁數限制。
• .lic 檔案應該存放在哪裡？ 放在應用程式啟動時可讀取的資料夾，最好位於網站根目錄之外以提升安全性。
• 需要多次呼叫 SetLicense() 嗎？ 不需要 – 在應用程式初始化時呼叫一次即可。
• 可以使用相對路徑嗎？ 可以，但請結合 Path.Combine() 使用，以避免平台特定的問題。
• 如果授權過期會發生什麼事？ 函式庫會回退至評估模式，重新出現浮水印與功能上限。

什麼是 GroupDocs Annotation 授權檔案？

授權檔案 (*.lic) 是一個小型的 XML 文件，內含您的產品金鑰、到期日與使用限制。函式庫在執行時讀取此檔案，並在授權期間啟用完整功能集。由於檔案經由 GroupDocs 簽署，任何竄改都會被偵測，導致函式庫拒絕授權。

為何要正確設定 GroupDocs Annotation 授權？

設定授權可確保函式庫以完整功能模式運作，移除評估限制，並保證在不同環境中的行為一致。它同時保護您的應用程式免於出現意外的浮水印、頁數限制與功能被停用，避免影響使用者體驗與生產環境的合規性。

適當的授權可消除三大生產風險：

1. 浮水印 – 評估模式會在每個註解頁面加上可見的「Powered by GroupDocs」浮水印，顯得不專業。
2. 頁數限制 – 未取得授權時，每份文件僅限 5 頁，對大多數商業情境而言不切實際。
3. 功能限制 – 高階註解類型（例如貼紙註記、PDF 文字標記、以及多頁評論串）在評估模式下被停用，限制使用者互動。

GroupDocs Annotation .NET 授權設定的前置條件

在撰寫任何程式碼之前，請確認以下項目已備妥：

透過 NuGet 安裝函式庫

在 Visual Studio 中開啟 Package Manager Console，然後執行：

Install-Package GroupDocs.Annotation

此指令會取得最新的穩定版，撰寫本文時支援 .NET 6、.NET 5、.NET Core 3.1 與 .NET Framework 4.6.2+。廣泛的相容性確保您能將函式庫整合至幾乎所有現代 .NET 專案。

匯入必要的命名空間

以下命名空間可讓您存取授權 API 以及基本的 I/O 工具：

using GroupDocs.Annotation;
using GroupDocs.Annotation.Config;
using System;
using System.IO;

這些命名空間提供 License 類別、檔案系統輔助工具，以及實作所需的核心 .NET 類型。

如何從檔案設定 GroupDocs Annotation 授權？

License 類別負責載入與驗證 GroupDocs.Annotation 授權檔案。其 SetLicense() 方法會將提供的授權套用至函式庫。請在應用程式啟動時載入一次授權檔案，驗證其是否存在，並在新的 License 物件上呼叫 SetLicense()。此單一呼叫會在整個 AppDomain 中全域註冊授權，使之後的所有 Annotation 操作皆具完整權限。

// Direct answer (40‑70 words):
// Load the license file with `new License()` and call `SetLicense(path)`. 
// This registers the license globally, removes evaluation watermarks, and enables all annotation features. 
// Place the call early in your startup routine (e.g., `Program.cs` or `Startup.cs`) so every component can rely on the licensed state.

步驟 1：驗證授權檔案是否存在

在嘗試載入之前檢查檔案可防止未處理的例外，並讓您有機會記錄清晰的錯誤訊息。

string licensePath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Licenses", "GroupDocs.Annotation.lic");

if (!File.Exists(licensePath))
{
    throw new FileNotFoundException($"GroupDocs Annotation license file not found at {licensePath}");
}

步驟 2：套用授權

確認檔案後，實例化 License 類別並指向該檔案。

var license = new License();
license.SetLicense(licensePath);

此呼叫之後，函式庫在整個程序生命週期內以完整授權模式運作。不再需要其他呼叫。

步驟 3：優雅地處理缺少或無效的授權

如果無法載入授權，應回退至安全狀態——通常記錄問題，並在開發建置中選擇性地繼續以評估模式執行。

try
{
    var license = new License();
    license.SetLicense(licensePath);
}
catch (Exception ex)
{
    // Log the exception and continue in evaluation mode (useful for CI pipelines)
    Console.Error.WriteLine($"License loading failed: {ex.Message}");
}

常見授權設定問題與解決方案

即使實作相當簡單，開發人員仍會遇到一些常見問題。以下列出最常見的症狀及其解決方式。

授權檔案路徑問題

問題 – 即使檔案存在，應用程式仍拋出 FileNotFoundException。
解決方案 – 使用絕對路徑或以 Path.Combine() 建構路徑，以避免 Windows 與 Linux 之間的目錄分隔符不一致。部署至 Azure 或 Docker 時，將授權存放於掛載的磁碟卷目錄，並透過環境變數引用。

權限問題

問題 – 程序缺乏讀取權限，導致 UnauthorizedAccessException。
解決方案 – 為應用程式池身分（例如 IIS AppPool\MyApp）在包含 .lic 檔案的資料夾上授予讀取權限。對於 Linux 容器，將檔案所有者設定為執行使用者（chmod 644）。

無效的授權格式

問題 – 函式庫回報「Invalid license format」。
解決方案 – 從 GroupDocs 入口重新下載授權。請勿手動編輯 XML；任何更改都會破壞數位簽章。

應用程式啟動時機問題

問題 – 當授權在首次註解請求之後才載入時，會出現間歇性失敗。
解決方案 – 將授權程式碼放在最早的初始化點：控制台應用程式的 Program.Main、ASP.NET Core 的 Startup.ConfigureServices，或傳統 ASP.NET 的 Application_Start。

授權管理的最佳實踐

安全的授權儲存

絕不要將授權金鑰直接嵌入原始碼或提交至版本控制。應將 .lic 檔案存放於受保護的資料夾，並透過設定檔引用：

// appsettings.json
{
  "GroupDocs": {
    "LicensePath": "C:\\SecureLicenses\\GroupDocs.Annotation.lic"
  }
}

在啟動時從設定檔讀取路徑，並傳遞給 SetLicense()。

依環境的授權策略

此做法確保開發人員可在不影響正式環境授權上限的情況下進行測試。

設定後的授權驗證

License.IsValid 屬性在載入的授權目前有效時會回傳 true。呼叫 SetLicense() 後，您可以透過檢查 License.IsValid 屬性（在較新 SDK 版本中提供）來驗證授權是否已啟用。此額外步驟對自動健康檢查很有幫助。

if (!license.IsValid)
{
    // Trigger alert or fallback logic
    Console.WriteLine("License validation failed – running in evaluation mode.");
}

替代授權方式

雖然基於檔案的授權最為常見，GroupDocs Annotation 亦提供以下方式：

• 基於串流的授權 – 從嵌入資源或網路串流載入授權，適用於檔案系統唯讀的雲端原生部署。
• 計量授權 – 按使用付費模式，透過 API 呼叫追蹤使用量，適合需求不可預測的 SaaS 產品。

效能考量

授權設定時機

呼叫 SetLicense() 會產生一次 I/O 操作與加密簽章驗證。於啟動時執行此呼叫，會在一般伺服器上增加 不到 15 ms 的開銷，與註解處理的成本相比可忽略不計。

記憶體佔用

License 物件相當輕量；成功註冊後，函式庫不會保留對檔案的參考。這表示您可以安全地釋放用於載入授權的任何串流，而不會影響執行時效能。

常見問答

Q: 開發是否需要授權？
A: 不需要，臨時或評估授權即可用於本機開發，但會看到浮水印與頁數限制。

Q: 可以在多台伺服器間共用同一授權檔案嗎？
A: 可以，只要您的授權協議允許多實例使用；請檢查合約或聯絡 GroupDocs 支援。

Q: GroupDocs.Annotation 支援哪些 .NET 版本？
A: 完全支援 .NET Framework 4.6.2+、.NET Core 3.1+、.NET 5+ 與 .NET 6+。

Q: 如何在不中斷服務的情況下更新授權？
A: 替換磁碟上的 .lic 檔案並重新啟動應用程式；新授權會在下次啟動時被載入。

Q: 有沒有辦法以程式方式檢查授權剩餘有效期？
A: 有，License 類別提供 Expiration 與 IsValid 屬性，可在執行時查詢。

結論

透過本指南，您現在已掌握在任何 .NET 應用程式中從檔案設定 groupdocs annotation 授權的完整、可投入生產的做法。主要要點如下：

• 在啟動時使用絕對且已驗證的路徑載入授權一次。
• 以清晰的錯誤處理防範檔案缺失、權限問題與格式無效。
• 安全儲存授權，並將其排除於版本控制之外。
• 載入後驗證授權，以確保未意外以評估模式執行。

實作這些步驟將消除浮水印、解鎖所有註解功能，並讓您確信應用程式在開發、測試與正式環境中皆能一致運作。

Last Updated: 2026-06-21
Tested With: GroupDocs.Annotation 23.12 for .NET
Author: GroupDocs

using System;
using System.IO;

if (File.Exists(Constants.LicensePath))
{
    // License file found - proceed with setup
}

if (File.Exists(Constants.LicensePath))
{
    License license = new License();
    license.SetLicense(Constants.LicensePath);
    Console.WriteLine("License set successfully.");
}

else
{
    Console.WriteLine("\nWe do not ship any license with this example. " +
                      "\nVisit the GroupDocs site to obtain either a temporary or permanent license. " +
                      "\nLearn more about licensing at https://purchase.groupdocs.com/faqs/licensing. " +
                      "\nLearn how to request a temporary license at https://purchase.groupdocs.com/temporary-license.");
}

string licensePath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "licenses", "GroupDocs.Annotation.lic");

// Good approach - using configuration
string licensePath = ConfigurationManager.AppSettings["GroupDocsLicensePath"];

// Avoid - hardcoded paths
// string licensePath = @"C:\MyApp\License.lic"; // Don't do this

public bool IsLicenseValid()
{
    try
    {
        License license = new License();
        license.SetLicense(Constants.LicensePath);
        return true;
    }
    catch (Exception ex)
    {
        // Log the exception for debugging
        Console.WriteLine($"License validation failed: {ex.Message}");
        return false;
    }
}

相關教學

• 從串流設定授權 .NET - 完整 GroupDocs.Annotation 教學
• GroupDocs.Annotation 授權 .NET - 完整設定與配置
• GroupDocs Annotation 計量授權教學 - 完整 .NET 設定指南