Konverter-Plugin

Das Konverter-Plugin verwandelt Doconut in einen Dokumentkonvertierungsdienst. 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 Konverter-Plugin:

dotnet add package Doconut.NET8.Converter

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

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

Halten Sie das Konverter-Paket in derselben Version wie Doconut.NET8. Die Paket-ID lautet Doconut.NET8.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, einschließlich Converter, wird auf dieselbe Weise registriert: Rufen Sie AddPlugin<TPlugin>() innerhalb von AddDoconut() auf. ConverterPlugin wird in seinem eigenen NuGet‑Paket Doconut.NET8.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 Start 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 deren Ablauf bleibt die Konvertierung mit einem Wasserzeichen verfügbar. Es gibt keine stille kostenlose Stufe. Siehe Lizenzsetup für Informationen, wie Lizenzen geladen werden.

Konvertieren aus C#

Jede Konvertierung liefert einen durchsuchbaren 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 ihn mit dem Formatkatalog und ein bloßer Dateiname wird nicht aufgelöst. Und trotz des Namens gibt WordToHtmlAsync ein Task<Stream> zurück, 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 jede Quelle lässt sich in jedes Ziel konvertieren – das Plugin ordnet jede Quell‑Formatfamilie (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document) einem eigenen festen Satz zulässiger Ziele zu. Kodieren Sie dieses Enum nicht fest in Ihrer UI‑Ziel‑Liste: ?convert=open liefert die tatsächlichen allowedTargets für die gerade hochgeladene Datei, und diese sollten Sie für die Auswahl verwenden.

Drop-in-Widget

Die Endpunkte des Widgets ?convert=open|run|download sind optional und standardmäßig deaktiviert – sicherheits­mäßig voreingestellt. 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() beantworten die drei ?convert=‑Endpunkte 404 – die JS‑Datei selbst wird jedoch weiterhin ausgeliefert (es handelt sich um 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 sich aus Konvertierungsrechte.

Widget anpassen

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

Rückrufe:

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‑Bildschirm; löst onReady nicht erneut aus
conv.loadFile(file);  // startet den Ablauf mit einem File‑Objekt; No‑Op, wenn nicht im Leerlauf
conv.destroy();       // entfernt Listener, leert den Mount; die Instanz ist danach unbrauchbar

Eigenes Frontend erstellen

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, in dem UseDoconut() gemountet ist (normalerweise /doconut):

Hochgeladene Quell‑Bytes werden serverseitig mit einem 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 Stash – downloadToken erhält ein frisches 30‑Minuten‑Fenster, sobald die Konvertierung abgeschlossen ist – während resultToken ein gewöhnliches Viewer‑Sitzungs‑Token ist, dessen Lebensdauer der Viewer‑Session‑Cache bestimmt, unabhängig vom Stash.

sourceExt in der open‑Antwort enthält keinen führenden Punkt (z. B. "docx" ) – das ist das Gegenstück zur sourceExtension‑Parameter‑Konvention bei DocumentConverter.ConvertAsync, die einen Punkt erfordert.

Fehlermodi, gruppiert nach Route:

Ressourcenbesitz

Der Konverter gibt einen durchsuchbaren MemoryStream zurück, 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 Service nicht manuell auf und geben Sie ihn nicht frei.

Für das Web‑Widget haben die Upload‑ und Download‑Stashes unabhängige TTLs von 30 Minuten. Ein Viewer‑resultToken folgt der Lebensdauer der Viewer‑Session. Das Schließen eines Viewer‑Ergebnisses löscht einen noch gültigen Download‑Stash nicht, 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) aus, um das zurückgegebene Feld watermarked zu füllen. Eine Integration kann end‑to‑end auf einer Evaluations‑Lizenz aufgebaut und getestet werden, bevor ein Kauf erfolgt – nur die Ausgabebytes ändern sich.