Система Плагінів

Розширте переглядач за допомогою плагінів

Ядро Doconut залишається легким; додаткова функціональність постачається у вигляді плагінів — окремих пакетів NuGet, які додають переглядачі або сервіси і активуються вашою ліцензією. На цій сторінці пояснюється модель реєстрації, як працює обмеження ліцензії під час виконання та як підключити власний переглядач.

Реєстрація плагіна

Кожен пакет плагіна надає один клас плагіна. Ви реєструєте його один раз під час запуску:

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

AddPlugin<TPlugin>() створює екземпляр плагіна та викликає його Register зворотний виклик у реєстрі плагінів, що зберігається на DoconutOptions. Все, що додає плагін, позначається необхідною можливістю плагіна. AddDoconut() негайно перевіряє зареєстровані плагіни: відсутня ліцензія, застарілий файл TRIAL або платна ліцензія без можливості призводить до помилки запуску з InvalidOperationException. Реєстрація Temporary/Demo зберігається після закінчення терміну, але її можливості під час виконання відкликаються після дати закінчення.

Контракт

Плагін реалізує навмисно невеликий інтерфейс:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // наприклад "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // ліцензійний шлюз
    void Register(IDoconutPluginBuilder builder); // додати переглядачі/служби
}

Всередині Register, будівельник приймає два типи внесків:

  • builder.RegisterViewer(extension, factory) — переглядач для розширення файлу; фабрика повертає IFormatViewer (плагін DICOM реєструє .dcm та .ima таким чином),
  • builder.RegisterService<TContract>(() => …) — типізований сервіс, який інші частини конвеєра можуть знайти.

Можливості та обмеження

Можливості — це одиниці ліцензії. Converter, Dicom та Signer постачаються як плагіни за вибором; Search і Annotation — вбудовані функції, обмежені тим же способом. Базовий переглядач не є можливістю — це передумова, представлена як IsViewerLicensed у сервісі ліцензії.

Перевірка під час запуску зазвичай запобігає входженню неліцензованого плагіна у конвеєр запитів. Фабрика переглядачів також застосовує два захисних правила під час виконання, які важливі, якщо права змінюються після запуску:

  • Плагін замінює вбудований переглядач (плагін заявляє розширення, яке також обробляє вбудований реєстр): при наявності ліцензованої можливості переглядач плагіна переважає; без неї Doconut тихо повертається до вбудованого переглядача. Користувачі все ще бачать свій документ — просто не отримують функцію плагіна.
  • Формат лише для плагіна (.dcm та .ima — у DICOM немає вбудованого переглядача): без можливості виклик відкриття завершується з помилкою:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Активна тимчасова ліцензія надає всі можливості (з чистим, без водяних знаків базовим переглядом). Це класичне джерело несподіванок під час запуску: реєстрація тих самих плагінів з придбаної ліцензії, яка не містить одну з їх можливостей, призводить до помилки AddDoconut() під час запуску. Порівняйте IsCapabilityGranted(...) з вашим планом перед розгортанням. З іншого боку: з повністю відсутньою ліцензією нічого не надається — відсутня ліцензія не є тимчасовою ліцензією.

Те ж обмеження проявляється на клієнті: Viewer.ReferenceScripts() і ReferenceCss() генерують пакети скриптів/стилів для функцій, обмежених ліцензією (пошук, анотація, …) лише коли ліцензія їх увімкне, тому інтерфейс віджету залишається узгодженим з тим, що сервер фактично робить.

Карта функцій та плагінів

Інтерфейс продукту використовує «плагін» як широкий мітку функції, але реєстрація на сервері відрізняється:

ФункціяЯк увімкненоМожливістьВносить
АнотаціяВбудовано в переглядач; включає ресурси анотаціїAnnotationАвторинг у браузері, збереження сесії та експорт з вбудованою анотацією
ПошукВбудовано в переглядачі формату з підтримкою пошуку; включає ресурси пошуку та дозволяє вилучення за потребиSearchВбудований текстовий індекс, підсвічування та навігація результатами
КонвертерВстановіть Doconut.NET8.Converter та зареєструйте ConverterPluginConverterСервіс конвертації C# та необов'язковий веб-віджет
DICOMВстановіть Doconut.NET8.Dicom та зареєструйте DicomPluginDicomПерегляд медичних зображень для .dcm та .ima
ПідписувачВстановіть Doconut.NET8.Signer та зареєструйте SignerPluginSignerВидимі підписи та цифрові печатки для PDF та Word: сервіс підпису C# та необов'язковий веб-віджет

Анотація та звичайний Пошук не використовують AddPlugin<TPlugin>(); їхні пакети генеруються лише коли ліцензія надає відповідну можливість. Конвертер, DICOM та Підписувач — це реалізації IDoconutPlugin за вибором.

Випущені пакети плагінів

ПлагінПакетМожливістьВносить
КонвертерDoconut.NET8.ConverterConverterМожливість конвертації документів
DICOMDoconut.NET8.DicomDicomПерегляд медичних зображень (.dcm та .ima — формати лише для плагіна)
ПідписувачDoconut.NET8.SignerSignerПідпис PDF та Word

Кожен має окрему сторінку у розділі Plugins з його налаштуваннями та використанням.

Користувацькі переглядачі — ваш власний обробник формату

Ви можете підключити переглядач до конвеєра без написання пакету плагіна, безпосередньо з Program.cs:

csharp
builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // реалізує IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // опціональна типова конфігурація
});

// Обробник формату, який створює фабрика. Замініть ці члени власним рендерингом.
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() { }
}

Користувацькі переглядачі мають пріоритет над усім — як вбудованими, так і плагінами — і не підлягають обмеженню ліцензії (це ваш код). Фабрика повертається до ImageConfig, якщо ви не надаєте конфігурацію за замовчуванням.

Висновки

  • Плагіни реєструються явно, і їх LicenseCapability перевіряється під час AddDoconut() — відсутність або недостатність не тимчасових прав призводить до швидкої помилки.
  • Плагіни типу Override деградують плавно; формати лише для плагіна завершуються помилкою LicenseException.
  • Активна тимчасова ліцензія розблоковує все; у продакшн-режимі розблоковується те, що ви придбали. Перевірте за допомогою IDoconutLicenseService перед випуском.

Чи була ця сторінка корисною?