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 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 einmal 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 markiert, und DoconutHost.Initialize prüft jedes registrierte Plugin gegen die 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 von 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 Anfrage beantwortet ein leeres 500, das IIS‑Protokoll zeigt nichts Nützliches, 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 Lizenzsetup.
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); // Beitragen zu Viewern/Diensten
}Innerhalb von Register akzeptiert der Builder zwei Arten von Beiträgen:
builder.RegisterViewer(extension, factory)— ein Viewer für eine Dateierweiterung; die Fabrik gibt einIFormatViewerzurück (das DICOM‑Plugin registriert auf diese Weise.dcmund.ima),builder.RegisterService<TContract>(() => …)— ein typisierter Service, den andere Teile der Pipeline nachschlagen können.
Fähigkeiten und Steuerung
Fähigkeiten sind die Lizenz‑Einheiten. Converter, Dicom und Signer werden als optional aktivierbare Plugins bereitgestellt; 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 normalerweise ein nicht lizenziertes Plugin aus der Anforderungspipeline fern. Die Viewer‑Fabrik wendet außerdem zwei defensive Regeln an, die wichtig sind, 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 sie greift Doconut auf den integrierten Viewer zurück. Benutzer sehen ihr Dokument weiterhin; sie erhalten jedoch nicht das Verhalten des Plugins.
- Ein ausschließlich von Plugins unterstütztes Format (
.dcmund.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 temporäre 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 gekauft haben. Bei keiner Lizenz wird nichts gewährt — eine fehlende Lizenz ist keine temporäre Lizenz.
Die gleiche Steuerung erreicht den Browser: Viewer.ReferenceScripts() und ReferenceCss() geben die Dateien für lizenzgesteuerte Funktionen (Suche, Annotation) nur dann aus, wenn die Lizenz sie gewährt, sodass die Seite niemals eine Funktion anbietet, die der Server ablehnt.
Funktions‑ und Plugin‑Übersicht
| Funktion | Wie sie aktiviert wird | Fähigkeit | Beiträgt |
|---|---|---|---|
| Annotation | Im Viewer integriert; die Annotations‑Ressourcen einbinden | Annotation | Browser‑Autorierung, Sitzungs‑Persistenz, eingebettete Exporte |
| Suche | In durchsuchbaren Format‑Viewern integriert; die Such‑Ressourcen einbinden | Search | Nativer Text‑Index, Hervorhebungen, Ergebnisnavigation |
| Konverter | Installieren Sie Doconut.NETFramework.Converter und registrieren Sie ConverterPlugin | Converter | C#‑Konvertierungsservice und ein optionales Web‑Widget |
| DICOM | Installieren Sie Doconut.NETFramework.Dicom und registrieren Sie DicomPlugin | Dicom | Anzeige medizinischer Bilder für .dcm und .ima |
| Signer | Installieren Sie Doconut.NETFramework.Signer und registrieren Sie SignerPlugin | Signer | Sichtbare Signaturen und digitale Siegel für PDF und Word: C#‑Signaturservice und ein optionales Web‑Widget |
Annotation und Suche verwenden nicht AddPlugin<TPlugin>(). Konverter, DICOM und Signer 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
});
// 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 — integrierten und Plugins gleichermaßen — und sind nicht lizenzgesteuert: Sie sind Ihr Code. Wenn Sie keine Standardkonfiguration bereitstellen, verwendet die Fabrik ein ImageConfig.
Fazit
- Plugins werden explizit in
DoconutHost.Initializeregistriert, und ihre Fähigkeiten werden dort validiert; ein fehlendes Anrecht stoppt die Site mit einem leeren500, dessen Grund im Windows‑Ereignisprotokoll zu finden ist. - Plugins im Override‑Stil degradieren elegant; ausschließlich von Plugins unterstützte Formate schlagen mit einem
LicenseExceptionfehl. - Eine aktive temporäre Lizenz schaltet alles frei; die Produktionslizenz schaltet das frei, was Sie gekauft haben. Prüfen Sie mit
IDoconutLicenseServicevor dem Ausliefern.
War diese Seite hilfreich?