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, co se děje při spuštění, když licence nepokrývá plugin, a jak připojit vlastní prohlížeč.

Registrace pluginu

Každý balíček pluginu poskytuje jednu třídu pluginu. Zaregistrujte ji jednou, v Application_Start:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Registrovaný plugin, jehož licence chybí, vyvolá výjimku zde, v Application_Start, a
// stránka pak odpovídá na každý požadavek prázdným 500. Důvod je v protokolu událostí Windows.

AddPlugin<TPlugin>() vytváří plugin a umožňuje mu zaregistrovat své příspěvky pomocí DoconutOptions. Vše, co plugin přispívá, je označeno požadovanou schopností pluginu a DoconutHost.Initialize kontroluje každý registrovaný plugin vůči licenci před tím, než server obslouží první požadavek.

Chybějící licence pluginu zastaví web

Když žádná aktivní licence nepřiděluje schopnost registrovaného pluginu — žádná licence, starý soubor TRIAL nebo placená licence bez této schopnosti — DoconutHost.Initialize vyhodí výjimku InvalidOperationException z 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.

V System.Web výjimka v Application_Start nevytvoří chybovou stránku. Každý požadavek vrátí prázdný 500, záznam IIS neukazuje nic užitečného a zpráva se objeví pouze v protokolu událostí Windows (protokol Aplikace, zdroj ASP.NET). Když web přestane reagovat těsně po přidání řádku AddPlugin, nejprve zkontrolujte licenční soubory v wwwroot — viz Nastavení licence.

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ět prohlížeče/služby
}

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

  • builder.RegisterViewer(extension, factory) — prohlížeč pro příponu souboru; továrna vrací IFormatViewer (plugin DICOM registruje .dcm a .ima tímto způsobem),
  • builder.RegisterService<TContract>(() => …) — typovanou službu, 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ě drží nelicencovaný plugin mimo pipeline požadavků. Továrna prohlížečů také uplatňuje dvě obranná pravidla, která jsou důležitá, pokud se oprávnění během běhu webu změní:

  • Plugin, který přepíše vestavěný prohlížeč (nárokuje si příponu, kterou také obsluhuje vestavěný prohlížeč): pokud je schopnost licencována, vítězí prohlížeč pluginu; bez ní se Doconut vrátí k vestavěnému prohlížeči. Uživatelé stále vidí svůj dokument; jen nedostanou chování pluginu.
  • Formát pouze pro plugin (.dcm a .ima — DICOM nemá vestavěný prohlížeč): bez schopnosti selže otevření:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Aktivní dočasná licence přiděluje všechny schopnosti. To je klasické překvapení při nasazení: stejné řádky AddPlugin, které běžely během hodnocení, zastaví web, když zakoupená licence vynechá některou z těchto schopností. Porovnejte IsCapabilityGranted(...) s tím, co jste zakoupili před nasazením. S žádnou licencí vůbec, nic není přiděleno — chybějící licence není dočasná licence.

Stejné řízení dosahuje i prohlížeče: Viewer.ReferenceScripts() a ReferenceCss() vydávají soubory pro funkce řízené licencí (Search, Annotation) pouze když licence je přidělí, takže stránka nikdy nenabídne funkci, kterou server odmítne.

Mapa funkcí a pluginů

FunkceJak je povolenoSchopnostPřispívá
PoznámkyVestavěno v prohlížeči; zahrnuje zdroje pro anotaceAnnotationAutorování v prohlížeči, perzistence relace, vestavěné exporty
VyhledáváníVestavěno v prohlížečích prohledávatelných formátů; zahrnuje zdroje pro vyhledáváníSearchNativní textový index, zvýraznění, navigace ve výsledcích
KonvertorNainstalujte Doconut.NETFramework.Converter a zaregistrujte ConverterPluginConverterC# konverzní služba a volitelný webový widget
DICOMNainstalujte Doconut.NETFramework.Dicom a zaregistrujte DicomPluginDicomProhlížení medicínských obrazů pro .dcm a .ima
PodepisovačNainstalujte Doconut.NETFramework.Signer a zaregistrujte SignerPluginSignerViditelné podpisy a digitální pečeti pro PDF a Word: C# služba podepisování a volitelný webový widget

Poznámky a Vyhledávání nepoužívají AddPlugin<TPlugin>(). Konvertor, DICOM a Podepisovač mají každé stránku pod Pluginy se svou konfigurací a použitím. V tomto balíčku DICOM vykresluje stránky, rámečky a animace, ale nečte technická metadata — viz DICOM Plugin.

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

Můžete připojit prohlížeč do pipeline bez psaní balíčku pluginu, přímo v Application_Start:

csharp
Doconut.DoconutHost.Initialize(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 ty 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. Když neposkytnete výchozí konfiguraci, továrna použije ImageConfig.

Závěry

  • Pluginy jsou explicitně registrovány v DoconutHost.Initialize a jejich schopnosti jsou tam ověřovány; chybějící oprávnění zastaví web s prázdným 500, jehož důvod je v protokolu událostí Windows.
  • Pluginy typu override selhávají elegantně; formáty pouze pro plugin selžou s LicenseException.
  • Aktivní dočasná licence odemkne vše; produkční odemkne to, co jste zakoupili. Zkontrolujte pomocí IDoconutLicenseService před nasazením.

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