Πρόσθετο Μετατροπέα

Μετατροπή εγγράφων σε 45 μορφές προορισμού

Το πρόσθετο Converter μετατρέπει το Doconut σε υπηρεσία μετατροπής εγγράφων. Συνεισφέρει τη μηχανή πίσω από το δημόσιο DocumentConverter πρόσοψη και — με επιλογή — ένα ενσωματωμένο widget που παρέχεται από DocImage.axd, ώστε να μπορείτε να μετατρέπετε έγγραφα από C#, από το widget ή από ένα frontend που γράφετε εσείς.

ΕπίπεδοΧρησιμοποιήστε το όταν
DocumentConverter (C#)Μετατρέπετε στον διακομιστή, χωρίς να εμπλέκεται πρόγραμμα περιήγησης
Drop-in widget (doconutConverter.js)Θέλετε μια έτοιμη οθόνη μεταφόρτωσης, μετατροπής και λήψης στη σελίδα σας
HTTP endpoints on DocImage.axd (?convert=open|run|download)Δημιουργείτε το δικό σας UI μετατροπής βάσει ενός τεκμηριωμένου συμβολαίου διακομιστή

Εγκατάσταση του πακέτου

powershell
Install-Package Doconut.NETFramework.Converter

Για να συνδέσετε το πρόσθετο στην έκδοση που περιγράφει αυτή η τεκμηρίωση:

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

Διατηρήστε το πακέτο Converter στην ίδια έκδοση με το Doconut.NETFramework.

Το αρχείο άδειας του πρόσθετου, Doconut.Viewer.Converter.lic, τοποθετείται στον ίδιο φάκελο με το Doconut.Viewer.lic· διαβάζεται μαζί με την άδεια του viewer.

Καταχώριση του πρόσθετου

Κάθε πρόσθετο καταχωρίζεται με τον ίδιο τρόπο: AddPlugin<TPlugin>() στο DoconutHost.Initialize, καλείται από το Application_Start.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Αυτό είναι ό,τι χρειάζεται η πρόσοψη C#. Το widget και τα HTTP endpoints του είναι μια ξεχωριστή επιλογή, AddConverterWidget() (δείτε Widget ενσωμάτωσης).

Το πρόσθετο χρειάζεται άδεια που παρέχει τη δυνατότητα Converter. Χωρίς αυτή, το DoconutHost.Initialize πετάει από το Application_Start:

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.

Στο System.Web αυτό σημαίνει ότι κάθε αίτηση επιστρέφει ένα κενό 500, και ο λόγος εμφανίζεται μόνο στο ημερολόγιο συμβάντων των Windows (πηγή ASP.NET). Παράγει σφάλμα όταν δεν υπάρχει άδεια, όταν υπάρχει ένα παλιό αρχείο TRIAL, όταν η άδεια δεν περιέχει Converter, και όταν μια πληρωμένη άδεια χρησιμοποιείται εκτός του χρονικού παραθύρου έκδοσής της. Δεχόμαστε προσωρινές άδειες Demo/NFR. Δείτε Ρύθμιση Άδειας.

Αδειοδότηση & υδατογράφημα

Κατάσταση άδειαςΈναρξηΑποτέλεσμα μετατροπής
Πληρωμένη άδεια viewer που παρέχει Converter, εντός του χρονικού παραθύρου έκδοσής τηςΞεκινάΚαθαρό — watermarked: false
Ενεργή προσωρινή (Demo/NFR) άδειαΞεκινάΜετατρέπει, με το υδατογράφημα αξιολόγησης — watermarked: true
Ληγμένη προσωρινή (Demo/NFR) άδειαΞεκινάΜετατρέπει, με το υδατογράφημα αξιολόγησης — watermarked: true
Χωρίς άδεια, ένα παλιό αρχείο TRIAL, άδεια χωρίς Converter, ή μια πληρωμένη άδεια εκτός του χρονικού παραθύρου έκδοσής τηςApplication_Start πετάει· κάθε αίτηση επιστρέφει ένα κενό 500—

Η πρόσοψη DocumentConverter και ο χειριστής ?convert=run του widget εφαρμόζουν τον ίδιο κανόνα. Μια ενσωμάτωση μπορεί να δημιουργηθεί και να δοκιμαστεί από άκρη σε άκρη με άδεια αξιολόγησης πριν από την αγορά — μόνο τα bytes εξόδου αλλάζουν.

Μία πηγή DICOM (.dcm, .ima) χρειάζεται επίσης τη δυνατότητα Dicom. Χωρίς αυτή, το ConvertAsync πετάει ένα LicenseException (Converting '.dcm' requires the Dicom capability license.) και ο open του widget απαντά 403.

Χρήση από C#

Κάθε μετατροπή επιστρέφει ένα αναζητήσιμο MemoryStream τοποθετημένο στο 0. Το DocumentConverter είναι χωρίς κατάσταση: επιλύστε το από το DoconutHost.Services όπου το χρειάζεστε και επαναχρησιμοποιήστε το ελεύθερα.

csharp
// Ανακτήστε το DocumentConverter από το DoconutHost.Services· ο κατασκευαστής του είναι εσωτερικός, οπότε ποτέ μην το `new`.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// Το sourceExtension περιλαμβάνει την αρχική τελεία. Το password είναι null εκτός αν το έγγραφο είναι προστατευμένο.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: ένα Stream που περιέχει το HTML για να μετατραπεί ξανά σε έγγραφο Word, όπως το αποτέλεσμα του WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Δύο λεπτομέρειες που είναι εύκολο να παραλειφθούν: το sourceExtension στην υπερφόρτωση ροής πρέπει να περιλαμβάνει την αρχική τελεία (".xlsx", όχι "xlsx"), αλλιώς δεν επιλύεται. Και παρά το όνομά του, το WordToHtmlAsync επιστρέφει Task<Stream>, όχι Task<string> — το έγγραφο HTML (εικόνες ενσωματωμένες ως Base64) φθάνει ως ροή, όπως κάθε άλλο αποτέλεσμα.

Ο καλών (caller) κατέχει το MemoryStream που επιστρέφει μια μετατροπή και πρέπει να το διαγράψει μετά την αντιγραφή ή την επιστροφή του (το File(stream, …) του MVC το διαγράφει για εσάς). Μην δημιουργείτε ή διαγράφετε το DocumentConverter μόνοι σας — ο κατασκευαστής του είναι εσωτερικός.

Σε έναν ελεγκτή MVC 5

Κάντε τη δράση ασύγχρονη και await τη μετατροπή:

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

Στα Web Forms: μην μπλοκάρετε ποτέ μια μετατροπή

Μια σελίδα Web Forms εκτελείται σε ένα μονονηματικό πλαίσιο αιτήματος. ConvertAsync συνεχίζει σε αυτό το πλαίσιο όταν ολοκληρωθεί, έτσι μια σελίδα που περιμένει συγχρονισμένα — .Result, .Wait(), .GetAwaiter().GetResult() — κρατά το ίδιο νήμα που χρειάζεται η μετατροπή για να ολοκληρωθεί. Η αίτηση δεν επιστρέφει ποτέ. Ο περιηγητής συνεχίζει να περιστρέφεται, το IIS δεν καταγράφει τίποτα, και το υπόλοιπο του ιστότοπου συνεχίζει να λειτουργεί, οπότε φαίνεται σαν αργή μετατροπή αντί για αδιέξοδο.

Σημειώστε τη σελίδα Async="true" και εκτελέστε τη μετατροπή ως ασύγχρονη εργασία σελίδας:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// Web Forms: η οδηγία @Page χρειάζεται Async="true", και η μετατροπή εκτελείται ως ασύγχρονη εργασία σελίδας.
// Η αποκλειστική αναμονή σε αυτό (.Result, .Wait(), .GetAwaiter().GetResult()) προκαλεί αδιέξοδο στο αίτημα:
// δεν επιστρέφει ποτέ, και δεν καταγράφεται τίποτα.
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, όχι HttpContext.Current: μετά από await το δεύτερο μπορεί να είναι null.
            Context.ApplicationInstance.CompleteRequest();
        }
    }));
}

Χωρίς Async="true" στην οδηγία @Page, το RegisterAsyncTask αγνοείται σιωπηρά. Μετά από ένα await, χρησιμοποιήστε το Context της σελίδας· το HttpContext.Current μπορεί να είναι null εκεί.

Μορφές προορισμού

ConversionTarget (namespace Doconut.Configs.Conversion) έχει 45 μέλη:

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

Δεν μετατρέπει κάθε πηγή σε κάθε προορισμό: η οικογένεια μορφών κάθε πηγής (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, web document, DICOM) έχει το δικό της σύνολο επιτρεπόμενων προορισμών. Η μετατροπή μιας πηγής DICOM (.dcm, .ima) απαιτεί επίσης άδεια που παρέχει τη δυνατότητα Dicom· οι προορισμοί της είναι Pdf, Png, Jpeg, Bmp, Tiff και Gif. Μην κωδικοποιείτε σκληρά αυτό το enum ως τη λίστα προορισμών του UI σας: το ?convert=open επιστρέφει το allowedTargets για το ανεβασμένο αρχείο, και αυτό είναι ό,τι πρέπει να οδηγεί έναν επιλογέα.

Widget ενσωμάτωσης

Ενεργοποίηση των τελικών σημείων

Τα τελικά σημεία ?convert=open|run|download του widget εξυπηρετούνται από DocImage.axd και είναι απενεργοποιημένα από προεπιλογή. Ενεργοποιήστε τα δίπλα στην καταχώριση του plugin:

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 διαβάζει ολόκληρο το ανέβασμα πριν το δει το Doconut: διατηρήστε το maxRequestLength (KB) και
// maxAllowedContentLength (bytes) στο Web.config πάνω από το MaxUploadMb του widget.

AddConverterWidget() χωρίς όρισμα ενεργοποιεί το widget με τις προεπιλογές (MaxUploadMb = 25). Δεν παρέχει δικαιώματα μετατροπής από μόνο του: χρειάζεται AddPlugin<ConverterPlugin>(), ή το DoconutHost.Initialize προκαλεί εξαίρεση:

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.

Δύο πράγματα προς έλεγχο όταν το widget συμπεριφέρεται λανθασμένα:

  • basePath: '/DocImage.axd'. Η προεπιλογή του widget, /doconut, είναι το τελικό σημείο ASP.NET Core. Σε αυτό το πακέτο, τα τελικά σημεία είναι ο χειριστής DocImage.axd από το Web.config.
  • Το script και τα τελικά σημεία είναι ανεξάρτητα. Το μοντέλο πόρων εξυπηρετεί το doconutConverter.js είτε το widget είναι ενεργοποιημένο είτε όχι. Χωρίς AddConverterWidget(), το widget φορτώνει, σχεδιάζει τη ζώνη απόθεσης και φαίνεται εντελώς σωστό — και η πρώτη του ενέργεια απαντά το 404.

Όρια μεταφόρτωσης

ASP.NET διαβάζει ολόκληρο το σώμα του αιτήματος πριν εκτελεστεί το DocImage.axd. Μια μεταφόρτωση πάνω από το MaxUploadMb αλλά κάτω από τα όρια του κεντρικού συστήματος λαμβάνει το δικό του JSON 413 του widget (File is too large.). Μια μεταφόρτωση πάνω από τα όρια του κεντρικού συστήματος απορρίπτεται πρώτα από το IIS, με μια σελίδα σφάλματος που το widget δεν μπορεί να διαβάσει. Διατηρήστε και τα δύο όρια του κεντρικού συστήματος στο Web.config πάνω από το όριο του widget:

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>

Ενσωματώστε το

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) δέχεται έναν CSS selector ή ένα στοιχείο, ρίχνει σφάλμα αν δεν βρεθεί η τοποθέτηση και επιστρέφει ένα handle. Το widget μεταφορτώνει ένα αρχείο, εμφανίζει μια προεπισκόπηση της σελίδας 1, επιτρέπει στον χρήστη να επιλέξει ένα από τα allowedTargets, μετατρέπει, προεπισκοπεί το αποτέλεσμα όταν μπορεί, και προσφέρει τη λήψη.

Επιλογές

ΕπιλογήΤύποςΠροεπιλογήΣημειώσεις
basePathstring/doconutΤο URL του τελικού σημείου. Ορίστε το '/DocImage.axd' σε αυτό το πακέτο
resPathstring/doconut-resΑποδεκτό για συνέπεια με άλλα widgets Doconut· το widget μετατροπέα δεν δημιουργεί κανένα URL από αυτό
maxUploadMbnumber25Μόνο προ-έλεγχος στην πλευρά του πελάτη· ο διακομιστής επιβάλλει το δικό του όριο
licenseUrlstring | nullnullΜετατρέπει την ειδοποίηση υδατογραφήματος στην οθόνη αποτελεσμάτων σε σύνδεσμο
labelsobject{}Αντικαθιστά οποιοδήποτε υποσύνολο των αγγλικών συμβολοσειρών του widget

Κλήσεις επιστροφής

ΚλήσηΕνεργοποιείται ότανΠεριεχόμενο
onReady()Το widget έχει αποδώσει την οθόνη μεταφοράς—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open succeedsΔιακριτικό πηγής, αριθμός σελίδων, επέκταση πηγής (χωρίς την αρχική τελεία), επιτρεπόμενοι προορισμοί
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run succeedsΗ απάντηση εκτέλεσης συν το ζητούμενο target
onDownload({ downloadName, downloadToken })Ο χρήστης κάνει κλικ στο ΛήψηΕνεργοποιείται παράλληλα με τη δική του λήψη του προγράμματος περιήγησης
onError({ phase, message })Μια αίτηση open ή run αποτυγχάνειphase είναι 'open' ή 'run'· message είναι το καθαρισμένο σφάλμα του διακομιστή

Μια κλήση επιστροφής που ρίχνει εξαίρεση πιάστηκε και καταγράφηκε· δεν διακόπτει ποτέ τη ροή του widget.

Απαιτούμενο handle

Το Doconut.convert() επιστρέφει την παρουσία του widget:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // ένα File από το δικό σας <input type="file" id="picker">
conv.reset();         // πίσω στην οθόνη απόθεσης; δεν επανεκκινεί το onReady
conv.loadFile(file);  // ξεκινά τη ροή με ένα File; no-op εκτός αν το widget βρίσκεται στην οθόνη απόθεσης
conv.destroy();       // αφαιρεί listeners, αδειάζει το mount; η instance είναι αχρησιμοποίητη μετά από αυτό

Ετικέτες

Κάθε συμβολοσειρά έχει προεπιλογή στα Αγγλικά· το labels αντικαθιστά οποιοδήποτε υποσύνολο και τα υπόλοιπα παραμένουν στα Αγγλικά. Τμήματα που αλλάζουν κατά την εκτέλεση χρησιμοποιούν το {placeholders}, όπως τα uploading: 'Uploading {name}…' και pages: '{n} pages'.

ΚλειδίΠροεπιλογή Αγγλική
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.

Περαιτέρω κλειδιά καλύπτουν το aria-label της ζώνης μεταφοράς (dropAriaLabel), τα κείμενα προεπισκόπησης alt (previewAlt, resultAlt), τη συνδεδεμένη μορφή της ειδοποίησης υδατογραφήματος που χρησιμοποιείται με το licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), μια μη αναγνώσιμη απάντηση (badResponse) και τις αναγγελίες aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).

Ένα σφάλμα JSON από τον διακομιστή εμφανίζεται όπως το έγραψε ο διακομιστής· το serverError χρησιμοποιείται μόνο όταν μια αποτυχημένη απάντηση δεν περιέχει σφάλμα JSON, όπως το 404 ενός απενεργοποιημένου widget.

Θέματα

Το widget προσθέτει την κλάση dcw στο στοιχείο προσάρτησής του και διαβάζει τα χρώματα, την ακτίνα και τη γραμματοσειρά του από προσαρμοσμένες ιδιότητες CSS, ώστε να μπορείτε να το θεματίσετε χωρίς να αγγίξετε τα εσωτερικά του:

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

Προεπιλογές: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px, και μια γραμματοσειρά συστήματος UI για --dcw-font.

Δημιουργήστε το δικό σας frontend

Το widget είναι πελάτης για αυτή τη σύμβαση HTTP στο DocImage.axd. Οι διαδρομές απαντούν 404 μέχρι να κληθεί το AddConverterWidget(). Τα σφάλματα περιέχουν σώμα JSON, { "error": "..." }, εκτός όπου ο πίνακας λέει «status only». Μια άγνωστη τιμή ?convert= απαντά 400.

ΔιαδρομήΣκοπόςΑπάντηση επιτυχίας
POST /DocImage.axd?convert=open (multipart, ένα αρχείο)Ανέβασμα και άνοιγμα ενός αρχείου προέλευσης200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>Μετατροπή του ανεβασμένου αρχείου προέλευσης σε target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>Ροή του μετατρεπόμενου αρχείου200 — το αρχείο, Content-Disposition: attachment, Cache-Control: no-store

Το sourceExt στην απάντηση open δεν έχει αρχική τελεία ("docx") — το αντίστροφο του παραμέτρου sourceExtension του ConvertAsync. Το allowedTargets παραθέτει ονόματα στόχων με πεζά γράμματα ("pdf", "html", …); περάστε ένα από αυτά ως target, το οποίο ταιριάζει χωρίς διάκριση πεζών‑κεφαλαίων. Το open χρησιμοποιεί το πρώτο αρχείο στο multipart σώμα.

Το resultToken είναι null, και το resultPages είναι 0, όταν το αποτέλεσμα δεν μπορεί να προεπισκοπηθεί. Το downloadName είναι το όνομα του αρχείου προέλευσης με την επέκταση του στόχου.

Οι εικόνες προεπισκόπησης χρησιμοποιούν τη στάνταρ διαδρομή εικόνας του προβολέα, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, με το token από open ή το resultToken από run. Το widget ζητά το width=240.

Τα ανεβασμένα αρχεία προέλευσης διατηρούνται για 30 λεπτά μετά την τελευταία ανάγνωση· μετά από αυτό, το run απαντά 404 και το αρχείο πρέπει να ανοίξει ξανά. Το downloadToken λαμβάνει το δικό του παράθυρο 30 λεπτών όταν ολοκληρωθεί η μετατροπή. Το resultToken είναι ένα συνηθισμένο token προβολέα για την προεπισκόπηση του αποτελέσματος· όταν το αποτέλεσμα μπορεί να προεπισκοπηθεί, είναι η ίδια τιμή με το downloadToken.

ΔιαδρομήΚατάστασηΠότεΣώμα
οποιοδήποτε404Το widget δεν είναι ενεργοποιημένο (το AddConverterWidget() δεν κλήθηκε ποτέ)μόνο κατάσταση
οποιοδήποτε405Λάθος ρήμα (open/run απαιτούν POST, download απαιτεί GET)μόνο κατάσταση
open400Δεν είναι multipart ανέβασμαExpected a multipart file upload.
open400Κανένα αρχείο, ή ένα κενόNo file uploaded.
open400Τύπος που δεν μπορεί να μετατραπείThis file type cannot be converted.
open403Ο τύπος αρχείου απαιτεί δυνατότητα που δεν παρέχει η άδεια (αρχείο DICOM χωρίς Dicom)Converting this file type requires the Dicom capability license.
open413Το ανέβασμα υπερβαίνει το MaxUploadMb (αλλά όχι τα όρια του IIS)File is too large.
run400Κακοδιατυπωμένο token (δεν είναι GUID)Invalid token.
run400Ένα target που δεν μπορεί να αναλυθεί σε ConversionTargetUnknown target format.
run400Στόχος που δεν υπάρχει στο allowedTargetsThat target format is not available for this file.
run404Το ανέβασμα έληξε ή δεν ανοίχθηκε ποτέUpload expired — please re-open the file.
open, run500Η επεξεργασία απέτυχεΈνα εξουδετερωμένο μήνυμα
download400 / 404Κακοδιατυπωμένο, άγνωστο ή ληγμένο token λήψηςμόνο κατάσταση

Μια πλήρης διαδρομή με fetch:

javascript
// file: το File προς μετατροπή, για παράδειγμα από ένα <input type="file">.
async function convertFile(file) {
  const base = '/DocImage.axd';

  // 1. open: ανέβασε το αρχείο
  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: μετατρέψτε σε PDF όταν επιτρέπεται, αλλιώς στον πρώτο επιτρεπόμενο προορισμό
  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: ένα απλό GET που μπορεί να ακολουθήσει ο περιηγητής
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

Τα σημεία άκρου είναι same-origin: αυτή η έκδοση δεν υποστηρίζει CORS. Σερβίρετε το UI σας και το script του widget από την ίδια προέλευση με το Doconut, ή κάντε reverse‑proxy τον χειριστή και τις διαδρομές πόρων κάτω από την προέλευση του UI σας.

Σε παραγωγή

  1. Εγκατάσταση του plugin δίπλα στο βασικό πακέτο, στην ίδια έκδοση: Install-Package Doconut.NETFramework.Converter.
  2. Προσθήκη του αρχείου άδειας. Τοποθετήστε Doconut.Viewer.Converter.lic στον ίδιο φάκελο με Doconut.Viewer.lic.
  3. Ορισμός των ορίων ανεβάσματος. MaxUploadMb στο AddConverterWidget είναι το όριο που επιβάλλει το Doconut· διατηρήστε maxRequestLength και maxAllowedContentLength στο Web.config πάνω από αυτό (δείτε Όρια ανεβάσματος), και το maxUploadMb του widget ίσο με αυτό.
  4. Ποτέ μην μπλοκάρετε μια μετατροπή σε Web Forms (δείτε Σε Web Forms).
  5. Αποδέσμευση των αποτελεσμάτων μετατροπής. Η ροή που επιστρέφει το ConvertAsync είναι σε δεξαμενή· η αποδέσμευσή της επιστρέφει τα buffers στην δεξαμενή.

Φάρμες Web

Το widget διατηρεί κάθε ανέβασμα και το αποτέλεσμα του στη μνήμη του διακομιστή που εξυπηρέτησε το open. Πίσω από έναν φορτωτή ισορροπίας χωρίς sticky sessions, ένα μεταγενέστερο run, download ή αίτημα προεπισκόπησης μπορεί να φτάσει σε άλλο διακομιστή και να μην βρει το ανέβασμα. Καταχωρίστε το κοινόχρηστο, κρυπτογραφημένο κατάστημα widget μέσω του δεύτερου ορίσματος του 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";   // ένας φάκελος που κάθε διακομιστής μπορεί να διαβάσει και να γράψει
        store.FarmKey = farmKey;                   // τουλάχιστον 32 byte, ταυτόσιο σε κάθε διακομιστή
        // store.Ttl = TimeSpan.FromMinutes(30);   // πόσο διαρκεί η διατήρηση ενός ανεβάσματος (η προεπιλογή)
    }));
  • Ένας μόνος διακομιστής δεν χρειάζεται τίποτα: χωρίς αυτήν την κλήση χρησιμοποιείται η αποθήκη στη μνήμη.
  • Τα ανεβάσματα και τα αποτελέσματα κρυπτογραφούνται κατά την αποθήκευση στο κοινόχρηστο (AES-256, encrypt-then-MAC), και κάθε αρχείο δεσμεύεται στο token του, ώστε ένα token να μην μπορεί ποτέ να διαβάσει το αρχείο κάποιου άλλου.
  • Στο κοινόχρηστο, ένα ανέβασμα ή ένα αποτέλεσμα διατηρείται για Ttl μετά τη δημιουργία του· η ανάγνωσή του δεν επεκτείνει αυτό το παράθυρο.
  • FarmKey πρέπει να είναι τουλάχιστον 32 bytes και το ίδιο σε κάθε διακομιστή. Φορτώστε το από μυστικό κατάστημα· ποτέ μην το κωδικοποιείτε σκληρά. Η καταχώριση ρίχνει ένα ArgumentException όταν το RootPath λείπει ή το FarmKey είναι μικρότερο από 32 bytes.
  • Κατευθύνετε το RootPath στην ίδια κοινόχρηστη τοποθεσία που χρησιμοποιεί ο κατανεμημένος viewer.

Αναφορά API

Η πρόσοψη και οι επιλογές του widget βρίσκονται στο namespace Doconut· ConversionTarget βρίσκεται στο Doconut.Configs.Conversion. ConverterPlugin βρίσκεται στο 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);
}

Αντιστοιχεί από το DoconutHost.Services· ο κατασκευαστής είναι εσωτερικός. sourceExtension περιλαμβάνει την αρχική τελεία. HtmlToWordAsync γράφει ένα αρχείο .doc όταν το outputFormat είναι ConversionTarget.Doc, και ένα αρχείο .docx για οποιαδήποτε άλλη τιμή.

ConversionTarget

Οι 45 μορφές εξόδου που αναφέρονται στο Μορφές στόχου.

ConverterWidgetOptions

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

Ορίζεται μέσω του DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), που επιστρέφει το DoconutOptions ώστε οι κλήσεις να μπορούν να αλυσιδωθούν.

Αντιμετώπιση προβλημάτων

ΣυμπτωμαΑιτίαΔιόρθωση
Κάθε αίτηση επιστρέφει ένα κενό 500 μετά την προσθήκη του plugin· το αρχείο καταγραφής συμβάντων των Windows (πηγή ASP.NET) εμφανίζει The Converter plugin is registered via AddPlugin but no active license grants Converter.Καμία άδεια, ένα αρχείο TRIAL, άδεια χωρίς Converter, ή πληρωμένη άδεια εκτός του παραθύρου έκδοσής τηςΕγκαταστήστε μια άδεια που παρέχει Converter, ή αφαιρέστε AddPlugin<ConverterPlugin>()
Κάθε αίτηση επιστρέφει ένα κενό 500· το αρχείο καταγραφής εμφανίζει AddConverterWidget() was called but the Converter plugin is not registered.Το widget είναι ενεργοποιημένο χωρίς το plugin τουΠροσθέστε options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>()
Η επίλυση του DocumentConverter προκαλεί No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().ConverterPlugin δεν είναι καταχωρημένοΠροσθέστε AddPlugin<ConverterPlugin>() στο DoconutHost.Initialize
Μια μετατροπή Web Forms δεν επιστρέφει ποτέΗ σελίδα μπλοκάρει στο ConvertAsyncΧρησιμοποιήστε Async="true" και RegisterAsyncTask
Η μετατροπή ροής αναφέρει ότι η μορφή δεν υποστηρίζεταιsourceExtension δεν έχει αρχική τελείαΠεράστε ".xlsx", όχι "xlsx"
ConvertAsync προκαλεί Converting '.dcm' requires the Dicom capability license.Μια πηγή DICOM, και η άδεια δεν παρέχει DicomΧρησιμοποιήστε μια άδεια που παρέχει Dicom
Η έξοδος έχει υδατογράφημαΗ άδεια είναι προσωρινή (Demo/NFR)Χρησιμοποιήστε μια πληρωμένη άδεια που παρέχει Converter
Το widget φορτώνει αλλά τα αιτήματά του επιστρέφουν 404AddConverterWidget() δεν κλήθηκε, ή basePath δεν είναι '/DocImage.axd'Κληθείτε AddConverterWidget()· ορίστε basePath: '/DocImage.axd'
Μια μεγάλη μεταφόρτωση εμφανίζει μια σελίδα σφάλματος IIS αντί για το μήνυμα του widgetmaxRequestLength / maxAllowedContentLength είναι κάτω από MaxUploadMbΑυξήστε τα όρια Web.config πάνω από MaxUploadMb
open απαντά 403 Converting this file type requires the Dicom capability license.Μια μεταφόρτωση DICOM, και η άδεια δεν παρέχει DicomΧρησιμοποιήστε μια άδεια που παρέχει Dicom
run απαντά 400 That target format is not available for this file.Ο προορισμός δεν είναι ένας από τους allowedTargets της πηγήςΠροσφέρετε μόνο το allowedTargets από convert=open
run ή download απαντά 404 (Upload expired — please re-open the file. από run)Το 30λεπτο παράθυρο έληξε, ή ένας άλλος διακομιστής σε φάρμα δεν έχει τη μεταφόρτωσηΑνοίξτε ξανά το αρχείο· σε φάρμα, καταχωρήστε AddDoconutDistributedWidgets
Το widget αποτυγχάνει όταν το UI είναι σε διαφορετική προέλευσηΤα άκρα δεν έχουν υποστήριξη CORSΣερβίρετε το UI από την ίδια προέλευση, ή κάντε reverse-proxy τις διαδρομές Doconut
Το θέμα δεν εφαρμόζεταιΟι μεταβλητές ορίζονται σε έναν πρόγονο ή σε ένα στοιχείο μέσα στο mount· ο δικός του κανόνας .dcw του widget τις ορίζει στο mountΣτοχεύστε στο ίδιο το mount: #doconut-convert.dcw ή #doconut-convert

Σημειώσεις πλαισίου

Σε σύγκριση με τα πακέτα ASP.NET Core, αυτό το πακέτο διαφέρει μόνο στο hosting· το API, το συμβόλαιο των endpoints, το script του widget και οι κανόνες αδειοδότησης είναι οι ίδιοι.

  • Καταγραφή είναι στο Application_Start, μέσω DoconutHost.Initialize, αντί για builder.Services.AddDoconut. Υπηρεσίες όπως AddDoconutDistributedWidgets πηγαίνουν στο δεύτερο όρισμά του.
  • Τελικά σημεία εξυπηρετούνται από DocImage.axd και το script από DoconutResourceModule, και τα δύο καταχωρούνται στο Web.config, αντί για UseDoconut() και UseDoconutResources(). Το widget χρειάζεται basePath: '/DocImage.axd'.
  • Αποτυχίες εκκίνησης εμφανίζονται ως κενό 500 σε κάθε αίτηση, με τον λόγο στο αρχείο καταγραφής των Windows.
  • Μεταφορτώσεις διαβάζονται πλήρως από το ASP.NET πριν το Doconut τις δει, έτσι τα όρια IIS πρέπει να είναι πάνω από MaxUploadMb.
  • Web Forms οι σελίδες δεν πρέπει να μπλοκάρουν σε μια μετατροπή· δείτε Στα Web Forms.
  • Μόνο Windows, όπως το υπόλοιπο του πακέτου .NET Framework.

Ήταν αυτή η σελίδα χρήσιμη;