Konverter-Plugin

Das Konverter-Plugin verwandelt Doconut in einen Dokumentkonvertierungsdienst. Es liefert die Engine hinter der öffentlichen DocumentConverter-Fassade und – optional – ein Plug‑in‑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 Konverter-Plugin:

dotnet add package Doconut.NET8.Converter

Um das Plugin an die aktuelle Version 26.7.0 zu binden, 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 ist 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 Konverter, wird auf dieselbe Weise registriert: Rufen Sie AddPlugin<TPlugin>() innerhalb von AddDoconut() auf. ConverterPlugin wird in seinem eigenen NuGet‑Paket, Doconut.NET8.Converter, geliefert und zusammen mit dem Basis‑Viewer‑Paket installiert.

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

Dieser Aufruf wirft beim Start eine Ausnahme bei fehlender Lizenz, einer veralteten TRIAL‑Datei oder einer nicht‑temporären Lizenz, die die Converter‑Fähigkeit nicht gewährt – ein InvalidOperationException, ausgelöst von innen in AddDoconut(), bevor die Anwendung Anfragen bedient. Temporäre Demo/NFR‑Registrierungen werden akzeptiert; nach deren Ablauf bleibt die Konvertierung mit Wasserzeichen‑Ausgabe verfügbar. Es gibt keine stille kostenlose Stufe. Siehe Lizenz‑Setup für Informationen, wie Lizenzen geladen werden.

Konvertieren aus C#

Jede Konvertierung liefert ein durchsuchbares MemoryStream, das bei 0 positioniert ist und sofort gelesen oder kopiert werden kann. Lösen Sie DocumentConverter aus dem DI auf, wo immer Sie es benötigen – es ist per Design zustandslos, sodass eine einzelne Instanz sicher über mehrere Anfragen hinweg wiederverwendet werden kann.

// Inject DocumentConverter; sein Konstruktor ist intern, also niemals `new` verwenden.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension enthält den führenden Punkt. password ist null, es sei denn, das Dokument ist geschützt.
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 eine bloße Erweiterung wird nicht aufgelöst. Und trotz seines Namens gibt WordToHtmlAsync 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 Formatfamilie der Quelle (Word, Excel, PowerPoint, PDF, CAD, Bild, E‑Mail, Diagramm, Projekt/Aufgabe, PSD, Web‑Dokument) ihrem eigenen festen Satz zulässiger Ziele zu. Kodieren Sie dieses Enum nicht fest in die Ziel‑Liste Ihrer UI: ?convert=open liefert das tatsächliche allowedTargets für die gerade hochgeladene Datei, und genau das sollte die Auswahl steuern.

Drop-in-Widget

Die ?convert=open|run|download‑Endpunkte des Widgets 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 – aber die JS‑Datei selbst wird trotzdem 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, die Converter gewährt – sie gewährt nicht von selbst Konvertierungsrechte.

Widget anpassen

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

Callbacks:

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

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // Zurück zum idle/drop screen; löst onReady nicht erneut aus
conv.loadFile(file);  // Startet den Ablauf mit einem File-Objekt; keine Aktion, sofern nicht gerade idle
conv.destroy();       // Entfernt Listener, leert das mount; die Instanz ist danach nicht mehr nutzbar

Eigenes Frontend erstellen

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

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

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

Fehlermodi, gruppiert nach Route:

Ressourcenbesitz

Der Konverter gibt ein seekbares MemoryStream zurück, das 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.

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 DocumentConverter C#‑Fassade 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 watermarked‑Feld 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.