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 Frontend, das Sie selbst schreiben, konvertieren können.
| Oberfläche | Verwendung |
|---|---|
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:
dotnet add package Doconut.NETStandard.ConverterUm das Plugin an die in dieser Dokumentation beschriebene Version zu binden, übergeben Sie die Version separat:
dotnet add package Doconut.NETStandard.Converter --version 26.10.0Halten Sie das Converter-Paket in derselben Version wie Doconut.NETStandard. Die Paket-ID ist
Doconut.NETStandard.Converter; .<version> erscheint nur im heruntergeladenen .nupkg-Dateinamen.
Die Lizenzdatei des Plugins, Doconut.Viewer.Converter.lic, wird im selben Ordner wie Doconut.Viewer.lic abgelegt; sie wird zusammen mit der Viewer‑Lizenz gelesen.
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, geliefert und zusammen mit dem Basis‑Viewer‑Paket installiert.
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 diese wirft AddDoconut() beim Starten einen InvalidOperationException, bevor die Anwendung eine Anfrage bedient:
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.Sie 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 Lizenzsetup für das Laden von Lizenzen.
Lizenzierung & Wasserzeichen
| Lizenzstatus | Start | Konvertierungsausgabe |
|---|---|---|
Kostenpflichtige Viewer‑Lizenz, die Converter gewährt, innerhalb ihres Versionsfensters | Startet | Sauber — watermarked: false |
| Aktive temporäre (Demo/NFR) Lizenz | Startet | Konvertiert, mit dem Evaluations‑Wasserzeichen — watermarked: true |
| Abgelaufene temporäre (Demo/NFR) Lizenz | Startet | Konvertiert, mit dem Evaluations‑Wasserzeichen — watermarked: true |
Keine Lizenz, eine veraltete TRIAL‑Datei, eine Lizenz ohne Converter oder eine kostenpflichtige Lizenz außerhalb ihres Versionsfensters | AddDoconut() 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 Evaluations‑Lizenz 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 sie wirft ConvertAsync einen LicenseException (Converting '.dcm' requires the Dicom capability license.) und der open des Widgets liefert 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 von Grund auf zustandslos, sodass eine einzelne Instanz sicher über mehrere Anfragen hinweg wiederverwendet werden kann.
// Inject DocumentConverter; sein Konstruktor ist intern, also nie `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(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// 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 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 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; erstellen oder entsorgen Sie ihn nicht manuell.
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, IcoNicht 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, 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:
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 gewährt nicht von selbst Konvertierungsrechte: Es benötigt AddPlugin<ConverterPlugin>(), oder AddDoconut() wirft:
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() geben die drei ?convert=‑Endpunkte 404 zurück — 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
<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 einen Fehler, wenn das Ziel nicht gefunden wird, und gibt ein 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
| Option | Typ | Standard | Hinweise |
|---|---|---|---|
basePath | string | /doconut | Basis‑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) |
resPath | string | /doconut-res | Akzeptiert zur Konfigurationskonsistenz mit anderen Doconut‑Widgets; das Konverter‑Widget erzeugt derzeit keine URL daraus |
maxUploadMb | number | 25 | Nur clientseitige Vorprüfung — verwirft eine zu große Datei vor dem Hochladen. Der Server erzwingt seine eigene Begrenzung unabhängig und gibt 413 zurück, wenn sie überschritten wird |
licenseUrl | string | null | null | Wenn gesetzt, wird der Wasserzeichen‑Hinweis auf dem Ergebnisbildschirm in einen Link zu dieser URL umgewandelt |
labels | object | {} | Überschreibt beliebige Teilmenge der englischen Standardzeichenketten des Widgets (Drop‑Text, Schaltflächen, aria‑live‑Ankündigungen, Fehlermeldungen) |
Rückrufe
| Callback | Wird ausgelöst wenn | Nutzdaten |
|---|---|---|
onReady() | Das Widget hat seinen Leerlauf‑/Drop‑Bildschirm gerendert | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open erfolgreich ist | Quell‑Session‑Token, Seitenzahl, Quell‑Erweiterung (ohne führenden Punkt), erlaubte Ziel‑Liste |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | ?convert=run erfolgreich ist | gleiche Felder wie die Laufantwort, plus das angeforderte target |
onDownload({ downloadName, downloadToken }) | Der Benutzer klickt auf den Download‑Link | wird 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 fehl | phase ist 'open' oder 'run'; message ist der bereinigte Serverfehler (oder eine clientseitige Meldung für die Vorprüfung der Upload‑Größe) |
Ein Callback, das einen Fehler wirft, wird abgefangen und protokolliert; es unterbricht niemals den Ablauf des Widgets.
Imperativer Handle
Doconut.convert() gibt die Widget‑Instanz selbst zurück — halte sie fest, um das Widget programmgesteuert zu steuern:
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 Leerlauf/Drop-Bildschirm; löst onReady nicht erneut aus
conv.loadFile(file); // startet den Ablauf mit einem File-Objekt; keine Aktion, sofern nicht gerade im Leerlauf
conv.destroy(); // entfernt Listener, leert das mount; die Instanz ist danach nicht mehr nutzbarBeschriftungen
Jede Zeichenkette hat einen englischen Standard; 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üssel | Englischer Standard |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could 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).
Ein JSON‑Fehler vom Server wird so angezeigt, wie er vom Server geschrieben wurde; 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 benutzerdefinierten CSS‑Eigenschaften, sodass du es thematisieren kannst, ohne seine internen Details zu verändern:
#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 — erstelle ein eigenes Frontend, das direkt dagegen arbeitet, um ein anderes Nutzererlebnis zu bieten. Alle drei Routen befinden sich unter dem 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.
| Route | Zweck | Erfolgsantwort |
|---|---|---|
POST ?convert=open (multipart, one file) | Hochladen und Öffnen eines Quelldokuments zur Vorschau | 200 — { token, pages, sourceExt, allowedTargets } |
POST ?token=<token>&convert=run&target=<ext> | Konvertiere die zwischengespeicherte Quelle zu target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET ?convert=download&token=<downloadToken> | Stelle die konvertierte Datei als Stream bereit | 200 — 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", …); übergebe einen davon als target, wobei die Groß‑/Kleinschreibung ignoriert wird. open verwendet die erste Datei im Multipart‑Body.
resultToken ist null und resultPages ist 0, wenn das Ergebnis nicht angezeigt werden kann. downloadName ist der Quelldateiname mit der Erweiterung des Ziels.
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, liefert run 404 und die Datei muss erneut geöffnet werden. Das konvertierte Ergebnis befindet sich im selben Zwischenspeicher — downloadToken erhält ein frisches 30‑Minuten‑Fenster, sobald die Konvertierung abgeschlossen ist — während resultToken ein gewöhnliches Viewer‑Sitzungs‑Token für die Vorschau des Ergebnisses ist. Wenn das Ergebnis angezeigt werden kann, sind downloadToken und resultToken identisch. Das Schließen eines Viewer‑Ergebnisses löscht den noch gültigen Download‑Zwischenspeicher nicht, und das Zurücksetzen des Browser‑Widgets verlängert keines der beiden Zeitfenster.
Fehlermodi, gruppiert nach Route:
| Route | Status | Wann | Inhalt |
|---|---|---|---|
| beliebig | 404 | Das Widget ist nicht aktiviert (AddConverterWidget() wurde nie aufgerufen) — geprüft, bevor einer der drei Routen verarbeitet wird | nur Status |
| beliebig | 405 | Falsches HTTP‑Verb (open/run benötigen POST; download erfordert GET) | nur Status |
open | 400 | Kein Multipart‑Upload | Expected a multipart file upload. |
open | 400 | Keine Datei oder eine leere Datei | No file uploaded. |
open | 400 | Eine Quell‑Erweiterung, die nicht konvertiert werden kann | This file type cannot be converted. |
open | 403 | Der Dateityp erfordert eine Fähigkeit, die die Lizenz nicht gewährt (eine DICOM‑Datei ohne Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | Hochgeladene Datei überschreitet MaxUploadMb, geprüft gegen Content-Length und während das Hochladen gelesen wird | File is too large. |
run | 400 | Fehlerhaftes Token (kein GUID) | Invalid token. |
run | 400 | Ein target, das nicht zu einem ConversionTarget geparst werden kann | Unknown target format. |
run | 400 | target ist nicht im allowedTargets der Quelle | That target format is not available for this file. |
run | 404 | Der zwischengespeicherte Upload ist abgelaufen oder das Token wurde nie geöffnet | Upload expired — please re-open the file. |
open, run | 500 | Interne Verarbeitung fehlgeschlagen | Eine bereinigte Meldung — bereinigt auf dieselbe Weise wie jeder andere Doconut‑Fehlerpfad; gibt niemals interne Details preis |
download | 400 | Fehlerhaftes Token (kein GUID) | nur Status |
download | 404 | Unbekanntes oder abgelaufenes Download‑Token | nur Status |
Ein vollständiger Durchlauf mit fetch:
// file: die Datei, die konvertiert werden soll, zum Beispiel von einem <input type="file">.
async function convertFile(file) {
const base = '/doconut';
// 1. open: die Datei hochladen
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: nach PDF konvertieren, wenn erlaubt, 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 gleicher Ursprung: diese Version unterstützt kein CORS. Stelle deine UI und das Widget‑Skript vom selben Ursprung wie Doconut bereit, oder reverse‑proxy beide /doconut‑Pfade (den Middleware‑Pfad und den Ressourcen‑Pfad) unter dem Ursprung deiner UI.
In Produktion
- Installieren Sie das Plugin neben dem Kernpaket, in derselben Version:
dotnet add package Doconut.NETStandard.Converter. - Fügen Sie die Lizenzdatei hinzu. Legen Sie
Doconut.Viewer.Converter.licim selben Ordner wieDoconut.Viewer.licab. - Setzen Sie das Server-Limit.
MaxUploadMbinAddConverterWidgetist das vom Server durchgesetzte Limit; dasmaxUploadMbdes Widgets ist nur eine clientseitige Prüfung. Halten Sie beide gleich. - Stellen Sie die UI vom selben Ursprung bereit wie die Doconut-Endpunkte, oder setzen Sie einen Reverse-Proxy ein (siehe Erstellen Sie Ihr eigenes Frontend).
- Verwerfen Sie Konvertierungsergebnisse. Der von
ConvertAsynczurückgegebene Stream ist gepoolt; das Verwerfen gibt seine Puffer an den Pool zurück.
Web-Farmen
Das Widget speichert jeden Upload und dessen Ergebnis im Speicher auf dem Knoten, 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():
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, auf jedem Knoten identisch
// 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
Ttlnach dem Schreiben aufbewahrt; das Lesen verlängert dieses Zeitfenster nicht. FarmKeymuss mindestens 32 Bytes groß sein und auf jedem Knoten gleich sein. Laden Sie es aus einem geheimen Speicher; nie hartkodieren. Die Registrierung wirft einArgumentException, wennRootPathfehlt oderFarmKeykürzer als 32 Bytes ist.- Zeigen Sie
RootPathauf denselben gemeinsamen Speicherort, den der verteilte Viewer verwendet.
API-Referenz
Die Fassade und die Widget-Optionen befinden sich im Doconut-Namespace; ConversionTarget ist in Doconut.Configs.Conversion. ConverterPlugin ist in Doconut.Plugins.Converter.
DocumentConverter
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);
}Aus der 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
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}Durch DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null) festgelegt, das das DoconutOptions zurückgibt, sodass Aufrufe verkettet werden können.
Fehlersuche
| Symptom | Ursache | Behebung |
|---|---|---|
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 Versionsfensters | Installieren 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 ohne sein Plugin aktiviert | Fü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 registriert | Fügen Sie AddPlugin<ConverterPlugin>() innerhalb von AddDoconut() hinzu |
| Stream-Konvertierung sagt, das Format wird nicht unterstützt | sourceExtension 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 Dicom | Verwenden Sie eine Lizenz, die Dicom gewährt |
| Die Ausgabe ist mit Wasserzeichen versehen | Die Lizenz ist temporär (Demo/NFR) | Verwenden Sie eine bezahlte Lizenz, die Converter gewährt |
Das Widget lädt, aber seine Anfragen beantworten 404 | AddConverterWidget() wurde nicht aufgerufen, oder basePath stimmt nicht mit dem Branch überein, in dem UseDoconut() gemountet ist | Rufen 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 Dicom | Verwenden Sie eine Lizenz, die Dicom gewährt |
open antwortet 413 File is too large. | Der Upload überschreitet MaxUploadMb | Erhö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 Quelle | Bieten 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 einem anderen Ursprung ist | Die Endpunkte unterstützen kein CORS | Stellen Sie die UI vom selben Ursprung bereit, oder setzen Sie einen Reverse‑Proxy für die Doconut‑Pfade ein |
| Das Theme wird nicht angewendet | Die Variablen sind auf einem Vorfahren oder auf einem Element innerhalb des Mounts gesetzt; die eigene .dcw-Regel des Widgets setzt sie auf dem Mount | Zielen Sie auf den Mount selbst: #doconut-convert.dcw oder #doconut-convert |
Framework-Notizen
viewer.Converter.GetConverter()existiert hier nicht. Die Konvertierung wird nicht mehr über die Viewer‑Instanz erreicht: StattdessenDoconut.DocumentConverterinjizieren.- Dieses eine
ConversionTarget‑Enum deckt jede Quellfamilie ab. Die vorherige Bibliothek hatte einen pro‑Familie*ConfigConverter‑Typ —WordConfigConverter,ExcelConfigConverterund so weiter — jeweils mit einem eigenen verschachteltenEnTargetFormat‑Enum, plus einSourceFormatConverter‑Enum für die Eingabe. All das ist weg; siehe den Migrationsleitfaden. - Nur Windows, wie der Rest des .NET Standard‑Pakets.
War diese Seite hilfreich?