Systém pluginů

Rozšiřte prohlížeč pomocí pluginů

Jádro Doconut zůstává štíhlé; volitelná funkčnost je dodávána jako pluginy — samostatné balíčky NuGet, které poskytují prohlížeče nebo služby a jsou aktivovány vaší licencí. Tato stránka vysvětluje model registrace, jak se řízení licencí chová za běhu, a jak připojit vlastní prohlížeč.

Tento model je v tomto vydání nový. Předchozí knihovna .NET Standard neměla registr pluginů: konverze probíhala přímo v prohlížeči a licence pluginů byly instalovány pomocí statických volání Viewer.SetLicensePlugin(...). Ani to není zde registrační mechanismus.

Registrace pluginu

Každý balíček pluginu poskytuje jednu třídu pluginu. Zaregistrujete ji jednou, při spuštění:

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

AddPlugin<TPlugin>() vytvoří instanci pluginu a zavolá jeho Register zpětné volání proti registru pluginů uloženému na DoconutOptions. Všechno, co plugin přispívá, je označeno požadovanou schopností pluginu. AddDoconut() okamžitě ověřuje registrované pluginy: chybějící licence, starý soubor TRIAL nebo placená licence bez schopnosti způsobí selhání spuštění s InvalidOperationException. Registrace Temporary/Demo je zachována po vypršení, ale její běhové schopnosti jsou po datu vypršení odebrány.

Smlouva

Plugin implementuje úmyslně malé rozhraní:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // např. "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // licenční brána
    void Register(IDoconutPluginBuilder builder); // přispívat k prohlížečům/službám
}

Uvnitř Register přijímá builder dva typy příspěvků:

  • builder.RegisterViewer(extension, factory) — prohlížeč pro příponu souboru; továrna vrací IFormatViewer (plugin DICOM takto registruje .dcm a .ima),
  • builder.RegisterService<TContract>(() => …) — typová služba, kterou mohou ostatní části pipeline vyhledat.

Schopnosti a řízení

Schopnosti jsou licenční jednotky. Converter, Dicom a Signer jsou dodávány jako volitelné pluginy; Search a Annotation jsou vestavěné funkce řízené stejným způsobem. Základní prohlížeč není schopnost — je předpokladem, vystaveným jako IsViewerLicensed v licenční službě.

Ověření při spuštění normálně zabraňuje nelicencovanému pluginu vstoupit do požadavkové pipeline. Továrna prohlížečů také uplatňuje dvě obranné běhové pravidla, která jsou důležitá, pokud se oprávnění po spuštění změní:

  • Plugin přepisuje vestavěný prohlížeč (plugin si nárokuje příponu, kterou také obsluhuje vestavěný registr): pokud je schopnost licencována, vítězí prohlížeč pluginu; pokud ne, Doconut tiše přepne na vestavěný prohlížeč. Uživatelé stále vidí svůj dokument — jen nedostanou funkci pluginu.
  • Formát pouze pro plugin (.dcm a .ima — DICOM nemá vestavěný prohlížeč): bez schopnosti volání open selže tvrdě:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Aktivní dočasná licence poskytuje všechny schopnosti (s čistým, neoznačeným základním prohlížením). To je klasický zdroj překvapení při nasazení: registrace stejných pluginů s zakoupenou licencí, která vynechává jednu z jejich schopností, způsobí selhání AddDoconut() během spuštění. Porovnejte IsCapabilityGranted(...) se svým plánem před nasazením. Naopak: s žádnou licencí vůbec, nic není poskytnuto — chybějící licence není dočasná licence.

Stejné řízení se objevuje i na straně klienta: Viewer.ReferenceScripts() a ReferenceCss() generují balíčky skriptů/stylů pro funkce řízené licencí (vyhledávání, anotace, …) pouze když licence je povolí, takže UI widgetu zůstává v souladu s tím, co server skutečně udělá.

Mapa funkcí a pluginů

Uživatelské rozhraní produktu používá „plugin“ jako široký štítek funkce, ale registrace na serveru se liší:

FunkceJak je povolenoSchopnostPřispívá
AnnotationVestavěno v prohlížeči; zahrnuje zdroje anotacíAnnotationAutorování v prohlížeči, perzistence relace a exporty s vrytou anotací
SearchVestavěno v prohlížečích podporujících vyhledávatelné formáty; zahrnuje zdroje vyhledávání a umožňuje extrakci tam, kde je potřebaSearchNativní textový index, zvýraznění a navigace výsledků
ConverterNainstalujte Doconut.NETStandard.Converter a zaregistrujte ConverterPluginConverterC# konverzní služba a volitelný webový widget
DICOMNainstalujte Doconut.NETStandard.Dicom a zaregistrujte DicomPluginDicomProhlížení medicínských obrazů pro .dcm a .ima
SignerNainstalujte Doconut.NETStandard.Signer a zaregistrujte SignerPluginSignerViditelné podpisy a digitální pečeti pro PDF a Word: C# služba podepisování a volitelný webový widget

Annotation a běžné vyhledávání nepoužívají AddPlugin<TPlugin>(); jejich balíčky jsou generovány pouze tehdy, když licence poskytne odpovídající schopnost. Converter, DICOM a Signer jsou opt‑in IDoconutPlugin implementace.

Vydané balíčky pluginů

PluginBalíčekSchopnostPřispívá
ConverterDoconut.NETStandard.ConverterConverterSchopnost konverze dokumentů
DICOMDoconut.NETStandard.DicomDicomProhlížení medicínských obrazů (.dcm a .ima — formáty pouze pro plugin)
SignerDoconut.NETStandard.SignerSignerPodepisování PDF a Word

Každý má vlastní stránku pod Plugins s jeho konfigurací a použitím.

Vlastní prohlížeče — váš vlastní obslužný formát

Můžete připojit prohlížeč do pipeline, aniž byste psali balíček pluginu, přímo z Program.cs:

csharp
builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // implementuje IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // volitelná výchozí konfigurace
});

// Formátový handler, který továrna vytvoří. Nahraďte tyto členy vlastním vykreslováním.
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() { }
}

Vlastní prohlížeče mají přednost před všemi — vestavěnými i pluginy — a nejsou řízeny licencí (jsou vaším kódem). Továrna přepne na ImageConfig, pokud neposkytnete výchozí konfiguraci.

Závěry

  • Pluginy jsou registrovány explicitně a jejich LicenseCapability je ověřováno během AddDoconut() — chybějící nebo nedostatečné ne‑dočasné oprávnění selže rychle.
  • Pluginy typu override selhávají elegantně; formáty pouze pro plugin selžou s LicenseException.
  • Aktivní dočasná licence odemyká vše; produkční licence odemyká to, co jste zakoupili. Ověřte pomocí IDoconutLicenseService před vydáním.

Byla tato stránka užitečná?