Plugin-System

Der Kern von Doconut bleibt schlank; optionale Funktionen werden als Plugins bereitgestellt – separate NuGet‑Pakete, die Viewer oder Services beisteuern und durch Ihre Lizenz aktiviert werden. Diese Seite erklärt das Registrierungsmodell, was beim Start passiert, wenn eine Lizenz ein Plugin nicht abdeckt, und wie Sie Ihren eigenen Viewer einbinden können.

Registrieren eines Plugins

Jedes Plugin‑Paket stellt eine Plugin‑Klasse bereit. Registrieren Sie sie einmalig in Application_Start:

Doconut.DoconutHost.Initialize(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});
// Ein registriertes Plugin, dessen Lizenz fehlt, wirft hier, in Application_Start, und die
// Die Seite beantwortet dann jede Anfrage mit einem leeren 500. Der Grund liegt im Windows-Ereignisprotokoll.

AddPlugin<TPlugin>() erstellt das Plugin und lässt es seine Beiträge mit DoconutOptions registrieren. Alles, was ein Plugin beiträgt, wird mit der erforderlichen Fähigkeit des Plugins versehen, und DoconutHost.Initialize prüft jedes registrierte Plugin anhand der Lizenz, bevor die Site ihre erste Anforderung bedient.

Fehlende Plugin‑Lizenz stoppt die Site

Wenn keine aktive Lizenz die Fähigkeit eines registrierten Plugins gewährt – keine Lizenz, eine veraltete TRIAL‑Datei oder eine kostenpflichtige Lizenz ohne diese Fähigkeit – wirft DoconutHost.Initialize InvalidOperationException aus Application_Start:

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.

In System.Web erzeugt eine Ausnahme in Application_Start keine Fehlermeldungsseite. Jede Anforderung beantwortet ein leeres 500, das IIS‑Protokoll liefert keine nützlichen Informationen, und die Meldung erscheint nur im Windows‑Ereignisprotokoll (Anwendungsprotokoll, Quelle ASP.NET). Wenn eine Site nach dem Hinzufügen einer AddPlugin‑Zeile nicht mehr reagiert, prüfen Sie zuerst die Lizenzdateien in wwwroot – siehe Lizenz‑Einrichtung.

Der Vertrag

Ein Plugin implementiert eine bewusst kleine Schnittstelle:

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

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

• builder.RegisterViewer(".dcm", () => new DicomViewer()) — ein Viewer für eine Dateierweiterung,
• builder.RegisterService<TContract>(() => …) — ein typisierter Service, den andere Teile der Pipeline abrufen können.

Fähigkeiten und Gating

Fähigkeiten sind die Lizenz‑Einheiten. Converter und Dicom werden als optional aktivierbare Plugins ausgeliefert; Search und Annotation sind integrierte Funktionen, die auf dieselbe Weise gesteuert werden. Der Basis‑Viewer ist keine Fähigkeit – er ist die Voraussetzung, die als IsViewerLicensed im Lizenz‑Service bereitgestellt wird.

Die Start‑Validierung hält ein nicht lizenziertes Plugin normalerweise aus der Anforderungspipeline fern. Die Viewer‑Factory wendet zudem zwei Schutzregeln an, die wichtig werden, wenn Berechtigungen sich während des Betriebs ändern:

• Ein Plugin, das einen integrierten Viewer überschreibt (es beansprucht eine Erweiterung, die auch ein integrierter Viewer verarbeitet): Ist die Fähigkeit lizenziert, gewinnt der Viewer des Plugins; ohne Lizenz greift Doconut auf den integrierten Viewer zurück. Die Benutzer sehen weiterhin ihr Dokument; sie erhalten jedoch nicht das Verhalten des Plugins.
• Ein ausschließlich von Plugins unterstütztes Format (.dcm und .ima – DICOM hat keinen integrierten Viewer): Ohne die Fähigkeit schlägt das Öffnen fehl:

LicenseException: This document type requires the 'Dicom' plugin license.

Eine aktive Temporary‑Lizenz gewährt jede Fähigkeit. Das ist eine klassische Überraschung beim Go‑Live: dieselben AddPlugin‑Zeilen, die während der Evaluierung liefen, stoppen die Site, wenn die gekaufte Lizenz eine dieser Fähigkeiten weglässt. Vergleichen Sie IsCapabilityGranted(...) mit dem, was Sie vor dem Deployment erworben haben. Ohne jegliche Lizenz wird nichts gewährt – eine fehlende Lizenz ist keine Temporary‑Lizenz.

Das gleiche Gating erreicht den Browser: Viewer.ReferenceScripts() und ReferenceCss() stellen die Dateien für lizenzgesteuerte Funktionen (Suche, Annotation) nur dann bereit, wenn die Lizenz sie gewährt, sodass die Seite niemals eine Funktion anbietet, die der Server ablehnen würde.

Funktions‑ und Plugin‑Übersicht

Annotation und Suche verwenden nicht AddPlugin<TPlugin>(). Converter und DICOM haben jeweils eine Seite unter Plugins mit ihrer Konfiguration und Nutzung. In diesem Paket rendert DICOM Seiten, Frames und Animationen, liest jedoch keine technischen Metadaten – siehe DICOM‑Plugin.

Benutzerdefinierte Viewer – Ihr eigener Format‑Handler

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

Doconut.DoconutHost.Initialize(options =>
{
    options.RegisterViewer(
        ".myext",
        () => new MyCustomViewer(),                        // implementiert IFormatViewer
        () => new ImageConfig { ImageResolution = 150 });  // optionale Standardkonfiguration
});

Benutzerdefinierte Viewer haben Vorrang vor allen – integrierten Viewern und Plugins gleichermaßen – und sind nicht lizenzgesteuert: Sie sind Ihr Code. Wenn Sie keine Standard‑Konfiguration bereitstellen, verwendet die Factory ein ImageConfig.

Fazit

• Plugins werden explizit in DoconutHost.Initialize registriert, und ihre Fähigkeiten werden dort validiert; ein fehlendes Recht stoppt die Site mit einem leeren 500, dessen Grund im Windows‑Ereignisprotokoll zu finden ist.
• Override‑Plugins degradieren elegant; ausschließlich von Plugins unterstützte Formate schlagen mit einem LicenseException fehl.
• Eine aktive Temporary‑Lizenz schaltet alles frei; die Produktionslizenz schaltet das frei, was Sie erworben haben. Prüfen Sie mit IDoconutLicenseService vor dem Versand.