Plugin-System

Erweitern Sie den Viewer mit Plugins

Der Kern von Doconut bleibt schlank; optionale Funktionalität wird als Plugins bereitgestellt — separate NuGet‑Pakete, die Viewer oder Dienste beitragen und durch Ihre Lizenz aktiviert werden. Diese Seite erklärt das Registrierungsmodell, wie die Lizenzgating zur Laufzeit funktioniert und wie Sie Ihren eigenen Viewer einbinden.

Registrieren eines Plugins

Jedes Plugin‑Paket stellt eine Plugin‑Klasse bereit. Sie registrieren es einmal beim Start:

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

AddPlugin<TPlugin>() instanziiert das Plugin und ruft dessen Register Callback im Plugin‑Register auf, das auf DoconutOptions gehalten wird. Alles, was ein Plugin beiträgt, ist mit der erforderlichen Fähigkeit des Plugins gekennzeichnet. AddDoconut() validiert registrierte Plugins sofort: Eine fehlende Lizenz, eine veraltete TRIAL‑Datei oder eine kostenpflichtige Lizenz ohne die Fähigkeit führen zum Fehlschlag beim Start mit InvalidOperationException. Eine Temporäre/Demo‑Registrierung bleibt über das Ablaufdatum erhalten, aber ihre Laufzeitfähigkeiten werden nach dem Ablaufdatum widerrufen.

Der Vertrag

Ein Plugin implementiert eine bewusst kleine Schnittstelle:

csharp
public interface IDoconutPlugin
{
    string Name { get; }                          // z. B. "Doconut DICOM Viewer"
    LicenseCapability RequiredCapability { get; } // das Lizenztor
    void Register(IDoconutPluginBuilder builder); // Viewer/Dienste beitragen
}

Innerhalb von Register akzeptiert der Builder zwei Arten von Beiträgen:

  • builder.RegisterViewer(extension, factory) — ein Viewer für eine Dateierweiterung; die Fabrik gibt ein IFormatViewer zurück (das DICOM‑Plugin registriert .dcm und .ima auf diese Weise),
  • builder.RegisterService<TContract>(() => …) — ein typisierter Dienst, den andere Teile der Pipeline nachschlagen können.

Fähigkeiten und Gating

Fähigkeiten sind die Lizenz‑Einheiten. Converter, Dicom und Signer werden als opt‑in‑Plugins bereitgestellt; Search und Annotation sind eingebaute Funktionen, die auf dieselbe Weise beschränkt werden. Der Basis‑Viewer ist nicht eine Fähigkeit — er ist die Voraussetzung, die als IsViewerLicensed im Lizenz‑Service bereitgestellt wird.

Die Start‑Validierung verhindert normalerweise, dass ein nicht lizenziertes Plugin in die Anforderungspipeline gelangt. Die Viewer‑Fabrik wendet außerdem zwei defensive Laufzeitregeln an, die wichtig sind, wenn sich das Anrecht nach dem Start ändert:

  • Plugin überschreibt einen eingebauten Viewer (ein Plugin beansprucht eine Erweiterung, die das eingebaute Register ebenfalls behandelt): Ist die Fähigkeit lizenziert, gewinnt der Plugin‑Viewer; ohne sie fällt Doconut stillschweigend zum eingebauten Viewer zurück. Benutzer sehen ihr Dokument weiterhin — sie erhalten jedoch nicht die Plugin‑Funktion.
  • Nur‑Plugin‑Format (.dcm und .ima — DICOM hat keinen eingebauten Viewer): Ohne die Fähigkeit schlägt der Öffnungsaufruf hart fehl:
text
LicenseException: This document type requires the 'Dicom' plugin license.

Eine aktive Temporäre Lizenz gewährt jede Fähigkeit (mit sauberer, nicht wasserzeichen‑behafteter Basisansicht). Das ist eine klassische Quelle für Überraschungen beim Go‑Live: Das Registrieren derselben Plugins mit einer gekauften Lizenz, die eine ihrer Fähigkeiten weglässt, lässt AddDoconut() beim Start fehlschlagen. Vergleichen Sie IsCapabilityGranted(...) mit Ihrem Plan, bevor Sie bereitstellen. Das Gegenstück: ohne jegliche Lizenz wird nichts gewährt — eine fehlende Lizenz ist keine Temporäre Lizenz.

Die gleiche Beschränkung erscheint clientseitig: Viewer.ReferenceScripts() und ReferenceCss() geben die Skript‑/Style‑Bundles für die lizenzgesteuerten Funktionen (Suche, Annotation, …) nur dann aus, wenn die Lizenz sie aktiviert, sodass die UI des Widgets konsistent bleibt mit dem, was der Server tatsächlich tut.

Funktions‑ und Plugin‑Übersicht

Die Produkt‑UI verwendet „Plugin“ als breiten Funktionsbegriff, aber die Server‑Registrierung unterscheidet sich:

FunktionWie es aktiviert wirdFähigkeitBeiträgt
AnnotationIm Viewer integriert; Annotation‑Ressourcen einbeziehenAnnotationBrowser‑Autorierung, Sitzungs‑Persistenz und eingebettete Exporte
SucheIn durchsuchbaren Format‑Viewern integriert; Such‑Ressourcen einbeziehen und Extraktion dort aktivieren, wo erforderlichSearchNativer Text‑Index, Hervorhebungen und Ergebnisnavigation
KonverterInstallieren Sie Doconut.NET8.Converter und registrieren Sie ConverterPluginConverterC#‑Konvertierungsservice und optionales Web‑Widget
DICOMInstallieren Sie Doconut.NET8.Dicom und registrieren Sie DicomPluginDicomBetrachtung medizinischer Bilder für .dcm und .ima
SignerInstallieren Sie Doconut.NET8.Signer und registrieren Sie SignerPluginSignerSichtbare Signaturen und digitale Siegel für PDF und Word: C#‑Signaturservice und ein optionales Web‑Widget

Annotation und die normale Suche verwenden nicht AddPlugin<TPlugin>(); ihre Bundles werden nur ausgegeben, wenn die Lizenz die entsprechende Fähigkeit gewährt. Converter, DICOM und Signer sind opt‑in IDoconutPlugin‑Implementierungen.

Veröffentliche Plugin‑Pakete

PluginPaketFähigkeitBeiträgt
KonverterDoconut.NET8.ConverterConverterFähigkeit zur Dokumentkonvertierung
DICOMDoconut.NET8.DicomDicomBetrachtung medizinischer Bilder (.dcm und .ima — nur‑Plugin‑Formate)
SignerDoconut.NET8.SignerSignerPDF‑ und Word‑Signatur

Jedes hat eine eigene Seite unter Plugins mit seiner Konfiguration und Nutzung.

Benutzerdefinierte Viewer — Ihr eigener Format‑Handler

Sie können einen Viewer in die Pipeline einbinden, ohne ein Plugin‑Paket zu schreiben, direkt von Program.cs:

csharp
builder.Services.AddDoconut(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),               // implementiert IFormatViewer
        () => new ImageConfig { ImageResolution = 150 }); // optionale Standardkonfiguration
});

// Der Format-Handler, den die Fabrik erstellt. Ersetzen Sie diese Mitglieder durch Ihre eigene Darstellung.
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() { }
}

Benutzerdefinierte Viewer haben Vorrang vor allen — eingebauten und Plugins gleichermaßen — und sind nicht lizenzgesteuert (sie sind Ihr Code). Die Fabrik greift auf ein ImageConfig zurück, wenn Sie keine Standardkonfiguration bereitstellen.

Fazit

  • Plugins werden explizit registriert und ihr LicenseCapability wird während AddDoconut() validiert — fehlende oder unzureichende nicht‑temporäre Berechtigung schlägt schnell fehl.
  • Override‑Plugins degradieren elegant; nur‑Plugin‑Formate scheitern mit einem LicenseException.
  • Eine aktive Temporäre Lizenz schaltet alles frei; die Produktionslizenz schaltet das frei, was Sie gekauft haben. Überprüfen Sie dies mit IDoconutLicenseService vor dem Ausliefern.

War diese Seite hilfreich?