Doconut Drop‑in‑Konverter‑Widget in .NET 8 registrieren und aktivieren

Das Drop‑in‑Widget ist Doconut’s fertige UI zum Hochladen einer Datei, Ausführen einer Konvertierung und Herunterladen des Ergebnisses.
Standardmäßig geben die drei ?convert= Endpunkte des Widgets 404 zurück; sie werden erst aktiv, wenn Sie das Converter‑Plugin registrieren und AddConverterWidget() auf DoconutOptions aufrufen.

Unten finden Sie eine vollständige, sofort einsetzbare Start‑Konfiguration, die beide Anforderungen erfüllt.

---

1. Voraussetzungen – Lizenz und Sitzungsunterstützung

• Lizenz – Das Converter‑Plugin benötigt eine Lizenz, die die Converter‑Funktionalität gewährt. Platzieren Sie die Datei (z. B. Doconut.Viewer.lic) an einem für die Anwendung erreichbaren Ort und verweisen Sie mit DoconutOptions.LicensePath darauf.
• Sitzungszustand – Doconut’s Sicherheitsmodell speichert Dokument‑Sitzungs‑Tokens im ASP.NET‑Core‑Session. Fügen Sie einen verteilten Cache hinzu und AddSession(), bevor die Middleware verkabelt wird.

builder.Services.AddDistributedMemoryCache();   // erforderlich für die Sitzung
builder.Services.AddSession();                  // ermöglicht IDistributedCache‑basierte Sitzung

---

2. Kern‑Doconut‑Dienste registrieren

AddDoconut() ist der einzige Einstiegspunkt, der den Viewer, den Lizenz‑Service und das Plugin‑Register injiziert.

builder.Services.AddDoconut(options =>
{
    // Teile Doconut mit, wo die Lizenzdatei zu finden ist.
    options.LicensePath = "Doconut.Viewer.lic";

    // Registriere das Converter-Plugin – dies validiert außerdem die Lizenzfähigkeit.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Wenn die Lizenz die Converter‑Funktionalität nicht enthält, wirft der obige Aufruf InvalidOperationException und die Anwendung startet nicht. Dieses Fail‑Fast‑Verhalten verhindert, dass Sie ein fehl‑lizenziertes Build bereitstellen.

---

3. Das Widget mit AddConverterWidget aktivieren

Das Widget ist optional. Der Aufruf von AddConverterWidget() registriert die drei Konvertierungs‑Endpunkte (?convert=open, ?convert=run, ?convert=download) und verbindet eine kleine Menge clientseitiger Konfiguration (maximale Upload‑Größe, Basis‑Pfade usw.).

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();

    // Aktiviere die Drop‑in-Benutzeroberfläche und setze das clientseitige Upload‑Limit.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // Client‑Vorprüfung; Server erzwingt sein eigenes Limit
    });
});

Nur der Aufruf von AddConverterWidget erstellt die Endpunkte; die statische JavaScript‑Datei (doconutConverter.js) wird stets als eingebettete Ressource bereitgestellt, aber sie kann den Server nicht erreichen, wenn die Endpunkte fehlen.

---

4. Middleware in der richtigen Reihenfolge verkabeln

Die Middleware, die statische Assets bereitstellt (UseDoconutResources), muss vor der abschließenden Viewer‑Middleware (UseDoconut) ausgeführt werden. Die Session‑Middleware muss ebenfalls früher platziert werden, da Doconut die Sitzung bei jeder Anfrage validiert.

app.UseSession();           // muss UseDoconut() vorausgehen
app.UseDoconutResources();  // liefert JS, CSS, Bilder
app.UseDoconut();           // verarbeitet ?convert= und Dokumentseiten‑Anfragen

Mit dieser Pipeline funktioniert eine Anfrage an /doconut-res/doconutConverter.js, und das Widget kann /doconut?convert=open, /doconut?convert=run und /doconut?convert=download aufrufen.

---

5. Was das Widget tatsächlich tut

Phase	Server‑Endpunkt	Typische Antwort
Öffnen	?convert=open	Gibt eine JSON‑Payload zurück, die ein token, Seitenzahl, Quell‑Erweiterung und die Liste der erlaubten Ziel‑Formate enthält.
Ausführen	?convert=run	Startet die Konvertierung und gibt ein downloadToken, die Ergebnis‑Seitenzahl, einen vorgeschlagenen Dateinamen und ein Flag zurück, das angibt, ob die Ausgabe mit Wasserzeichen versehen ist.
Herunterladen	?convert=download	Streamt die konvertierte Datei, wenn der Client der bereitgestellten Download‑URL folgt.

Clientseitig führt das Widget eine Vor‑Upload‑Größenprüfung gegen widget.MaxUploadMb durch. Überschreitet die Datei dieses Limit, bricht das Widget den Upload ab und löst den onError‑Callback mit phase = "open" und einer freundlichen Meldung aus. Der Server erzwingt sein eigenes Limit und antwortet mit 413 Payload Too Large, wenn die Anfrage die Client‑Prüfung umgeht.

---

6. Anbinden von Widget‑Ereignissen (C#‑Seite nicht erforderlich)

Alle Callbacks (onReady, onSourceLoaded, onConverted, onError usw.) sind JavaScript‑Funktionen, die von der Seite bereitgestellt werden, die das Widget hostet. Da die Frage den Registrierungs‑Teil fokussiert, müssen Sie keinen zusätzlichen C#‑Code schreiben, um diese Callbacks zu behandeln – das Widget ruft sie automatisch auf, sobald die Endpunkte aktiv sind.

---

7. Häufige Fallstricke und wie man sie vermeidet

Symptom	Wahrscheinliche Ursache	Lösung
404 auf /doconut?convert=open	AddConverterWidget() wurde weggelassen.	Fügen Sie den Aufruf wie in Abschnitt 3 gezeigt hinzu.
Anwendung startet nicht mit InvalidOperationException wegen fehlender Fähigkeit	Lizenzdatei gewährt nicht Converter.	Beschaffen Sie eine Lizenz, die die Converter‑Fähigkeit enthält.
Sitzungsbezogener 500‑Fehler	UseSession() wurde nach UseDoconut() platziert oder Cache‑Registrierung fehlt.	Stellen Sie sicher, dass app.UseSession() vor app.UseDoconut() ausgeführt wird und ein Cache‑Dienst registriert ist.

---

8. Anwendung ausführen und das Widget in Aktion sehen

1. Bauen und starten Sie das ASP.NET‑Core‑Projekt.
2. Öffnen Sie eine Seite, die ein <div id="doconut-convert"></div>‑Element enthält und das Doconut‑Konverter‑Script einbindet (das Script wird automatisch von /doconut-res/doconutConverter.js bereitgestellt).
3. Ziehen Sie eine unterstützte Datei (PDF, DOCX, DWG usw.) in den Drop‑Bereich.
4. Das Widget ruft ?convert=open auf, dann ?convert=run und präsentiert schließlich einen Download‑Link, der auf ?convert=download zeigt.

Wenn die drei Endpunkte mit JSON statt 404 antworten, ist das Widget korrekt registriert und bereit für den Produktionseinsatz.

Nächster Schritt: Fügen Sie die obigen Code‑Snippets zu Ihrem Program.cs (oder Startup.cs) hinzu, prüfen Sie, dass die Lizenzdatei vorhanden ist, und starten Sie die Anwendung. Das Drop‑in‑Konverter‑Widget wird ohne weitere serverseitige Änderungen aktiv sein.