Cài đặt giấy phép

Nếu không có giấy phép, Doconut vẫn hiển thị tài liệu — mỗi trang chỉ có một dấu nước đánh giá. Trang này trình bày bốn cách cung cấp giấy phép trong Global.asax, nơi Doconut tìm kiếm khi bạn không cung cấp gì, và những gì xảy ra khi giấy phép của một plugin bị thiếu.

Bốn cách cung cấp giấy phép

Có ba nguồn rõ ràng trên DoconutOptions — một đường dẫn tệp, một luồng, hoặc nội dung thô — cộng với việc tự động khám phá khi không có gì được đặt. Tất cả chúng được đọc một lần, trong DoconutHost.Initialize. Khi có hơn một nguồn được đặt, thứ tự ưu tiên là chính xác:

LicenseStream thắng LicenseContent thắng LicensePath thắng tự động khám phá.

Theo đường dẫn

Cung cấp cho LicensePath một đường dẫn đầy đủ. Đường dẫn tương đối được giải quyết dựa trên thư mục hiện tại của tiến trình, và dưới IIS thì đó là thư mục của tiến trình worker, không phải site của bạn. HostingEnvironment.MapPath chuyển một đường dẫn tương đối với site thành một đường dẫn đầy đủ:

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
});

Nếu tệp không tồn tại, Doconut không ném lỗi và không quay lại tự động khám phá: nó không tải bất kỳ giấy phép nào, và trình xem sẽ có dấu nước. Các tệp giấy phép per‑plugin trong cùng thư mục (Doconut.Viewer.<Capability>.lic) được đọc cùng với nó, vì vậy LicensePath và AddPlugin<...>() hoạt động cùng nhau khi giấy phép plugin nằm cạnh giấy phép cơ bản.

Theo luồng

LicenseStream được đọc một lần, khi khởi động — hữu ích khi giấy phép đến từ một tài nguyên nhúng hoặc kho bí mật thay vì một tệp trên đĩa.

// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
Doconut.DoconutHost.Initialize(options =>
{
    options.LicenseStream = licenseStream;
});

Theo nội dung

LicenseContent nhận trực tiếp văn bản giấy phép — từ biến môi trường, cơ sở dữ liệu, hoặc kho bí mật — vì vậy không cần triển khai tệp giấy phép cùng site.

// License XML from a database, an environment variable or a secret store -
// no file on disk. Beaten only by LicenseStream.
Doconut.DoconutHost.Initialize(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Tự động khám phá

Không đặt bất kỳ ba tùy chọn nào, và Doconut sẽ tự tìm kiếm giấy phép:

// Configure nothing, and Doconut searches for the license itself, in this order:
//   1. {CurrentDirectory}\wwwroot
//   2. {AppContext.BaseDirectory}\wwwroot   (under IIS: the site's root folder)
// It looks for Doconut.lic first, then Doconut.Viewer.lic, plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
Doconut.DoconutHost.Initialize();

Hai thư mục, theo thứ tự, và các tệp được tìm kiếm:

1. {CurrentDirectory}\wwwroot
2. {AppContext.BaseDirectory}\wwwroot

In each folder:
  Doconut.lic                        — if found, this is the only file read
  Doconut.Viewer.lic                 — base viewer license
  Doconut.Viewer.<Capability>.lic    — per-plugin licenses, read only next to Doconut.Viewer.lic

Dưới IIS và IIS Express, AppContext.BaseDirectory là thư mục gốc của site — thư mục chứa Web.config — không phải thư mục bin của nó. Vì vậy giấy phép phải nằm trong wwwroot dưới thư mục gốc của site:

MySite\
  Web.config
  Global.asax
  bin\
  wwwroot\
    Doconut.Viewer.lic
    Doconut.Viewer.Converter.lic

Trong dự án, giữ các tệp wwwroot\*.lic bên cạnh Web.config và triển khai thư mục cùng site. Không cần bước build nào để sao chép chúng. Một tệp .lic ở bất kỳ nơi nào khác — trong bin\, cạnh Web.config, hoặc trong một thư mục con của wwwroot — sẽ không bao giờ được đọc.

Giữ các tệp .lic ra khỏi hệ thống kiểm soát nguồn. Triển khai chúng cùng site, hoặc cung cấp giấy phép qua LicenseContent hoặc LicenseStream từ kho bí mật của bạn.

Điều gì xảy ra khi không có giấy phép

Một giấy phép thiếu sẽ không ném lỗi. DoconutHost.Initialize thành công, site khởi động, và trình xem chạy, nhưng mỗi trang đều có dấu nước đánh giá và không có khả năng tùy chọn nào được cấp.

Một tệp giấy phép được tìm thấy nhưng bị từ chối là khác. Chữ ký không hợp lệ, bị can thiệp, hoặc bản dựng ngoài khung thời gian phiên bản của giấy phép sẽ khiến OpenDocumentAsync ném LicenseException với lý do.

Các plugin cần giấy phép khi khởi động

Đăng ký một plugin có khả năng không được bất kỳ giấy phép nào cấp sẽ dừng ứng dụng khi khởi động. DoconutHost.Initialize ném lỗi trong Application_Start:

InvalidOperationException: The Converter plugin is registered via AddPlugin but no active
license grants Converter. Remove the AddPlugin<...>() call or install a license (or
trial/demo) that includes Converter.

Trong System.Web, bạn không thấy thông báo đó trong trình duyệt. Mỗi yêu cầu tới site trả về một 500 trống — không có trang lỗi, không có stack trace, không có gì trong log IIS. Ngoại lệ chỉ được ghi lại trong Windows event log (log Ứng dụng, nguồn ASP.NET). Nếu toàn bộ site ngừng phản hồi ngay sau khi bạn thêm dòng AddPlugin, hãy kiểm tra các tệp giấy phép trong wwwroot trước mã: tệp Doconut.Viewer.<Capability>.lic của plugin phải nằm cạnh Doconut.Viewer.lic, và nếu không có giấy phép cơ bản, các tệp plugin sẽ không được đọc.

Xác minh giấy phép đã tải

IDoconutLicenseService là nguồn sự thật mà SDK sử dụng. Lấy nó từ DoconutHost.Services để cung cấp một endpoint chẩn đoán đã xác thực hoặc điều khiển các tính năng — không bao giờ trả lại nội dung giấy phép:

// GET /License/Status
public ActionResult Status()
{
    var license = Doconut.DoconutHost.Services.GetRequiredService<IDoconutLicenseService>();

    return Json(new
    {
        viewer     = license.IsViewerLicensed || license.IsTemporary,
        temporary  = license.IsTemporary,
        search     = license.IsCapabilityGranted(LicenseCapability.Search),
        annotation = license.IsCapabilityGranted(LicenseCapability.Annotation),
        converter  = license.HasConverter,
        dicom      = license.HasDicom
    }, JsonRequestBehavior.AllowGet);
}

Giấy phép được đọc một lần, trong DoconutHost.Initialize. Sau khi thay thế tệp giấy phép, hãy tái tạo lại application pool (hoặc sửa đổi Web.config) để Application_Start chạy lại.

Khắc phục sự cố

Các bước tiếp theo

• Cấp phép — các khả năng, và cách kiểm tra chúng tại thời gian chạy.
• Khắc phục sự cố — dấu nước, lỗi khởi động, và các triệu chứng khác.