Hệ thống Plugin

Mở rộng trình xem bằng 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 plugin — các gói NuGet riêng biệt đóng góp trình xem hoặc dịch vụ và được kích hoạt bằng giấy phép của bạn. Trang này giải thích mô hình đăng ký, những gì xảy ra khi khởi động nếu giấy phép không bao gồm một plugin, và cách tích hợp trình xem của riêng bạn.

Đăng ký plugin

Mỗi gói plugin cung cấp một lớp plugin. Đăng ký nó một lần, trong Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Một plugin đã đăng ký mà giấy phép bị thiếu sẽ ném ngoại lệ ở đây, trong Application_Start, và đó
// trang web sau đó trả lời mọi yêu cầu bằng một lỗi 500 trống. Lý do nằm trong nhật ký sự kiện Windows.

AddPlugin<TPlugin>() tạo plugin và cho phép nó đăng ký các đóng góp của mình với 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, và DoconutHost.Initialize kiểm tra mọi plugin đã đăng ký so với giấy phép trước khi trang web phục vụ yêu cầu đầu tiên.

Thiếu giấy phép plugin làm ngừng trang web

Khi không có giấy phép hoạt động nào cấp khả năng cho plugin đã đăng ký — không có giấy phép nào, một tệp TRIAL cũ, hoặc một giấy phép trả phí mà không có khả năng đó — DoconutHost.Initialize ném InvalidOperationException từ Application_Start:

text
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, một ngoại lệ trong Application_Start không tạo ra trang lỗi. Mỗi yêu cầu trả về một 500 trống, nhật ký IIS không hiển thị gì hữu ích, và thông báo chỉ xuất hiện trong nhật ký sự kiện Windows (nhật ký Ứng dụng, nguồn ASP.NET). Khi một trang web ngừng phản hồi ngay sau khi một dòng AddPlugin được thêm, hãy kiểm tra các tệp giấy phép trong wwwroot trước — xem Cài đặt giấy phép.

Hợp đồng

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

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // ví dụ "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // cửa kiểm tra giấy phép
    void Register(IDoconutPluginBuilder builder); // cộng góp viewers/services
}

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; nhà máy 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 pipeline 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.

Kiểm tra khởi động thường giữ một plugin không có giấy phép ra khỏi pipeline yêu cầu. Nhà máy trình xem cũng áp dụng hai quy tắc phòng thủ, quan trọng nếu quyền thay đổi trong khi trang web đang chạy:

  • Một plugin ghi đè lên trình xem tích hợp (nó yêu cầu một phần mở rộng mà trình xem tích hợp cũng xử lý): nếu khả năng được cấp phép, trình xem của plugin sẽ thắng; nếu không, Doconut sẽ quay lại 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 hành vi của 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, việc mở sẽ thất bại:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Một giấy phép tạm thời hoạt động cấp mọi khả năng. Đó là một bất ngờ kinh điển khi đưa vào hoạt động: những dòng AddPlugin giống như đã chạy trong quá trình đánh giá sẽ làm ngừng trang web khi giấy phép mua không bao gồm một trong những khả năng đó. So sánh IsCapabilityGranted(...) với những gì bạn đã mua trước khi triển khai. 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à một giấy phép tạm thời.

Việc kiểm soát tương tự cũng áp dụng cho trình duyệt: Viewer.ReferenceScripts() và ReferenceCss() phát ra các tệp cho các tính năng được kiểm soát bằng giấy phép (Tìm kiếm, Ghi chú) chỉ khi giấy phép cấp chúng, vì vậy trang không bao giờ cung cấp tính năng mà máy chủ sẽ từ chối.

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

Tính năngCách bậtKhả năngĐóng góp
Ghi chúTích hợp trong trình xem; bao gồm các tài nguyên ghi chúAnnotationTạo nội dung trong trình duyệt, duy trì phiên, 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 các tài nguyên tìm kiếmSearchChỉ mục văn bản gốc, đánh dấu, điều hướng kết quả
Bộ chuyển đổiCài đặt Doconut.NETFramework.Converter và đăng ký ConverterPluginConverterDịch vụ chuyển đổi C# và một widget web tùy chọn
DICOMCài đặt Doconut.NETFramework.Dicom và đăng ký DicomPluginDicomXem hình ảnh y tế cho .dcm và .ima
Bộ kýCài đặt Doconut.NETFramework.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

Ghi chú và Tìm kiếm không sử dụng AddPlugin<TPlugin>(). Bộ chuyển đổi, DICOM và Bộ ký mỗi đều có một trang dưới Plugin với cấu hình và cách sử dụng của chúng. Trong gói này, DICOM hiển thị các trang, khung và hoạt hình, nhưng không đọc siêu dữ liệu kỹ thuật — xem Plugin DICOM.

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

Bạn có thể tích hợp một trình xem vào pipeline mà không cần viết gói plugin, trực tiếp trong Application_Start:

csharp
Doconut.DoconutHost.Initialize(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à factory 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. Khi bạn không cung cấp cấu hình mặc định, nhà máy sẽ sử dụng một ImageConfig.

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

  • Các plugin được đăng ký một cách rõ ràng trong DoconutHost.Initialize, và các khả năng của chúng được xác thực ở đó; một quyền thiếu sẽ làm ngừng trang web với một 500 trống, lý do được ghi trong nhật ký sự kiện Windows.
  • 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 tạm thời hoạt động mở khóa mọi thứ; môi trường sản xuất mở khóa những gì bạn đã mua. Kiểm tra với IDoconutLicenseService trước khi phát hành.

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