Konverter-Plugin

Das Konverter-Plugin verwandelt Doconut in einen Dokumentkonvertierungsdienst. Es liefert die Engine hinter der öffentlichen DocumentConverter‑Fassade und – optional – ein sofort einsetzbares Widget mit eigenem HTTP‑Vertrag, sodass Sie Dokumente aus C#, aus dem Widget oder aus einem von Ihnen selbst geschriebenen Frontend konvertieren können.

Paket installieren

Installieren Sie das neueste stabile Converter-Plugin:

dotnet add package Doconut.NETStandard.Converter

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

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

Halten Sie das Converter-Paket in derselben Version wie Doconut.NETStandard. Die Paket-ID lautet Doconut.NETStandard.Converter; .26.8.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.NETStandard.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 vorhanden ist oder eine nicht‑temporäre Lizenz, die 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 ihrem Ablauf bleibt die Konvertierung mit einem Wasserzeichen‑Ausgabe verfügbar. Es gibt keine stille Gratis‑Stufe. Siehe Lizenzsetup für Informationen, wie Lizenzen geladen werden.

Konvertieren aus C#

Jede Konvertierung gibt einen durchsuchbaren MemoryStream zurück, der bei 0 positioniert ist und sofort gelesen oder kopiert werden kann. Holen Sie DocumentConverter aus dem DI‑Container, wo immer Sie ihn benötigen – er ist von Grund auf zustandslos, sodass eine einzelne Instanz sicher über mehrere Anfragen hinweg wiederverwendet werden kann.

viewer.Converter.GetConverter() gibt es hier nicht. Die Konvertierung wird nicht mehr über die Viewer‑Instanz aufgerufen: Injizieren Sie stattdessen Doconut.DocumentConverter.

// 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" statt "xlsx" ) – der Konverter vergleicht ihn mit dem Formatkatalog und eine reine Erweiterung wird nicht aufgelöst. Und trotz seines Namens gibt WordToHtmlAsync ein Task<Stream> zurück, nicht ein Task<string> – Sie erhalten das HTML‑Dokument (Bilder als Base64 eingebettet) als Stream, genau wie jedes andere Konvertierungsergebnis.

Zielformate

ConversionTarget (Namespace Doconut.Configs.Conversion) hat 45 Mitglieder:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

Dieses eine Enum deckt jede Quellfamilie ab. Die vorherige Bibliothek hatte für jede Familie einen eigenen *ConfigConverter‑Typ – WordConfigConverter, ExcelConfigConverter usw. – jeweils mit einem eigenen verschachtelten EnTargetFormat‑Enum sowie einem SourceFormatConverter‑Enum für die Eingabe. All das ist verschwunden; siehe den Migrationsleitfaden.

Nicht jede Quelle lässt sich in jedes Ziel konvertieren – das Plugin ordnet jeder Formatfamilie der Quelle (Word, Excel, PowerPoint, PDF, CAD, Bild, E‑Mail, Diagramm, Projekt/Aufgabe, PSD, Web‑Dokument) ihr eigenes festes Set zulässiger Ziele zu. Kodieren Sie dieses Enum nicht fest in die Ziel‑Liste Ihrer UI: ?convert=open liefert die tatsächlichen allowedTargets für die gerade hochgeladene Datei, und diese sollten den Picker steuern.

Drop-in-Widget

Die Endpunkte des Widgets ?convert=open|run|download sind standardmäßig optional und 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() geben die drei ?convert=‑Endpunkte 404 zurück — die JS‑Datei wird jedoch weiterhin ausgeliefert (es handelt sich um eine einfache eingebettete statische Ressource; nur die Endpunkte, zu denen sie kommuniziert, sind gesperrt). AddConverterWidget() erfordert weiterhin, dass das Converter‑Plugin registriert ist und eine Lizenz vorhanden ist, die Converter gewährt — es verleiht nicht von selbst Konvertierungsrechte.

Widget anpassen

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

Rückruffunktionen:

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; keine Aktion, 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 — erstellen Sie ein eigenes Frontend, das direkt darauf zugreift, für ein anderes UX. Alle drei Routen befinden sich unter dem ASP.NET‑Zweig, an dem UseDoconut() eingebunden ist (normalerweise /doconut):

Hochgeladene Quellbytes werden serverseitig mit einer TTL von 30 Minuten zwischengespeichert; sobald dieses Zeitfenster abläuft, gibt run 404 zurück und die Datei muss erneut geöffnet werden. Das konvertierte Ergebnis verbleibt im selben Zwischenspeicher — downloadToken erhält ein eigenes frisches 30‑Minuten‑Fenster, wenn die Konvertierung abgeschlossen ist — während resultToken ein gewöhnliches Viewer‑Session‑Token ist, dessen Lebensdauer dem Session‑Cache des Viewers folgt, unabhängig vom Zwischenspeicher.

sourceExt in der open‑Antwort hat keinen führenden Punkt (z. B. "docx") — die gegenteilige Konvention zum Parameter sourceExtension bei DocumentConverter.ConvertAsync, der einen Punkt erfordert.

Fehlermodi, nach Route gruppiert:

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 seines Inhalts freigeben. Der DocumentConverter‑Dienst selbst ist zustandslos und wird über Dependency Injection aufgelöst; erstellen oder entsorgen Sie den Dienst nicht manuell.

Für das Web‑Widget haben die Upload‑ und Download‑Zwischenspeicher unabhängige TTLs von 30 Minuten. Ein Viewer‑resultToken folgt stattdessen 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.

Fehlerbehebung

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 des DocumentConverter leitet es intern aus dem IsViewerLicensed‑ und IsTemporary‑Zustand der Lizenz ab, und der ?convert=run‑Handler des Widgets führt die äquivalente Prüfung (IsViewerLicensed && !IsTrial && !IsTemporary) durch, um das zurückgegebene Feld watermarked zu füllen. Eine Integration kann end‑to‑end auf einer Evaluations‑Lizenz vor dem Kauf aufgebaut und getestet werden — nur die Ausgabebytes ändern sich.