Hệ thống Plugin

Mở rộng trình xem với các plugin

Lõi của Doconut vẫn gọn nhẹ; chức năng tùy chọn được cung cấp dưới dạng plugins — các gói NuGet riêng biệt đóng góp các trình xem hoặc dịch vụ và được bật bằng giấy phép của bạn. Trang này giải thích mô hình đăng ký, cách kiểm soát giấy phép hoạt động tại thời gian chạy, và cách tích hợp trình xem của riêng bạn.

Mô hình này là mới trong bản phát hành này. Thư viện .NET Standard trước đây không có đăng ký plugin: việc chuyển đổi nằm trong trình xem tự nó và giấy phép plugin được cài đặt thông qua các lời gọi tĩnh Viewer.SetLicensePlugin(...). Cả hai đều không phải là cơ chế đăng ký ở đây.

Đăng ký một plugin

Mỗi gói plugin cung cấp một lớp plugin. Bạn đăng ký nó một lần, vào lúc khởi động:

csharp
builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddPlugin<TPlugin>() khởi tạo plugin và gọi callback Register của nó đối với registry plugin được giữ trên DoconutOptions. Mọi thứ mà một plugin đóng góp đều được gắn thẻ với khả năng yêu cầu của plugin. AddDoconut() xác thực các plugin đã đăng ký ngay lập tức: thiếu giấy phép, tệp legacy TRIAL, hoặc giấy phép trả phí mà không có khả năng sẽ khiến khởi động thất bại với InvalidOperationException. Một đăng ký Temporary/Demo được giữ lại qua thời gian hết hạn, nhưng các khả năng thời gian chạy của nó sẽ bị thu hồi sau ngày hết hạn.

Hợp đồng

Một plugin thực hiện một giao diện được thiết kế cố ý nhỏ gọn:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // ví dụ: "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // cổng giấy phép
    void Register(IDoconutPluginBuilder builder); // cống hiến các trình xem/dịch vụ
}

Bên trong Register, bộ xây dựng chấp nhận hai loại đóng góp:

  • builder.RegisterViewer(extension, factory) — một trình xem cho một phần mở rộng tệp; bộ tạo trả về một IFormatViewer (plugin DICOM đăng ký .dcm và .ima theo cách này),
  • builder.RegisterService<TContract>(() => …) — một dịch vụ kiểu mà các phần khác của đường truyền có thể tra cứu.

Khả năng và kiểm soát

Khả năng là các đơn vị giấy phép. Converter, Dicom và Signer được cung cấp dưới dạng plugin tùy chọn; Search và Annotation là các tính năng tích hợp sẵn được kiểm soát theo cùng cách. Trình xem cơ bản không phải là một khả năng — nó là điều kiện tiên quyết, được hiển thị dưới dạng IsViewerLicensed trên dịch vụ giấy phép.

Việc xác thực khi khởi động thường ngăn một plugin không có giấy phép tham gia đường truyền yêu cầu. Bộ tạo trình xem cũng áp dụng hai quy tắc thời gian chạy phòng thủ, quan trọng nếu quyền lợi thay đổi sau khi khởi động:

  • Plugin ghi đè một trình xem tích hợp (một plugin yêu cầu một phần mở rộng mà đăng ký tích hợp cũng xử lý): nếu khả năng được cấp phép, trình xem plugin sẽ thắng; nếu không, Doconut sẽ im lặng chuyển về trình xem tích hợp. Người dùng vẫn thấy tài liệu của họ — họ chỉ không nhận được tính năng plugin.
  • Định dạng chỉ có plugin (.dcm và .ima — DICOM không có trình xem tích hợp): nếu không có khả năng, lời gọi mở sẽ thất bại nghiêm trọng:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Một giấy phép Temporary hoạt động sẽ cấp mọi khả năng (với chế độ xem cơ bản sạch sẽ, không có dấu nước). Đây là nguồn gây bất ngờ khi đưa vào hoạt động: đăng ký cùng các plugin với một giấy phép mua mà thiếu một trong các khả năng của chúng sẽ khiến AddDoconut() thất bại trong quá trình khởi động. So sánh IsCapabilityGranted(...) với kế hoạch của bạn trước khi triển khai. Ngược lại: với không có giấy phép nào, không có gì được cấp — một giấy phép thiếu không phải là giấy phép Temporary.

Cơ chế kiểm soát tương tự cũng xuất hiện phía client: Viewer.ReferenceScripts() và ReferenceCss() phát ra các bundle script/style cho các tính năng được kiểm soát bằng giấy phép (tìm kiếm, chú thích, …) chỉ khi giấy phép bật chúng, vì vậy giao diện UI của widget vẫn nhất quán với những gì server thực sự thực hiện.

Bản đồ tính năng và plugin

Giao diện UI sản phẩm sử dụng “plugin” như một nhãn tính năng rộng, nhưng việc đăng ký trên server khác nhau:

Tính năngCách nó được bậtKhả năngĐóng góp
Chú thíchTích hợp trong trình xem; bao gồm các tài nguyên chú thíchAnnotationTạo nội dung trong trình duyệt, duy trì phiên, và xuất bản có nhúng
Tìm kiếmTích hợp trong các trình xem định dạng có khả năng tìm kiếm; bao gồm tài nguyên tìm kiếm và cho phép trích xuất khi cầnSearchChỉ mục văn bản gốc, đánh dấu, và điều hướng kết quả
Bộ chuyển đổiCài đặt Doconut.NETStandard.Converter và đăng ký ConverterPluginConverterDịch vụ chuyển đổi C# và widget web tùy chọn
DICOMCài đặt Doconut.NETStandard.Dicom và đăng ký DicomPluginDicomXem ảnh y tế cho .dcm và .ima
Bộ kýCài đặt Doconut.NETStandard.Signer và đăng ký SignerPluginSignerChữ ký hiển thị và con dấu kỹ thuật số cho PDF và Word: dịch vụ ký C# và một widget web tùy chọn

Chú thích và Tìm kiếm bình thường không sử dụng AddPlugin<TPlugin>(); các bundle của chúng chỉ được phát ra khi giấy phép cấp khả năng tương ứng. Bộ chuyển đổi, DICOM và Bộ ký là các triển khai IDoconutPlugin tùy chọn.

Các gói plugin đã phát hành

PluginGóiKhả năngĐóng góp
Bộ chuyển đổiDoconut.NETStandard.ConverterConverterKhả năng chuyển đổi tài liệu
DICOMDoconut.NETStandard.DicomDicomXem ảnh y tế (.dcm và .ima — định dạng chỉ có plugin)
Bộ kýDoconut.NETStandard.SignerSignerKý PDF và Word

Mỗi plugin có một trang riêng dưới Plugins với cấu hình và cách sử dụng của nó.

Trình xem tùy chỉnh — trình xử lý định dạng của bạn

Bạn có thể tích hợp một trình xem vào đường truyền mà không cần viết gói plugin, trực tiếp từ Program.cs:

csharp
builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // thực hiện IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // cấu hình mặc định tùy chọn
});

// Trình xử lý định dạng mà nhà máy tạo ra. Thay thế các thành viên này bằng việc render của riêng bạn.
public sealed class MyCustomViewer : Doconut.Core.Interfaces.IFormatViewer
{
    public ViewerType ViewerType => ViewerType.None;
    public int TotalPages => 0;
    public int DefaultWidth => 0;
    public int DefaultHeight => 0;
    public bool PreferOcr => false;

    public Task LoadAsync(Stream documentStream, BaseConfig config, CancellationToken ct = default)
        => Task.CompletedTask;

    public Task<byte[]> GetPageImageAsync(int pageNumber, CancellationToken ct = default)
        => Task.FromResult(Array.Empty<byte>());

    public void Dispose() { }
}

Trình xem tùy chỉnh có ưu tiên hơn mọi thứ — cả tích hợp sẵn và plugin — và không bị kiểm soát bằng giấy phép (chúng là mã của bạn). Bộ tạo sẽ quay lại một ImageConfig khi bạn không cung cấp cấu hình mặc định.

Những điểm cần nhớ

  • Các plugin được đăng ký một cách rõ ràng và LicenseCapability của chúng được xác thực trong quá trình AddDoconut() — thiếu hoặc không đủ quyền không tạm thời sẽ thất bại nhanh.
  • Các plugin kiểu ghi đè giảm dần một cách nhẹ nhàng; các định dạng chỉ có plugin sẽ thất bại với một LicenseException.
  • Một giấy phép Temporary hoạt động sẽ mở khóa mọi thứ; môi trường sản xuất mở khóa những gì bạn đã mua. Xác minh với IDoconutLicenseService trước khi phát hành.

Trang này có hữu ích không?