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 mô tả 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.

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 khám phá tự động khi không có gì đượ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 auto-search.

Bằng đường dẫn

LicensePath được truyền vào File.Exists đúng 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à cũng không phải thư mục chứa Program.cs. Nếu đường dẫn không thể giải quyết, Doconut không ném lỗi và không chuyển sang tìm kiếm tự động — nó chỉ đơn giản không tải giấy phép và trình xem sẽ có dấu nước. Tìm kiếm tự động chỉ chạy khi không có LicensePath, LicenseContent, hoặc LicenseStream nào được thiết lập.

Ư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 khám phá tự động bên dưới.

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

Bằng 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.

// Precedence: LicenseStream > LicenseContent > LicensePath > auto-search.
builder.Services.AddDoconut(options =>
{
    options.LicenseStream = licenseStream;
});

Bằng 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 trình quản lý bí mật:

// License XML from a database, environment variable, or secret manager —
// no file on disk. Beaten only by LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

Khám phá tự động

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:

// Configure nothing, and Doconut searches for the license itself:
//   1. {CurrentDirectory}/wwwroot
//   2. {CurrentDirectory}/wwwroot/lib
//   3. AppContext.BaseDirectory  (the build output folder)
// It looks for Doconut.Viewer.lic plus any per-plugin
// Doconut.Viewer.<Capability>.lic files alongside it.
builder.Services.AddDoconut();

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

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

Filenames (checked in each directory above, in order):
  Doconut.Viewer.lic                   — base viewer license
  Doconut.Viewer.<Capability>.lic      — per-plugin license, alongside Doconut.Viewer.lic

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

LicensePath, và việc dò AppContext.BaseDirectory của tìm kiếm tự động, đều cần tệp .lic tồn tại bên cạnh ứng dụng đã biên dịch — không chỉ trong wwwroot nguồn của bạn. Ứng dụng thử nghiệm của SDK sao chép tệp này trong mỗi lần xây dựng bằng mục tiêu MSBuild sau:

<Target Name="CopyLicensesToOutput" AfterTargets="Build">
  <ItemGroup>
    <DoconutLicenseFiles Include="$(MSBuildProjectDirectory)\wwwroot\*.lic" />
  </ItemGroup>
  <Copy SourceFiles="@(DoconutLicenseFiles)" DestinationFolder="$(OutDir)" SkipUnchangedFiles="true" />
</Target>

Giữ các tệp .lic ra khỏi hệ thống kiểm soát nguồn — triển khai chúng bên cạnh ứng dụng, hoặc tiêm 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 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 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à trường hợp khác. Chữ ký không hợp lệ, giả mạo, đưa vào danh sách đen, hoặc xây dựng ngoài cửa sổ phiên bản của giấy phép sẽ khiến OpenDocumentAsync ném LicenseException kèm 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ẽ vẫn tiếp tục ở chế độ có dấu nước.

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 biệt: đố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 InvalidOperationException, vì vậy ứng dụng sẽ không khởi động. Ví dụ, đăng ký plugin Converter mà không có giấy phép cấp 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 chỉ ra cách khắc phục ngay lập tức: hoặc loại bỏ 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 khả năng đó. Các đăng ký tạm thời được cho phép tồn tại sau ngày hết hạn để một ứng dụng đã cấu hình có thể giảm chức năng ở thời gian chạy thay vì 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, nguồn sự thật duy nhất mà SDK dùng, để cung cấp một endpoint chẩn đoán đã xác thực hoặc để điều khiển các cờ tính năng. Không trả lại nội dung hoặc khó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 dẫn 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ấp độ giấy phép, và cách xác minh những gì đã được tải ở thời gian chạy.
• Khắc phục sự cố — dấu nước, giấy phép bị từ chối, và lỗi khả năng.