Converter-Plugin

Dokumente in 45 Zielformate konvertieren

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

OberflächeVerwendung
DocumentConverter (C#)Sie konvertieren auf dem Server, ohne dass ein Browser beteiligt ist
Drop-in widget (doconutConverter.js)Sie möchten einen fertigen Upload-, Konvertierungs- und Download‑Bildschirm in Ihrer Seite
HTTP endpoints (?convert=open|run|download)Sie bauen Ihre eigene Konvertierungs‑UI gegen einen dokumentierten Server‑Vertrag

Paket installieren

Installieren Sie das neueste stabile Converter-Plugin:

bash
dotnet add package Doconut.NET6.Converter

Um das Plugin auf die in dieser Dokumentation beschriebene Version festzulegen, übergeben Sie die Version separat:

bash
dotnet add package Doconut.NET6.Converter --version 26.10.0

Halten Sie das Converter-Paket in derselben Version wie Doconut.NET6. Die Paket-ID ist Doconut.NET6.Converter; .<version> erscheint nur im heruntergeladenen .nupkg-Dateinamen.

Die Lizenzdatei des Plugins, Doconut.Viewer.Converter.lic, kommt in denselben Ordner wie Doconut.Viewer.lic; sie wird zusammen mit der Viewer-Lizenz gelesen.

Plattformen. Das Plugin läuft überall dort, wo Doconut.NET6 läuft: Windows und auf glibc‑basiertem Linux auf x64 (nicht Alpine oder andere musl‑basierte Distributionen). Unter Linux installieren Sie die Schriftkonfigurationsbibliothek, bevor das erste Dokument geöffnet wird:

bash
apt-get update && apt-get install -y libfontconfig1

Unter RHEL, Fedora und ähnlichen Distributionen ist das Paket fontconfig. Ohne dieses schlägt das Öffnen eines Dokuments mit The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. fehl.

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.NET6.Converter, geliefert und zusammen mit dem Basis‑Viewer‑Paket installiert.

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

Das ist alles, was die C#‑Fassade benötigt. Das Widget und seine HTTP‑Endpunkte sind ein separates optionales Feature, AddConverterWidget() (siehe Drop-in‑Widget).

Das Plugin benötigt eine Lizenz, die die Converter‑Fähigkeit gewährt. Ohne eine solche wirft AddDoconut() beim Starten einen InvalidOperationException, bevor die Anwendung eine Anfrage bedient:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

Es wird ausgelöst bei fehlender Lizenz, einer veralteten TRIAL‑Datei, einer Lizenz ohne Converter und einer kostenpflichtigen Lizenz, die außerhalb ihres Versionsfensters verwendet wird. Temporäre Demo/NFR‑Lizenzen werden akzeptiert. Es gibt keine stille kostenlose Stufe. Siehe Lizenz‑Einrichtung für Informationen, wie Lizenzen geladen werden.

Lizenzierung & Wasserzeichen

LizenzstatusStartKonvertierungsausgabe
Kostenpflichtige Viewer‑Lizenz, die Converter gewährt, innerhalb ihres VersionsfenstersStartetSauber — watermarked: false
Aktive temporäre (Demo/NFR) LizenzStartetKonvertiert, mit dem Evaluierungs‑Wasserzeichen — watermarked: true
Abgelaufene temporäre (Demo/NFR) LizenzStartetKonvertiert, mit dem Evaluierungs‑Wasserzeichen — watermarked: true
Keine Lizenz, eine veraltete TRIAL‑Datei, eine Lizenz ohne Converter oder eine kostenpflichtige Lizenz außerhalb ihres VersionsfenstersAddDoconut() wirft—

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 Evaluierungslizenz vor dem Kauf aufgebaut und getestet werden – nur die Ausgabebytes ändern sich.

Eine DICOM‑Quelle (.dcm, .ima) benötigt ebenfalls die Dicom‑Fähigkeit. Ohne diese wirft ConvertAsync einen LicenseException (Converting '.dcm' requires the Dicom capability license.) und der open des Widgets antwortet mit 403.

Verwendung aus C#

Jede Konvertierung gibt ein durchsuchbares MemoryStream zurück, das bei 0 positioniert ist und sofort zum Lesen oder Kopieren bereitsteht. Lösen Sie DocumentConverter aus DI, wo immer Sie es benötigen — es ist per Design zustandslos, sodass eine einzelne Instanz sicher über Anfragen hinweg wiederverwendet werden kann.

csharp
// Inject DocumentConverter; sein Konstruktor ist intern, also nie `new` verwenden.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension enthält den führenden Punkt. password ist null, sofern das Dokument nicht geschützt ist.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: ein Stream, der das HTML enthält, das zurück in ein Word-Dokument umgewandelt werden soll, z. B. das Ergebnis von WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Zwei Details, die leicht falsch zu verstehen sind: sourceExtension bei der Stream-Überladung muss den führenden Punkt enthalten (".xlsx", nicht "xlsx") — der Konverter vergleicht ihn mit dem Formatkatalog und eine reine 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.

Der Aufrufer besitzt den zurückgegebenen Stream und sollte ihn nach dem Kopieren oder Zurückgeben seines Inhalts freigeben. Der DocumentConverter‑Dienst selbst wird aus der Dependency Injection aufgelöst; bauen Sie ihn nicht manuell auf und geben Sie ihn nicht frei.

Zielformate

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

text
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

Nicht jede Quelle lässt sich in jedes Ziel konvertieren — das Plugin ordnet jede Formatfamilie einer Quelle (Word, Excel, PowerPoint, PDF, CAD, Bild, E‑Mail, Diagramm, Projekt/Aufgabe, PSD, Web‑Dokument, DICOM) einem eigenen festen Satz zulässiger Ziele zu. Das Konvertieren einer DICOM‑Quelle (.dcm, .ima) erfordert zudem eine Lizenz, die die Dicom‑Fähigkeit gewährt; ihre Ziele sind Pdf, Png, Jpeg, Bmp, Tiff und Gif. Kodieren Sie dieses Enum nicht fest in die Ziel‑Liste Ihrer UI: ?convert=open gibt das tatsächliche allowedTargets für die gerade hochgeladene Datei zurück, und das sollte die Auswahl steuern.

Drop‑in‑Widget

Endpunkte aktivieren

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:

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

AddConverterWidget() ohne Argument aktiviert das Widget mit den Standardwerten (MaxUploadMb = 25). Es vergibt nicht von selbst Konvertierungsrechte: Es benötigt AddPlugin<ConverterPlugin>(), sonst wirft AddDoconut():

text
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.

Ohne AddConverterWidget() beantworten die drei ?convert=‑Endpunkte 404 — aber die JS‑Datei selbst wird trotzdem ausgeliefert (es ist eine einfache eingebettete statische Ressource; nur die Endpunkte, mit denen sie kommuniziert, sind gesperrt).

Einbetten

html
<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>

Doconut.convert(selectorOrElement, options) nimmt einen CSS‑Selektor oder ein Element, wirft eine Ausnahme, wenn das Ziel nicht gefunden wird, und gibt einen Handle zurück. Das Widget lädt eine Datei hoch, zeigt eine Vorschau von Seite 1, lässt den Benutzer eines der allowedTargets auswählen, konvertiert, zeigt das Ergebnis, wenn möglich, in einer Vorschau und bietet den Download an.

Optionen

OptionTypStandardAnmerkungen
basePathstring/doconutBasis‑Pfad für die ?convert= Endpunkte; er muss mit dem ASP.NET‑Zweig übereinstimmen, in dem UseDoconut() tatsächlich eingebunden ist (normalerweise über MiddlewarePath koordiniert)
resPathstring/doconut-resAkzeptiert zur Konfigurationskonsistenz mit anderen Doconut‑Widgets; das Konverter‑Widget erzeugt derzeit keine URL daraus
maxUploadMbnumber25Nur clientseitige Vorprüfung — lehnt eine zu große Datei vor dem Hochladen ab. Der Server setzt seine eigene Grenze eigenständig durch und antwortet mit 413, wenn sie überschritten wird
licenseUrlstring | nullnullWenn gesetzt, wird der Wasserzeichen‑Hinweis auf dem Ergebnisbildschirm in einen Link zu dieser URL umgewandelt
labelsobject{}Überschreibt beliebige Teilmenge der englischen Standardzeichenketten des Widgets (Drop‑Text, Schaltflächen, aria‑live‑Ankündigungen, Fehlermeldungen)

Rückrufe

RückrufAusgelöst wennNutzdaten
onReady()Das Widget hat seinen Leerlauf‑/Drop‑Bildschirm gerendert—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open erfolgreichQuell‑Sitzungs‑Token, Seitenanzahl, Quell‑Erweiterung (ohne führenden Punkt), erlaubte Ziel‑Liste
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run erfolgreichgleiche Felder wie die Laufantwort, plus das target, das angefordert wurde
onDownload({ downloadName, downloadToken })Der Benutzer klickt auf den Download‑Linkwird zusammen mit dem nativen Download des Browsers ausgelöst — es wird nicht abgefangen oder ersetzt
onError({ phase, message })Ein Öffnen‑ oder Ausführen‑Anfrage schlägt fehlphase ist 'open' oder 'run'; message ist der bereinigte Serverfehler (oder eine clientseitige Meldung für die Vorprüfung der Upload‑Größe)

Ein Rückruf, der eine Ausnahme wirft, wird abgefangen und protokolliert; er unterbricht niemals den Ablauf des Widgets.

Imperativer Zugriff

Doconut.convert() gibt die Widget‑Instanz selbst zurück — halte sie fest, um das Widget programmgesteuert zu steuern:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // eine Datei von Ihrem eigenen <input type="file" id="picker">
conv.reset();         // zurück zum Idle/Drop-Bildschirm; löst onReady nicht erneut aus
conv.loadFile(file);  // startet den Ablauf mit einem File-Objekt; no-op, sofern nicht gerade idle
conv.destroy();       // entfernt Listener, leert das Mount; die Instanz ist danach nicht mehr nutzbar

Beschriftungen

Jede Zeichenkette hat eine englische Vorgabe; labels überschreibt beliebige Teilmenge und der Rest bleibt Englisch. Fragmente, die zur Laufzeit geändert werden, verwenden {placeholders}, wie z.B. uploading: 'Uploading {name}…' und pages: '{n} pages'.

SchlüsselEnglische Vorgabe
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould not reach the server. Please check your connection and try again.

Weitere Schlüssel decken die Drop‑Zone aria-label (dropAriaLabel), die Vorschau alt Texte (previewAlt, resultAlt), die verlinkte Form des Wasserzeichen‑Hinweises, die mit licenseUrl verwendet wird (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), eine nicht lesbare Antwort (badResponse) und die aria-live Ankündigungen (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError) ab.

Ein JSON‑Fehler vom Server wird so angezeigt, wie der Server ihn geschrieben hat; serverError wird nur verwendet, wenn eine fehlgeschlagene Antwort keinen JSON‑Fehler enthält, wie z.B. das 404 eines deaktivierten Widgets.

Gestaltung

Das Widget fügt dem Montage‑Element die Klasse dcw hinzu und liest seine Farben, den Radius und die Schriftart aus CSS‑Custom‑Properties, sodass Sie es thematisieren können, ohne seine Interna zu berühren:

css
#doconut-convert.dcw {
  --dcw-accent: #6b46c1;
  --dcw-radius: 12px;
  --dcw-font: "Inter", system-ui, sans-serif;
}

Standardwerte: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px und eine System‑UI‑Schrift für --dcw-font.

Erstelle dein eigenes Frontend

Das Widget ist lediglich ein Client für diesen HTTP‑Vertrag — bauen Sie Ihr eigenes Frontend direkt dagegen für ein anderes Nutzererlebnis. Alle drei Routen befinden sich im ASP.NET‑Zweig, wo UseDoconut() eingebunden ist (normalerweise /doconut), und sie geben 404 zurück, bis AddConverterWidget() aufgerufen wird. Fehler enthalten einen JSON‑Body, { "error": "..." }, außer dort, wo die Tabelle „nur Status“ angibt. Ein unbekannter ?convert=‑Wert liefert 400.

RouteZweckErfolgsantwort
POST ?convert=open (multipart, one file)Upload und Öffnen eines Quelldokuments zur Vorschau200 — { token, pages, sourceExt, allowedTargets }
POST ?token=<token>&convert=run&target=<ext>Konvertiere die zwischengespeicherte Quelle zu target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET ?convert=download&token=<downloadToken>Streame die konvertierte Datei200 — Dateibytes, Content-Disposition: attachment, Cache-Control: no-store

sourceExt in der open‑Antwort hat keinen führenden Punkt (z. B. "docx") — die gegenteilige Konvention zum sourceExtension‑Parameter bei DocumentConverter.ConvertAsync, der einen Punkt erfordert. allowedTargets listet Zielnamen in Kleinbuchstaben auf ("pdf", "html", …); übergeben Sie einen davon als target, der case‑insensitiv abgeglichen wird. open verwendet die erste Datei im multipart‑Body.

resultToken ist null und resultPages ist 0, wenn das Ergebnis nicht vorgeschaut werden kann. downloadName ist der Quelldateiname mit der Zielerweiterung.

Die Vorschaubilder verwenden die Standard‑Viewer‑Bild‑Route, {basePath}?token={token}&page=1&thumb=1&width={px}, mit dem token von open oder dem resultToken von run. Das Widget fordert width=240 an.

Hochgeladene Quellbytes werden serverseitig zwischengespeichert und für 30 Minuten nach dem letzten Lesen aufbewahrt; sobald dieses Zeitfenster abläuft, gibt run 404 zurück und die Datei muss erneut geöffnet werden. Das konvertierte Ergebnis befindet sich 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 zum Vorschaun des Ergebnisses ist. Wenn das Ergebnis vorschaut werden kann, sind downloadToken und resultToken derselbe Wert. Das Schließen eines Viewer‑Ergebnisses löscht den noch gültigen Download‑Speicher nicht, und das Zurücksetzen des Browser‑Widgets verlängert keines der beiden Zeitfenster nicht.

Fehlermodi, gruppiert nach Route:

RouteStatusWannInhalt
any404Das Widget ist nicht aktiviert (AddConverterWidget() wurde nie aufgerufen) — geprüft, bevor eine der drei Routen verarbeitet wirdnur Status
any405Falsches HTTP‑Verb (open/run erfordern POST; download erfordert GET)nur Status
open400Kein multipart‑UploadExpected a multipart file upload.
open400Keine Datei oder eine leere DateiNo file uploaded.
open400Eine Quell‑Erweiterung, die nicht konvertiert werden kannThis file type cannot be converted.
open403Der Dateityp benötigt eine Fähigkeit, die die Lizenz nicht gewährt (eine DICOM‑Datei ohne Dicom)Converting this file type requires the Dicom capability license.
open413Hochgeladene Datei überschreitet MaxUploadMb, geprüft gegen Content-Length und während das Upload gelesen wirdFile is too large.
run400Fehlerhaftes Token (kein GUID)Invalid token.
run400Ein target, das nicht zu einem ConversionTarget geparst werden kannUnknown target format.
run400target ist nicht im allowedTargets der Quelle enthaltenThat target format is not available for this file.
run404Der zwischengespeicherte Upload ist abgelaufen oder das Token wurde nie geöffnetUpload expired — please re-open the file.
open, run500Interne Verarbeitung fehlgeschlagenEine bereinigte Meldung — bereinigt auf dieselbe Weise wie jeder andere Doconut‑Fehlerpfad; gibt niemals interne Details preis
download400Fehlerhaftes Token (kein GUID)nur Status
download404Unbekanntes oder abgelaufenes Download‑Tokennur Status

Ein vollständiger Rundlauf mit fetch:

javascript
// file: die File, die konvertiert werden soll, zum Beispiel von einem <input type="file">.
async function convertFile(file) {
  const base = '/doconut';

  // 1. open: lade die Datei hoch
  const form = new FormData();
  form.append('file', file, file.name);
  const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
  if (!openResp.ok) throw new Error((await openResp.json()).error);
  const opened = await openResp.json();

  // 2. run: konvertiere zu PDF, wenn es erlaubt ist, sonst zum ersten erlaubten Ziel
  const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
  const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
    '&convert=run&target=' + target, { method: 'POST' });
  if (!runResp.ok) throw new Error((await runResp.json()).error);
  const converted = await runResp.json();

  // 3. download: ein einfacher GET, dem der Browser folgen kann
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

Die Endpunkte sind same-origin: diese Version unterstützt kein CORS. Stellen Sie Ihre UI und das Widget‑Skript vom selben Ursprung wie Doconut bereit, oder reverse‑proxyen Sie beide /doconut‑Pfade (den Middleware‑Pfad und den Ressourcen‑Pfad) unter dem Ursprung Ihrer UI.

In Produktion

  1. Installieren Sie das Plugin neben dem Kernpaket, in derselben Version: dotnet add package Doconut.NET6.Converter.
  2. Fügen Sie die Lizenzdatei hinzu. Platzieren Sie Doconut.Viewer.Converter.lic im selben Ordner wie Doconut.Viewer.lic.
  3. Setzen Sie die Servergrenze. MaxUploadMb in AddConverterWidget ist das Limit, das der Server durchsetzt; das maxUploadMb des Widgets ist nur eine clientseitige Prüfung. Halten Sie beide gleich.
  4. Stellen Sie die UI aus derselben Herkunft bereit wie die Doconut-Endpunkte, oder setzen Sie einen Reverse-Proxy ein (siehe Erstelle dein eigenes Frontend).
  5. Verwerfen Sie Konvertierungsergebnisse. Der von ConvertAsync zurückgegebene Stream wird gepoolt; das Verwerfen gibt seine Puffer zurück in den Pool.

Webfarmen

Das Widget speichert jeden Upload und sein Ergebnis im Speicher des Knotens, der open bereitgestellt hat. Hinter einem Load Balancer ohne Sticky Sessions kann eine spätere run, download oder Vorschau-Anfrage einen anderen Knoten erreichen und den Upload nicht finden. Registrieren Sie den gemeinsamen, verschlüsselten Widget‑Speicher einmalig, nach AddDoconut():

csharp
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // ein Ordner, den jeder Knoten lesen und schreiben kann
    store.FarmKey = farmKey;                   // mindestens 32 bytes, identisch auf jedem Knoten
    // store.Ttl = TimeSpan.FromMinutes(30);   // wie lange ein Upload aufbewahrt wird (der Standard)
});
  • Ein einzelner Server benötigt nichts: Ohne diesen Aufruf wird der In‑Memory‑Speicher verwendet.
  • Uploads und Ergebnisse werden im Ruhezustand auf dem Share verschlüsselt (AES‑256, encrypt‑then‑MAC), und jede Datei ist an ihr Token gebunden, sodass ein Token niemals die Datei eines anderen lesen kann.
  • Auf dem Share wird ein Upload oder Ergebnis für Ttl nach dem Schreiben aufbewahrt; das Lesen verlängert dieses Zeitfenster nicht.
  • FarmKey muss mindestens 32 Bytes groß sein und auf jedem Knoten gleich sein. Laden Sie es aus einem geheimen Speicher; niemals hart codieren. Die Registrierung wirft ein ArgumentException, wenn RootPath fehlt oder FarmKey kürzer als 32 Bytes ist.
  • Zeigen Sie RootPath auf denselben gemeinsamen Ort, den der verteilte Viewer verwendet.

API-Referenz

Die Fassade und die Widget‑Optionen befinden sich im Namespace Doconut; ConversionTarget ist in Doconut.Configs.Conversion. ConverterPlugin ist in Doconut.Plugins.Converter.

DocumentConverter

csharp
public sealed class DocumentConverter
{
    public Task<Stream> ConvertAsync(
        string filePath, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> ConvertAsync(
        Stream source, string sourceExtension, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);

    public Task<Stream> HtmlToWordAsync(
        Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
        CancellationToken ct = default);
}

Wird über Dependency Injection aufgelöst; der Konstruktor ist intern. sourceExtension enthält den führenden Punkt. HtmlToWordAsync schreibt eine .doc‑Datei, wenn outputFormat ConversionTarget.Doc ist, und eine .docx‑Datei für jeden anderen Wert.

ConversionTarget

Die 45 Ausgabeformate, die in Ziel-Formate aufgeführt sind.

ConverterWidgetOptions

csharp
public sealed class ConverterWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
}

Festgelegt über DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), das das DoconutOptions zurückgibt, sodass Aufrufe verkettet werden können.

Fehlersuche

SymptomUrsacheLösung
AddDoconut() wirft The Converter plugin is registered via AddPlugin but no active license grants Converter.Keine Lizenz, eine TRIAL‑Datei, eine Lizenz ohne Converter, oder eine bezahlte Lizenz außerhalb ihres VersionsfenstersInstallieren Sie eine Lizenz, die Converter gewährt, oder entfernen Sie AddPlugin<ConverterPlugin>()
AddDoconut() wirft AddConverterWidget() was called but the Converter plugin is not registered.Das Widget ist aktiviert ohne sein PluginFügen Sie options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() hinzu
Auflösen von DocumentConverter wirft No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().ConverterPlugin ist nicht registriertFügen Sie AddPlugin<ConverterPlugin>() innerhalb von AddDoconut() hinzu
Stream‑Konvertierung sagt, das Format wird nicht unterstütztsourceExtension hat keinen führenden PunktÜbergeben Sie ".xlsx", nicht "xlsx"
ConvertAsync wirft Converting '.dcm' requires the Dicom capability license.Eine DICOM‑Quelle, und die Lizenz gewährt nicht DicomVerwenden Sie eine Lizenz, die Dicom gewährt
Die Ausgabe ist mit Wasserzeichen versehenDie Lizenz ist temporär (Demo/NFR)Verwenden Sie eine bezahlte Lizenz, die Converter gewährt
Das Widget lädt, aber seine Anfragen beantworten 404AddConverterWidget() wurde nicht aufgerufen, oder basePath stimmt nicht mit dem Branch überein, in dem UseDoconut() gemountet istRufen Sie AddConverterWidget() auf; beheben Sie basePath
open antwortet 403 Converting this file type requires the Dicom capability license.Ein DICOM‑Upload, und die Lizenz gewährt nicht DicomVerwenden Sie eine Lizenz, die Dicom gewährt
open antwortet 413 File is too large.Der Upload überschreitet MaxUploadMbErhöhen Sie MaxUploadMb in AddConverterWidget; das maxUploadMb des Widgets ist nur eine clientseitige Prüfung
run antwortet 400 That target format is not available for this file.Das Ziel ist nicht eines der allowedTargets der QuelleBieten Sie nur das allowedTargets von open an
run oder download antwortet 404 (Upload expired — please re-open the file. von run)Das 30‑Minuten‑Fenster ist abgelaufen, oder ein Web‑Farm‑Knoten hat den Upload nichtÖffnen Sie die Datei erneut; in einer Farm, registrieren Sie AddDoconutDistributedWidgets
Das Widget schlägt fehl, wenn die UI auf einer anderen Herkunft istDie Endpunkte unterstützen kein CORSStellen Sie die UI aus derselben Herkunft bereit, oder setzen Sie einen Reverse‑Proxy für die Doconut‑Pfade ein
Das Theme wird nicht angewendetDie Variablen sind auf einem Vorfahren oder auf einem Element innerhalb des Mounts gesetzt; die eigene .dcw‑Regel des Widgets setzt sie auf dem MountZielen Sie auf das Mount selbst: #doconut-convert.dcw oder #doconut-convert

War diese Seite hilfreich?