Konverter-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, das von DocImage.axd bereitgestellt wird, sodass Sie Dokumente aus C#, vom Widget oder von 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-Endpunkte auf DocImage.axd (?convert=open|run|download) | Sie bauen Ihre eigene Konvertierungs‑UI gegen einen dokumentierten Server‑Vertrag |
Paket installieren
Install-Package Doconut.NETFramework.ConverterUm das Plugin an die in dieser Dokumentation beschriebene Version zu binden:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0Bewahren Sie das Converter-Paket in derselben Version wie Doconut.NETFramework.
Die Lizenzdatei des Plugins, Doconut.Viewer.Converter.lic, kommt in denselben Ordner wie Doconut.Viewer.lic; sie wird zusammen mit der Viewer-Lizenz gelesen.
Plugin registrieren
Jedes Plugin wird auf dieselbe Weise registriert: AddPlugin<TPlugin>() in DoconutHost.Initialize, aufgerufen von Application_Start.
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/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 DoconutHost.Initialize von Application_Start aus:
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.In System.Web bedeutet das, dass jede Anfrage ein leeres 500 zurückgibt, und der Grund ist nur im Windows-Ereignisprotokoll (Quelle ASP.NET) zu finden. Es wirft 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. Siehe Lizenzsetup.
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 Evaluierungs-Wasserzeichen — watermarked: true |
| Abgelaufene temporäre (Demo/NFR) Lizenz | Startet | Konvertiert, mit dem Evaluierungs-Wasserzeichen — watermarked: true |
Keine Lizenz, eine veraltete TRIAL-Datei, eine Lizenz ohne Converter oder eine kostenpflichtige Lizenz außerhalb ihres Versionsfensters | Application_Start wirft; jede Anfrage gibt ein leeres 500 zurück | — |
Die DocumentConverter-Fassade und der ?convert=run-Handler des Widgets wenden dieselbe Regel an. 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 sie 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. DocumentConverter ist zustandslos: Lösen Sie es aus DoconutHost.Services, wo immer Sie es benötigen, und verwenden Sie es frei wieder.
// Löse DocumentConverter aus DoconutHost.Services auf; 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 zu verstehen sind: sourceExtension bei der Stream‑Überladung muss den führenden Punkt enthalten (".xlsx", nicht "xlsx"), sonst wird es nicht aufgelöst. Und trotz seines Namens gibt WordToHtmlAsync Task<Stream> zurück, nicht Task<string> — das HTML‑Dokument (Bilder als Base64 eingebettet) kommt als Stream, wie jedes andere Ergebnis.
Der Aufrufer besitzt das MemoryStream, das eine Konvertierung zurückgibt, und sollte es nach dem Kopieren oder Zurückgeben entsorgen (MVCs File(stream, …) entsorgt es für Sie). Konstruieren oder entsorgen Sie DocumentConverter nicht selbst — sein Konstruktor ist intern.
In einem MVC 5‑Controller
Machen Sie die Aktion asynchron und await die Konvertierung:
[HttpPost]
public async Task<ActionResult> ToPdf(HttpPostedFileBase file)
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
Stream pdf = await converter.ConvertAsync(
file.InputStream, Path.GetExtension(file.FileName), ConversionTarget.Pdf,
password: null, ct: Response.ClientDisconnectedToken);
return File(pdf, "application/pdf", Path.GetFileNameWithoutExtension(file.FileName) + ".pdf");
}In Web Forms: Nie bei einer Konvertierung blockieren
Eine Web‑Forms‑Seite läuft in einem single‑threaded Request‑Kontext. ConvertAsync wird in diesem Kontext fortgesetzt, wenn sie abgeschlossen ist, sodass eine Seite, die synchron darauf wartet — .Result, .Wait(), .GetAwaiter().GetResult() — den exakt gleichen Thread blockiert, den die Konvertierung zum Abschluss benötigt. Die Anforderung kehrt nie zurück. Der Browser dreht sich weiter, IIS protokolliert nichts, und der Rest der Seite funktioniert weiter, sodass es wie eine langsame Konvertierung aussieht und nicht wie ein Deadlock.
Markieren Sie die Seite Async="true" und führen Sie die Konvertierung als asynchronen Seiten‑Task aus:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms: die @Page-Direktive benötigt Async="true", und die Konvertierung läuft als asynchroner Seiten-Task.
// Das Blockieren darauf stattdessen (.Result, .Wait(), .GetAwaiter().GetResult()) führt zu einem Deadlock der Anforderung:
// sie kehrt nie zurück, und es wird nichts protokolliert.
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack) return;
RegisterAsyncTask(new PageAsyncTask(async ct =>
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
using (var pdf = await converter.ConvertAsync(
Server.MapPath("~/App_Data/contract.docx"), ConversionTarget.Pdf, ct: ct))
using (var ms = new MemoryStream())
{
if (pdf.CanSeek) pdf.Position = 0;
await pdf.CopyToAsync(ms);
Response.ContentType = "application/pdf";
Response.AddHeader("Content-Disposition", "attachment; filename=contract.pdf");
Response.BinaryWrite(ms.ToArray());
// Context, nicht HttpContext.Current: nach einem await kann Letzteres null sein.
Context.ApplicationInstance.CompleteRequest();
}
}));
}Ohne Async="true" in der @Page‑Direktive wird RegisterAsyncTask stillschweigend ignoriert. Nach einem await verwenden Sie das Context der Seite; HttpContext.Current kann dort null sein.
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: Jede Formatfamilie einer Quelle (Word, Excel, PowerPoint, PDF, CAD, Bild, E‑Mail, Diagramm, Projekt, PSD, Web‑Dokument, DICOM) hat ihre eigene Menge zulässiger Ziele. 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 diese Aufzählung nicht hart in die Ziel‑Liste Ihrer UI: ?convert=open liefert das allowedTargets für die hochgeladene Datei, und das sollte den Picker bestimmen.
Drop‑in‑Widget
Endpunkte aktivieren
Die ?convert=open|run|download‑Endpunkte des Widgets werden von DocImage.axd bereitgestellt und sind standardmäßig deaktiviert. Aktivieren Sie sie neben der Plugin‑Registrierung:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget(widget =>
{
widget.MaxUploadMb = 25;
});
});
// System.Web liest den gesamten Upload, bevor Doconut ihn sieht: behalten Sie maxRequestLength (KB) und
// maxAllowedContentLength (bytes) in Web.config über dem MaxUploadMb des Widgets.AddConverterWidget() ohne Argument aktiviert das Widget mit den Standardwerten (MaxUploadMb = 25). Es erteilt nicht von selbst Konvertierungsrechte: Es benötigt AddPlugin<ConverterPlugin>(), oder DoconutHost.Initialize 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.Zwei Dinge, die Sie prüfen sollten, wenn das Widget Fehlverhalten zeigt:
basePath: '/DocImage.axd'. Der Standard des Widgets,/doconut, ist der ASP.NET‑Core‑Endpunkt. In diesem Paket sind die Endpunkte derDocImage.axd‑Handler vonWeb.config.- Das Skript und die Endpunkte sind unabhängig. Das Ressourcenmodul liefert
doconutConverter.js, unabhängig davon, ob das Widget aktiviert ist. OhneAddConverterWidget()lädt das Widget, zeichnet seine Drop‑Zone und sieht völlig korrekt aus — und seine erste Aktion beantwortet404.
Upload‑Grenzen
ASP.NET liest den gesamten Anforderungstext, bevor DocImage.axd ausgeführt wird. Ein Upload über MaxUploadMb, aber unterhalb der Host‑Grenzen, erhält das eigene JSON des Widgets 413 (File is too large.). Ein Upload, der die Host‑Grenzen überschreitet, wird zuerst von IIS abgelehnt, mit einer Fehlermeldungsseite, die das Widget nicht lesen kann. Behalte beide Host‑Grenzen in Web.config über dem Limit des Widgets:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Einbetten
<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd', 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 | Die Endpunkt‑URL. Setze '/DocImage.axd' in diesem Paket |
resPath | string | /doconut-res | Akzeptiert zur Konsistenz mit anderen Doconut‑Widgets; das Konverter‑Widget erzeugt daraus keine URL |
maxUploadMb | number | 25 | Nur clientseitige Vorprüfung; der Server erzwingt sein eigenes Limit |
licenseUrl | string | null | null | Wandelt den Wasserzeichen‑Hinweis auf dem Ergebnisbildschirm in einen Link um |
labels | object | {} | Überschreibt jede Teilmenge der englischen Zeichenketten des Widgets |
Rückrufe
| Rückruf | Wird ausgelöst, wenn | Nutzdaten |
|---|---|---|
onReady() | Das Widget hat seinen Drop‑Bildschirm gerendert | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | wenn ?convert=open erfolgreich ist | Quell‑Token, Seitenzahl, Quell‑Erweiterung (ohne führenden Punkt), erlaubte Ziele |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | wenn ?convert=run erfolgreich ist | Die Ausführungs‑Antwort plus das angeforderte target |
onDownload({ downloadName, downloadToken }) | Der Benutzer klickt auf Download | Wird zusammen mit dem eigenen Download des Browsers ausgelöst |
onError({ phase, message }) | Eine Öffnen‑ oder Ausführen‑Anfrage schlägt fehl | phase ist 'open' oder 'run'; message ist der bereinigte Server‑Fehler |
Ein Rückruf, der einen Fehler wirft, wird abgefangen und protokolliert; er unterbricht niemals den Ablauf des Widgets.
Imperativer Handle
Doconut.convert() gibt die Widget‑Instanz zurück:
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // eine File von Ihrem eigenen <input type="file" id="picker">
conv.reset(); // zurück zum Drop-Bildschirm; löst onReady nicht erneut aus
conv.loadFile(file); // startet den Ablauf mit einer File; no-op, sofern das Widget nicht auf seinem Drop-Bildschirm ist
conv.destroy(); // entfernt listeners, leert das mount; die instance ist danach nicht mehr verwendbarBeschriftungen
Jede Zeichenkette hat eine englische Vorgabe; labels überschreibt jede 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 | Englische Vorgabe |
|---|---|
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 betreffen 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 zum Beispiel das 404 eines deaktivierten Widgets.
Themen
Das Widget fügt dem Montage‑Element die Klasse dcw hinzu und liest seine Farben, den Radius und die Schriftart aus CSS‑Benutzerdefinierten Eigenschaften, sodass du es thematisieren kannst, ohne seine Interna zu berühren:
#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 ein Client für diesen HTTP‑Vertrag auf DocImage.axd. Die Routen 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 /DocImage.axd?convert=open (multipart, one file) | Hochladen und Öffnen eines Quelldokuments | 200 — { token, pages, sourceExt, allowedTargets } |
POST /DocImage.axd?token=<token>&convert=run&target=<ext> | Konvertiere die hochgeladene Quelle zu target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET /DocImage.axd?convert=download&token=<downloadToken> | Stelle die konvertierte Datei als Stream bereit | 200 — die Datei, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt in der open‑Antwort hat keinen führenden Punkt ("docx") — das Gegenteil des sourceExtension‑Parameters von ConvertAsync. allowedTargets listet Zielnamen in Kleinbuchstaben auf ("pdf", "html", …); übergebe 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 angezeigt werden kann. downloadName ist der Quelldateiname mit der Erweiterung des Ziels.
Die Vorschaubilder verwenden die Standard‑Viewer‑Bild‑Route, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, mit dem token von open oder dem resultToken von run. Das Widget fragt nach width=240.
Hochgeladene Quellen werden 30 Minuten lang nach dem letzten Lesen aufbewahrt; danach liefert run 404 und die Datei muss erneut geöffnet werden. downloadToken erhält sein eigenes 30‑Minuten‑Fenster, wenn die Konvertierung abgeschlossen ist. resultToken ist ein gewöhnliches Viewer‑Token zum Vorsehen des Ergebnisses; wenn das Ergebnis angezeigt werden kann, ist es derselbe Wert wie downloadToken.
| Route | Status | Wann | Inhalt |
|---|---|---|---|
| beliebig | 404 | Das Widget ist nicht aktiviert (AddConverterWidget() wurde nie aufgerufen) | nur Status |
| beliebig | 405 | Falsches Verb (open/run erfordern POST, download erfordert GET) | nur Status |
open | 400 | Kein Multipart‑Upload | Expected a multipart file upload. |
open | 400 | Keine Datei oder eine leere | No file uploaded. |
open | 400 | Ein Typ, der nicht konvertiert werden kann | This file type cannot be converted. |
open | 403 | Der 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. |
open | 413 | Der Upload überschreitet MaxUploadMb (aber nicht die IIS‑Grenzen) | File is too large. |
run | 400 | Ein fehlerhaftes Token (kein GUID) | Invalid token. |
run | 400 | Ein target, das nicht zu einem ConversionTarget geparst werden kann | Unknown target format. |
run | 400 | Ein Ziel, das nicht in allowedTargets enthalten ist | That target format is not available for this file. |
run | 404 | Der Upload ist abgelaufen oder wurde nie geöffnet | Upload expired — please re-open the file. |
open, run | 500 | Verarbeitung fehlgeschlagen | Eine bereinigte Meldung |
download | 400 / 404 | Ein fehlerhaftes, unbekanntes oder abgelaufenes Download‑Token | nur Status |
Ein vollständiger Durchlauf mit fetch:
// file: the File to convert, for example from an <input type="file">.
async function convertFile(file) {
const base = '/DocImage.axd';
// 1. open: 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: in 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 same-origin: Diese Version unterstützt kein CORS. Stelle deine UI und das Widget‑Skript vom selben Ursprung wie Doconut bereit, oder setze einen Reverse‑Proxy für den Handler und die Ressourcen‑Pfade unter dem Ursprung deiner UI ein.
In Produktion
- Installieren Sie das Plugin neben dem Kernpaket, in derselben Version:
Install-Package Doconut.NETFramework.Converter. - Fügen Sie die Lizenzdatei hinzu. Legen Sie
Doconut.Viewer.Converter.licin denselben Ordner wieDoconut.Viewer.lic. - Setzen Sie die Upload‑Grenzen.
MaxUploadMbinAddConverterWidgetist das von Doconut durchgesetzte Limit; halten SiemaxRequestLengthundmaxAllowedContentLengthinWeb.configdarüber (siehe Upload‑Grenzen), und setzen Sie dasmaxUploadMbdes Widgets gleich darauf. - Blockieren Sie niemals bei einer Konvertierung in Web Forms (siehe In Web Forms).
- Entsorgen Sie Konvertierungsergebnisse. Der von
ConvertAsynczurückgegebene Stream ist gepoolt; das Entsorgen gibt seine Puffer zurück in den Pool.
Web‑Farmen
Das Widget speichert jeden Upload und sein Ergebnis im Speicher auf dem Server, der open bereitgestellt hat. Hinter einem Load Balancer ohne Sticky Sessions kann eine spätere run, download oder Vorschau‑Anfrage einen anderen Server erreichen und den Upload nicht finden. Registrieren Sie den gemeinsamen, verschlüsselten Widget‑Store über das zweite Argument von DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget();
},
services => services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // ein Ordner, den jeder Server lesen und schreiben kann
store.FarmKey = farmKey; // mindestens 32 Bytes, auf jedem Server 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‑Store 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 ein Ergebnis für
Ttlnach dem Schreiben aufbewahrt; das Lesen verlängert dieses Zeitfenster nicht. FarmKeymuss mindestens 32 Byte groß sein und auf jedem Server gleich sein. Laden Sie es aus einem Secret Store; niemals hartkodieren. Die Registrierung wirft einArgumentException, wennRootPathfehlt oderFarmKeykürzer als 32 Byte ist.- Zeigen Sie
RootPathauf denselben gemeinsamen Speicherort, den der verteilte Viewer verwendet.
API‑Referenz
Die Fassade und die Widget‑Optionen befinden sich im Namensraum Doconut; 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);
}Gelöst aus DoconutHost.Services; 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 Ausgabformate, die in Ziel‑Formate aufgeführt sind.
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}Über DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null) gesetzt, das das DoconutOptions zurückgibt, sodass Aufrufe verkettet werden können.
Fehlerbehebung
| Symptom | Ursache | Lösung |
|---|---|---|
Jede Anfrage liefert ein leeres 500 nach dem Hinzufügen des Plugins; das Windows‑Ereignisprotokoll (Quelle ASP.NET) zeigt 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>() |
Jede Anfrage liefert ein leeres 500; das Ereignisprotokoll zeigt AddConverterWidget() was called but the Converter plugin is not registered. | Das Widget ist aktiviert ohne sein Plugin | Fügen Sie options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() hinzu |
Das 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>() in DoconutHost.Initialize hinzu |
| Eine Web Forms‑Konvertierung gibt nie zurück | Die Seite blockiert bei ConvertAsync | Verwenden Sie Async="true" und RegisterAsyncTask |
| 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 geben 404 zurück | AddConverterWidget() wurde nicht aufgerufen, oder basePath ist nicht '/DocImage.axd' | Rufen Sie AddConverterWidget() auf; setzen Sie basePath: '/DocImage.axd' |
| Ein großer Upload zeigt eine IIS‑Fehlerseite anstelle der Widget‑Nachricht | maxRequestLength / maxAllowedContentLength liegen unter MaxUploadMb | Erhöhen Sie die Web.config‑Grenzwerte über MaxUploadMb |
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 |
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 convert=open an |
run oder download antwortet 404 (Upload expired — please re-open the file. von run) | Das 30‑Minuten‑Fenster ist abgelaufen, oder ein anderer Server in einem Farm hat den Upload nicht | Öffnen Sie die Datei erneut; registrieren Sie in einer Farm AddDoconutDistributedWidgets |
| Das Widget schlägt fehl, wenn die UI von einem anderen Ursprung stammt | 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 werden an einem Vorfahren oder an einem Element innerhalb des Mounts gesetzt; die eigene .dcw‑Regel des Widgets setzt sie auf dem Mount | Zielen Sie direkt auf den Mount: #doconut-convert.dcw oder #doconut-convert |
Hinweise zum Framework
Im Vergleich zu den ASP.NET Core‑Paketen unterscheidet sich dieses Paket nur im Hosting; die API, der Endpunktvertrag, das Widget‑Skript und die Lizenzierungsregeln sind identisch.
- Registrierung erfolgt in
Application_Start, überDoconutHost.Initialize, anstelle vonbuilder.Services.AddDoconut. Dienste wieAddDoconutDistributedWidgetsgehen in das zweite Argument. - Endpunkte werden von
DocImage.axdbereitgestellt und das Skript vonDoconutResourceModule, beide registriert inWeb.config, anstelle vonUseDoconut()undUseDoconutResources(). Das Widget benötigtbasePath: '/DocImage.axd'. - Startfehler zeigen sich als ein leeres
500bei jeder Anfrage, mit dem Grund im Windows‑Ereignisprotokoll. - Uploads werden von ASP.NET vollständig gelesen, bevor Doconut sie sieht, daher müssen die IIS‑Grenzwerte über
MaxUploadMbliegen. - Web Forms‑Seiten dürfen nicht bei einer Konvertierung blockieren; siehe In Web Forms.
- Nur Windows, wie der Rest des .NET Framework‑Pakets.
War diese Seite hilfreich?