DoconutExtensions – Doconut Dokumentation

DoconutExtensions (Namespace Doconut.Middleware) ist die statische Klasse mit den drei Aufrufen, die jeder Doconut‑Host ausführt: eine Service‑Registrierung und zwei Middleware‑Registrierungen.

csharp

builder.Services.AddDoconut(options => { /* … */ });
// …
app.UseDoconutResources(); // BEFORE UseDoconut()
app.UseDoconut();

AddDoconut

text

IServiceCollection AddDoconut(this IServiceCollection services, Action<DoconutOptions>? configure = null)

Erstellt die DoconutOptions, validiert sie sofort (siehe DoconutOptions → Startup‑Validierung) und registriert den vollständigen Service‑Graphen:

Dienst	Lebensdauer	Rolle
`DoconutOptions`	Singleton	Das Konfigurationsobjekt
`IViewerFactory`	Singleton	Ordnet Erweiterungen den Format‑Viewern zu
`IDocumentSessionManager`	Singleton	Token → Sitzungs‑Cache (`IMemoryCache` ist ebenfalls registriert)
`IDoconutLicenseService`	Singleton	Lizenz wird einmal beim Start geladen (Priorität: `LicenseStream` → `LicenseContent` → `LicensePath` → automatische Suche)
`PageImageService`	Singleton	Seitenbild‑Pipeline (Wasserzeichen/Drehen/Skalieren/Annotationen)
Dokumentensicherheit (Zugriffsspeicher)	Singleton	Berechtigungen für Token‑zu‑Sitzungs‑Verknüpfung
`Viewer`	Transient	Die öffentliche Öffnen/Schließen‑Fassade
`DocumentConverter`	Transient	Konvertierungs‑Fassade — erfordert das Converter‑Plugin
Gesundheitsprüfung `"doconut"`	—	Meldet Lizenz‑/Ablaufstatus über ASP.NET‑Health‑Checks

Zwei Verhaltensweisen, die man kennen sollte:

Converter erfordert sein Plugin. Das Auflösen von DocumentConverter ohne options.AddPlugin<ConverterPlugin>() wirft:

text

InvalidOperationException: No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Plugin‑Berechtigung wird beim Start validiert. Eine fehlende Lizenz, eine veraltete TRIAL‑Datei oder eine bezahlte Lizenz ohne registrierte Plugin‑Fähigkeit führt zur Fehlermeldung zur Zeit von AddDoconut(). Temporäre/Demo‑Registrierungen überleben ihr Ablaufdatum, während Laufzeit‑Gates die abgelaufenen Fähigkeiten entziehen.

Der Gesundheits‑Check integriert sich in den standardmäßigen ASP.NET‑Core‑Mechanismus — mappe ihn, wenn du den Lizenzstatus auf deinem Health‑Endpoint sehen möchtest:

csharp

app.MapHealthChecks("/health");

UseDoconut

text

IApplicationBuilder UseDoconut(this IApplicationBuilder app)

Fügt die Doconut‑Seitenbild‑Middleware hinzu. Sie beantwortet jede Anfrage, die einen ?token=‑Abfrageparameter enthält — Seiten, Thumbnails, Suche, Annotationen, Seitenaktionen (die vollständige Anfragetabelle findet sich in Kernkonzepte → Wie der Viewer funktioniert). Wenn UnsafeMode false ist, wird die Dokumentensicherheits‑Schicht automatisch davor eingebunden.

Das Referenzbeispiel leitet die Widget‑Anfragen über einen Pfad‑Branch weiter:

csharp

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconutResources

text

IApplicationBuilder UseDoconutResources(this IApplicationBuilder app)

Stellt das eingebettete JS, CSS, Bilder und Schriftarten unter DoconutOptions.ResourcesPath (Standard /doconut-res) bereit. Dies sind die Dateien, für die Viewer.ReferenceCss() / ReferenceScripts() Tags erzeugen.

Rufe dies immer vor UseDoconut() auf. Wenn der Viewer‑Bereich leer bleibt und die Browser‑Konsole 404‑Fehler für /doconut-res/... anzeigt, fehlt dieser Aufruf oder ist an der falschen Stelle.

Zusammenfassung der Reihenfolge

csharp

app.UseRouting();
app.UseSession();          // erforderlich, wenn UnsafeMode = false
app.UseDoconutResources(); // 1. Doconut‑Aufruf
app.UseDoconut();          // 2. Doconut‑Aufruf (oder über einen MapWhen‑Branch)