DoconutExtensions

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.

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

AddDoconut

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

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

Es gibt keinen entsprechenden Aufruf in der vorherigen .NET Standard-Bibliothek. Sie erzeugte new Viewer(cache, accessor) pro Anfrage und übergab Optionen an die Middleware; beide werden durch diese einzelne Registrierung ersetzt.

Zwei Verhaltensweisen, die es zu kennen gilt:

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

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

• Die Berechtigung des Plugins wird beim Start validiert. Eine fehlende Lizenz, eine veraltete TRIAL-Datei oder eine kostenpflichtige Lizenz ohne die Fähigkeit eines registrierten Plugins schlägt zur Zeit von AddDoconut() fehl. 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:

app.MapHealthChecks("/health");

UseDoconut

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 befindet sich in Kernkonzepte → Wie der Viewer funktioniert). Wenn UnsafeMode false ist, wird die Dokumentensicherheits‑Schicht automatisch davor verdrahtet.

Sie nimmt keine Argumente entgegen. Das Übergeben einer DoconutOptions‑Instanz hier war die Form der vorherigen Bibliothek und kompiliert nicht mehr.

Das Referenzbeispiel leitet die Anfragen des Widgets über einen Pfadzweig, wodurch die historische Anfragestruktur beibehalten wird:

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

UseDoconutResources

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 sie 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.

Dies ist der unterstützte Ersatz für das manuelle Verdrahten der Embedded‑Resource‑Middleware mit app.UseMiddleware<EmbeddedResourceMiddleware>().

Serving from shared storage

Zwei weitere Registrierungen existieren für Deployments, bei denen der Knoten, der ein Dokument rendert, nicht unbedingt der Knoten ist, der dessen Seiten bereitstellt. Beide werden vollständig in Verteilte Bereitstellungen behandelt; die Signaturen lauten:

IServiceCollection AddDoconutDistributedAsyncPublish(...)   // opt-in background publish queue
IServiceCollection AddDoconutDistributedWidgets(...)        // shared backing store for widget uploads

Die Leseseite ist eine separate Middleware aus dem Paket Doconut.Clouds:

IApplicationBuilder UseDoconutCloud<THandler>(
    this IApplicationBuilder app,
    Action<CloudOptions>? configure = null,
    string pathPrefix = "/doconut-cloud")
    where THandler : BaseCloudHandler

UseDoconutWebFarm(...) und WebFarmOptions existieren in dieser Version nicht. Siehe den Migrationsleitfaden für die Einstellung‑für‑Einstellung‑Zuordnung.

Ordering recap

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