Converter-Plugin

Das Converter‑Plugin verwandelt Doconut in einen Dokument‑Konvertierungsservice. Es stellt die Engine hinter der öffentlichen DocumentConverter‑Fassade bereit und – optional – ein Drop‑in‑Widget mit eigenem HTTP‑Vertrag, sodass Sie Dokumente aus C#, aus dem Widget oder aus einem selbst geschriebenen Frontend konvertieren können.

Paket installieren

Installieren Sie das neueste stabile Converter‑Plugin:

dotnet add package Doconut.NET6.Converter

Um das Plugin auf die aktuelle Version 26.7.0 festzulegen, geben Sie die Version separat an:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Halten Sie das Converter‑Paket in derselben Version wie Doconut.NET6. Die Paket‑ID lautet Doconut.NET6.Converter; .26.7.0 erscheint nur im heruntergeladenen .nupkg‑Dateinamen.

Plugin registrieren

Es gibt keine AddConverter()‑Methode – Doconut’s Plugin‑Modell ist einheitlich. Jedes Plugin, Converter eingeschlossen, wird auf dieselbe Weise registriert: Rufen Sie AddPlugin<TPlugin>() innerhalb von AddDoconut() auf. ConverterPlugin wird in seinem eigenen NuGet‑Paket Doconut.NET6.Converter ausgeliefert, das zusammen mit dem Basis‑Viewer‑Paket installiert wird.

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

Dieser Aufruf wirft beim Starten eine Ausnahme, wenn eine Lizenz fehlt, eine veraltete TRIAL‑Datei vorliegt oder eine nicht‑temporäre Lizenz die Converter‑Fähigkeit nicht gewährt – eine InvalidOperationException, die aus AddDoconut() heraus ausgelöst wird, bevor die Anwendung Anfragen bedient. Temporäre Demo‑/NFR‑Registrierungen werden akzeptiert; nach Ablauf ihres Kalenders bleibt die Konvertierung mit Wasserzeichen‑Ausgabe verfügbar. Es gibt keine stillschweigende Gratis‑Stufe. Siehe Lizenzsetup für das Laden von Lizenzen.

Konvertieren aus C#

Jede Konvertierung liefert einen seek‑fähigen MemoryStream, der bei 0 positioniert ist und sofort gelesen oder kopiert werden kann. Lösen Sie DocumentConverter über DI dort auf, wo Sie ihn benötigen – er ist per Design zustandslos, sodass eine einzelne Instanz sicher über mehrere Anfragen hinweg wiederverwendet werden kann.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Zwei Details, die leicht falsch gemacht werden können: sourceExtension bei der Stream‑Überladung muss den führenden Punkt enthalten (".xlsx", nicht "xlsx" ) – der Konverter vergleicht dies mit dem Formatkatalog und ein bloßer Extension‑String wird nicht aufgelöst. Und trotz des Namens liefert WordToHtmlAsync Task<Stream>, nicht Task<string> – Sie erhalten das HTML‑Dokument (Bilder als Base64 eingebettet) als Stream, genau wie jedes andere Konvertierungsergebnis.

Zielformate

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Nicht jedes Quellformat lässt sich in jedes Zielformat konvertieren – das Plugin ordnet jede Quell‑Formatfamilie (Word, Excel, PowerPoint, PDF, CAD, Bild, E‑Mail, Diagramm, Projekt/Aufgabe, PSD, Web‑Dokument) einem festen Satz zulässiger Ziele zu. Kodieren Sie dieses Enum nicht fest in Ihrer UI: ?convert=open liefert die tatsächlichen allowedTargets für die gerade hochgeladene Datei, und diese sollten die Auswahl bestimmen.

Drop‑in‑Widget

Die Endpunkte des Widgets ?convert=open|run|download sind optional und standardmäßig deaktiviert – sicher per Vorgabe. Aktivieren Sie sie serverseitig zusammen mit der Plugin‑Registrierung:

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

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Ohne AddConverterWidget() antworten die drei ?convert=‑Endpunkte mit 404 – die JS‑Datei selbst wird jedoch weiterhin ausgeliefert (es ist eine einfache eingebettete statische Ressource; nur die Endpunkte, mit denen sie kommuniziert, sind gesperrt). AddConverterWidget() erfordert weiterhin, dass das Converter‑Plugin registriert ist und eine Lizenz vorliegt, die Converter gewährt – es verleiht nicht von selbst Konvertierungsrechte.

Widget anpassen

Initiale Optionen, die an Doconut.convert(selector, options) übergeben werden:

Callbacks:

Doconut.convert() gibt die Widget‑Instanz selbst zurück – behalten Sie sie, um das Widget programmgesteuert zu steuern:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // zurück zum Leerlauf‑/Drop‑Screen; löst onReady nicht erneut aus
conv.loadFile(file);  // startet den Ablauf mit einem File‑Objekt; hat keine Wirkung, wenn nicht im Leerlauf |
conv.destroy();       // entfernt Listener, leert den Mount‑Punkt; die Instanz ist danach unbrauchbar

Eigenes Frontend bauen

Das Widget ist lediglich ein Client für diesen HTTP‑Vertrag – bauen Sie Ihr eigenes Frontend direkt darauf für ein anderes UX. Alle drei Routen liegen unter dem ASP.NET‑Zweig, an dem UseDoconut() gemountet ist (normalerweise /doconut):

Hochgeladene Quellbytes werden serverseitig mit einer TTL von 30 Minuten zwischengespeichert; nach Ablauf dieses Fensters antwortet run mit 404 und die Datei muss erneut geöffnet werden. Das konvertierte Ergebnis verbleibt im selben Speicher – downloadToken erhält sein eigenes frisches 30‑Minuten‑Fenster, sobald die Konvertierung abgeschlossen ist – während resultToken ein gewöhnlicher Viewer‑Sitzungs‑Token ist, dessen Lebensdauer der Viewer‑Sitzungs‑Cache bestimmt, unabhängig vom Zwischenspeicher.

sourceExt in der open‑Antwort hat keinen führenden Punkt (z. B. "docx" ) – das ist das Gegenstück zum Parameter sourceExtension von DocumentConverter.ConvertAsync, der einen Punkt verlangt.

Fehlermodi, gruppiert nach Route:

Ressourcen‑Eigentum

Der Konverter liefert einen seek‑fähigen MemoryStream, der bei Null positioniert ist. Der Aufrufer besitzt diesen Stream und sollte ihn nach dem Kopieren oder Zurückgeben des Inhalts freigeben. Der DocumentConverter‑Dienst selbst ist zustandslos und wird über Dependency Injection aufgelöst; bauen Sie den Dienst nicht manuell auf und geben Sie ihn nicht frei.

Für das Web‑Widget haben die Upload‑ und Download‑Zwischenspeicher unabhängige TTLs von 30 Minuten. Ein Viewer‑resultToken folgt der Lebensdauer der Viewer‑Sitzung. Das Schließen eines Viewer‑Ergebnisses löscht keinen noch gültigen Download‑Zwischenspeicher, und das Zurücksetzen des Browser‑Widgets verlängert keine der beiden TTLs.

Fehlersuche

Wasserzeichen

Mit registriertem ConverterPlugin befindet sich die Lizenz des Hosts in einem von drei Zuständen:

Beide Aufrufpfade berechnen das Flag nach derselben Regel: Die C#‑Fassade DocumentConverter leitet es intern aus den Lizenz‑Eigenschaften IsViewerLicensed und IsTemporary ab, und der Widget‑Handler ?convert=run führt die äquivalente Prüfung (IsViewerLicensed && !IsTrial && !IsTemporary) durch, um das zurückgegebene Feld watermarked zu füllen. Eine Integration kann komplett auf einer Evaluations‑Lizenz aufgebaut und getestet werden, bevor ein Kauf erfolgt – nur die Ausgabebytes ändern sich.