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ó dấu watermark đánh giá. Trang này trình bày bốn cách cung cấp giấy phép, và thứ tự ưu tiên chính xác khi có hơn một cách được thiết lập.

Giấy phép được tải một lần, trong AddDoconut(). Đây là một thay đổi so với thư viện .NET Standard trước đây, nơi giấy phép được truyền cho một thể hiện Viewer hoặc được thiết lập thông qua các lời gọi tĩnh Viewer.DoconutLicense(...) / Viewer.SetLicensePlugin(...). Các phương thức đó không phải là cơ chế khởi động trong phiên bản này — xem hướng dẫn di chuyển.

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

Có bốn cách: ba nguồn rõ ràng trên DoconutOptions — một luồng, nội dung thô, hoặc một đường dẫn tệp — cộng với việc tự động khám phá khi không có nào được thiết lập. Khi có hơn một cách được thiết lập, thứ tự ưu tiên là chính xác:

LicenseStream thắng LicenseContent thắng LicensePath thắng tự động tìm kiếm.

Theo đường dẫn

LicensePath được truyền vào File.Exists chính xác như đã cho. Một đường dẫn tương đối được giải quyết dựa trên thư mục làm việc hiện tại của tiến trình — không phải thư mục dự án của bạn, và không phải thư mục chứa Program.cs. Nếu đường dẫn không được giải quyết, Doconut không ném ngoại lệ và không quay lại tự động tìm kiếm — nó chỉ đơn giản không tải giấy phép và trình xem sẽ hiển thị watermark. Tự động tìm kiếm chỉ chạy khi không có LicensePath, LicenseContent, hoặc LicenseStream nào được thiết lập. 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 các giấy phép plugin nằm bên cạnh giấy phép cơ bản.

Ưu tiên sử dụng đường dẫn tuyệt đối (ví dụ được xây dựng từ IWebHostEnvironment.WebRootPath hoặc AppContext.BaseDirectory), hoặc bỏ qua hoàn toàn LicensePath và dựa vào việc tự động khám phá bên dưới.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});

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 kho bí mật thay vì một tệp trên đĩa.

// Thứ tự ưu tiên: LicenseStream > LicenseContent > LicensePath > auto-search.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

Theo nội dung

LicenseContent chấp nhận văn bản giấy phép trực tiếp — từ biến môi trường, cơ sở dữ liệu, hoặc trình quản lý bí mật:

// XML giấy phép từ cơ sở dữ liệu, biến môi trường, hoặc trình quản lý bí mật —
// không có tệp trên đĩa. Chỉ bị vượt qua bởi LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Tự động khám phá

Không cấu hình bất kỳ ba nguồn rõ ràng nào, và Doconut sẽ tự tìm kiếm giấy phép:

// Không cấu hình gì, và Doconut sẽ tự tìm kiếm giấy phép, chỉ trong hai thư mục này:
//   1. {CurrentDirectory}/wwwroot
//   2. {AppContext.BaseDirectory}/wwwroot   (wwwroot trong thư mục đầu ra của bản dựng)
// Nó tìm Doconut.lic trước, sau đó Doconut.Viewer.lic, cộng với bất kỳ
// các tệp Doconut.Viewer.<Capability>.lic bên cạnh nó.
builder.Services.AddDoconut();

Các thư mục kiểm tra, theo thứ tự, và các tên tệp được tìm trong mỗi thư mục:

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

Tên tệp (được kiểm tra trong mỗi thư mục ở trên, theo thứ tự):
  Doconut.lic                          — giấy phép trình xem cơ bản (được kiểm tra đầu tiên)
  Doconut.Viewer.lic                   — giấy phép trình xem cơ bản
  Doconut.Viewer.<Capability>.lic      — giấy phép theo khả năng, nằm bên cạnh giấy phép cơ bản

Không có gì bên ngoài thư mục wwwroot được đọc: một tệp .lic trong thư mục đầu ra, hoặc trong wwwroot/lib, sẽ bị bỏ qua.

Nếu trước đây bạn đã truyền một List<string> các đường dẫn giấy phép vào hàm khởi tạo Viewer — một cho mỗi khả năng — hãy giữ các tệp đồng hành đó bên cạnh Doconut.Viewer.lic và để việc tự động khám phá lấy chúng. Không có tùy chọn danh sách các đường dẫn trên DoconutOptions.

Sao chép giấy phép vào thư mục đầu ra của bạn

Khi quá trình không chạy từ thư mục dự án — một ứng dụng đã xuất bản, IIS, một container, một trình chạy thử nghiệm — lần dò đầu tiên sẽ không tìm thấy, và lần thứ hai, {AppContext.BaseDirectory}/wwwroot, phải tìm tệp. Ứng dụng kiểm thử riêng của SDK sao chép các giấy phép vào đó trong mỗi lần biên dịch bằng mục tiêu MSBuild này:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
    <StaleOutputLicenses Include="$(OutDir)wwwroot\*.lic" />
  </ItemGroup>
  <!-- Xóa trước, để việc đổi tên hoặc xóa một tệp .lic trong wwwroot cũng được loại bỏ khỏi đầu ra. -->
  <Delete Files="@(StaleOutputLicenses)" />
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)wwwroot" />
</Target>

Đích phải là $(OutDir)wwwroot: một tệp .lic được sao chép vào thư mục gốc đầu ra sẽ không bao giờ được tìm thấy bằng việc tự động tìm kiếm. Các ví dụ LicensePath trên trang này đều chỉ tới cùng vị trí đó.

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 với ứng dụng, hoặc tiêm giấy phép thông qua LicenseContent hoặc LicenseStream từ kho lưu trữ bí mật của bạn.

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

Việc thiếu giấy phép sẽ không gây lỗi. AddDoconut() thành công, ứng dụng khởi động, và trình xem chạy — nhưng mỗi trang đều có dấu watermark đá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 thì khác. Chữ ký không hợp lệ, bị giả mạo, bị đưa vào danh sách đen, hoặc bản dựng nằm ngoài khoảng thời gian phiên bản của giấy phép sẽ khiến OpenDocumentAsync ném ra LicenseException với License.RejectionMessage. Một giấy phép đã hết hạn theo lịch mà không có thông báo từ chối sẽ tiếp tục ở chế độ có watermark.

Plugin cần các khả năng

Đăng ký một plugin mà không có quyền tương ứng là khác: đối với giấy phép thiếu, tệp TRIAL cũ, hoặc giấy phép trả phí mà không có khả năng đó, AddDoconut() ném ra InvalidOperationException, vì vậy ứng dụng không khởi động. Ví dụ, đăng ký plugin Converter mà không có giấy phép cấp quyền Converter:

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.

Thông báo này cho bạn biết cách khắc phục trực tiếp: hoặc xóa lời gọi options.AddPlugin<...>() cho plugin đó, hoặc cài đặt một giấy phép trả phí hoặc một giấy phép Temporary/Demo (NFR) đang hoạt động mà cấp quyền đó. Các đăng ký tạm thời được phép tồn tại sau ngày hết hạn để một ứng dụng đã cấu hình sẵn có thể giảm chức năng tại thời gian chạy thay vì bị sập khi khởi động lại; một khi hết hạn, các khả năng của chúng vẫn bị thu hồi.

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

Sử dụng IDoconutLicenseService, cùng nguồn thông tin thực tế mà SDK sử dụng, để 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 trả về nội dung hoặc khóa của giấy phép.

app.MapGet("/api/doconut/license", (IDoconutLicenseService license) => Results.Ok(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
}));

Giấy phép được đọc trong quá trình đăng ký AddDoconut(). ResetLicense hiện chỉ là một thuộc tính tương thích mà không có đường tải lại hoạt động, vì vậy việc thay thế tệp giấy phép yêu cầu khởi động lại ứng dụng.

Ma trận khắc phục sự cố

Các bước tiếp theo

• Cấp phép — các khả năng, các cấp giấy phép, và xác minh những gì đã được tải tại thời gian chạy.
• Khắc phục sự cố — dấu watermark, giấy phép bị từ chối, và lỗi khả năng.