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 kompletten Service‑Graphen:

Service	Lifetime	Role
`DoconutOptions`	Singleton	Das Konfigurationsobjekt
`IViewerFactory`	Singleton	Ordnet Erweiterungen 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` → Auto‑Suche)
`PageImageService`	Singleton	Seitenbild‑Pipeline (Wasserzeichen/Drehen/Skalieren/Annotationen)
Document security (access store)	Singleton	Berechtigungen für Token‑zu‑Sitzungsbindung
`Viewer`	Transient	Die öffentliche Öffnen/Schließen‑Fassade
`DocumentConverter`	Transient	Konvertierungs‑Fassade — erfordert das Converter‑Plugin
Health check `"doconut"`	—	Berichtet 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 Health‑Check integriert sich in den Standard‑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, Seiten‑Aktionen (die vollständige Anfragetabelle findet sich in Core Concepts → How the Viewer Works). Wenn UnsafeMode false ist, wird die Dokumenten‑Sicherheits‑Schicht automatisch davor eingebunden.

Das Referenz‑Beispiel 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. Das sind die Dateien, für die Viewer.ReferenceCss() / ReferenceScripts() Tags erzeugen.

Rufe es 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 er ist an der falschen Stelle.

Ordering recap

csharp

app.UseRouting();
app.UseSession();          // required when UnsafeMode = false
app.UseDoconutResources(); // 1st Doconut call
app.UseDoconut();          // 2nd Doconut call (or via a MapWhen branch)