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ä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-Endpunkte auf DocImage.axd (?convert=open|run|download)Sie bauen Ihre eigene Konvertierungs‑UI gegen einen dokumentierten Server‑Vertrag

Paket installieren

powershell
Install-Package Doconut.NETFramework.Converter

Um das Plugin an die in dieser Dokumentation beschriebene Version zu binden:

powershell
Install-Package Doconut.NETFramework.Converter -Version 26.10.0

Bewahren 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.

csharp
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:

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.

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

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 VersionsfenstersApplication_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.

csharp
// 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);
csharp
// 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);
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"), 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:

csharp
[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:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// 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.

Ziel­formate

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

csharp
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:

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.

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 der DocImage.axd‑Handler von Web.config.
  • Das Skript und die Endpunkte sind unabhängig. Das Ressourcenmodul liefert doconutConverter.js, unabhängig davon, ob das Widget aktiviert ist. Ohne AddConverterWidget() lädt das Widget, zeichnet seine Drop‑Zone und sieht völlig korrekt aus — und seine erste Aktion beantwortet 404.

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:

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

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

OptionTypStandardHinweise
basePathstring/doconutDie Endpunkt‑URL. Setze '/DocImage.axd' in diesem Paket
resPathstring/doconut-resAkzeptiert zur Konsistenz mit anderen Doconut‑Widgets; das Konverter‑Widget erzeugt daraus keine URL
maxUploadMbnumber25Nur clientseitige Vorprüfung; der Server erzwingt sein eigenes Limit
licenseUrlstring | nullnullWandelt den Wasserzeichen‑Hinweis auf dem Ergebnisbildschirm in einen Link um
labelsobject{}Überschreibt jede Teilmenge der englischen Zeichenketten des Widgets

Rückrufe

RückrufWird ausgelöst, wennNutzdaten
onReady()Das Widget hat seinen Drop‑Bildschirm gerendert—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })wenn ?convert=open erfolgreich istQuell‑Token, Seitenzahl, Quell‑Erweiterung (ohne führenden Punkt), erlaubte Ziele
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })wenn ?convert=run erfolgreich istDie Ausführungs‑Antwort plus das angeforderte target
onDownload({ downloadName, downloadToken })Der Benutzer klickt auf DownloadWird zusammen mit dem eigenen Download des Browsers ausgelöst
onError({ phase, message })Eine Öffnen‑ oder Ausführen‑Anfrage schlägt fehlphase 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:

javascript
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 verwendbar

Beschriftungen

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ü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 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:

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

RouteZweckErfolgsantwort
POST /DocImage.axd?convert=open (multipart, one file)Hochladen und Öffnen eines Quelldokuments200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>Konvertiere die hochgeladene Quelle zu target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>Stelle die konvertierte Datei als Stream bereit200 — 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.

RouteStatusWannInhalt
beliebig404Das Widget ist nicht aktiviert (AddConverterWidget() wurde nie aufgerufen)nur Status
beliebig405Falsches Verb (open/run erfordern POST, download erfordert GET)nur Status
open400Kein Multipart‑UploadExpected a multipart file upload.
open400Keine Datei oder eine leereNo file uploaded.
open400Ein Typ, der 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.
open413Der Upload überschreitet MaxUploadMb (aber nicht die IIS‑Grenzen)File is too large.
run400Ein fehlerhaftes Token (kein GUID)Invalid token.
run400Ein target, das nicht zu einem ConversionTarget geparst werden kannUnknown target format.
run400Ein Ziel, das nicht in allowedTargets enthalten istThat target format is not available for this file.
run404Der Upload ist abgelaufen oder wurde nie geöffnetUpload expired — please re-open the file.
open, run500Verarbeitung fehlgeschlagenEine bereinigte Meldung
download400 / 404Ein fehlerhaftes, unbekanntes oder abgelaufenes Download‑Tokennur Status

Ein vollständiger Durchlauf mit fetch:

javascript
// 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

  1. Installieren Sie das Plugin neben dem Kernpaket, in derselben Version: Install-Package Doconut.NETFramework.Converter.
  2. Fügen Sie die Lizenzdatei hinzu. Legen Sie Doconut.Viewer.Converter.lic in denselben Ordner wie Doconut.Viewer.lic.
  3. Setzen Sie die Upload‑Grenzen. MaxUploadMb in AddConverterWidget ist das von Doconut durchgesetzte Limit; halten Sie maxRequestLength und maxAllowedContentLength in Web.config darüber (siehe Upload‑Grenzen), und setzen Sie das maxUploadMb des Widgets gleich darauf.
  4. Blockieren Sie niemals bei einer Konvertierung in Web Forms (siehe In Web Forms).
  5. Entsorgen Sie Konvertierungsergebnisse. Der von ConvertAsync zurü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:

csharp
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 Ttl nach dem Schreiben aufbewahrt; das Lesen verlängert dieses Zeitfenster nicht.
  • FarmKey muss mindestens 32 Byte groß sein und auf jedem Server gleich sein. Laden Sie es aus einem Secret Store; niemals hartkodieren. Die Registrierung wirft ein ArgumentException, wenn RootPath fehlt oder FarmKey kürzer als 32 Byte ist.
  • Zeigen Sie RootPath auf 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

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);
}

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

csharp
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

SymptomUrsacheLö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 VersionsfenstersInstallieren 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 PluginFü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 registriertFügen Sie AddPlugin<ConverterPlugin>() in DoconutHost.Initialize hinzu
Eine Web Forms‑Konvertierung gibt nie zurückDie Seite blockiert bei ConvertAsyncVerwenden Sie Async="true" und RegisterAsyncTask
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 geben 404 zurückAddConverterWidget() 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‑NachrichtmaxRequestLength / maxAllowedContentLength liegen unter MaxUploadMbErhö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 DicomVerwenden 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 QuelleBieten 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 stammtDie Endpunkte unterstützen kein CORSStellen Sie die UI vom selben Ursprung bereit, oder setzen Sie einen Reverse‑Proxy für die Doconut‑Pfade ein
Das Theme wird nicht angewendetDie Variablen werden an einem Vorfahren oder an einem Element innerhalb des Mounts gesetzt; die eigene .dcw‑Regel des Widgets setzt sie auf dem MountZielen 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, über DoconutHost.Initialize, anstelle von builder.Services.AddDoconut. Dienste wie AddDoconutDistributedWidgets gehen in das zweite Argument.
  • Endpunkte werden von DocImage.axd bereitgestellt und das Skript von DoconutResourceModule, beide registriert in Web.config, anstelle von UseDoconut() und UseDoconutResources(). Das Widget benötigt basePath: '/DocImage.axd'.
  • Startfehler zeigen sich als ein leeres 500 bei 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 MaxUploadMb liegen.
  • 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?