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

Μετατρέψτε έγγραφα σε 45 μορφές προορισμού

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

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

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

Εγκαταστήστε το πιο πρόσφατο σταθερό πρόσθετο Converter:

bash
dotnet add package Doconut.NET6.Converter

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

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

Διατηρήστε το πακέτο Converter στην ίδια έκδοση με το Doconut.NET6. Το αναγνωριστικό πακέτου είναι Doconut.NET6.Converter; το .<version> εμφανίζεται μόνο στο ληφθέν όνομα αρχείου .nupkg.

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

Πλατφόρμες. Το πρόσθετο λειτουργεί όπου και το Doconut.NET6 λειτουργεί: Windows και Linux βασισμένο σε glibc σε x64 (όχι Alpine ή άλλες διανομές βασισμένες σε musl). Σε Linux, εγκαταστήστε τη βιβλιοθήκη διαμόρφωσης γραμματοσειρών πριν ανοίξει το πρώτο έγγραφο:

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

Σε RHEL, Fedora και παρόμοιες διανομές το πακέτο είναι fontconfig. Χωρίς αυτό, το άνοιγμα ενός εγγράφου αποτυγχάνει με The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

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

Δεν υπάρχει μέθοδος AddConverter() — το μοντέλο πρόσθετων του Doconut είναι ομοιόμορφο. Κάθε πρόσθετο, συμπεριλαμβανομένου του Converter, καταχωρείται με τον ίδιο τρόπο: καλέστε το AddPlugin<TPlugin>() μέσα στο AddDoconut(). Το ConverterPlugin διανέμεται στο δικό του πακέτο NuGet, Doconut.NET6.Converter, εγκατεστημένο παράλληλα με το βασικό πακέτο προβολέα.

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

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

Το πρόσθετο χρειάζεται μια άδεια που παρέχει τη δυνατότητα Converter. Χωρίς αυτή, το AddDoconut() ρίχνει ένα InvalidOperationException κατά την εκκίνηση, πριν η εφαρμογή εξυπηρετήσει ένα αίτημα:

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.

Ρίχνει σφάλμα όταν δεν υπάρχει άδεια, όταν υπάρχει ένα παλιό αρχείο TRIAL, όταν η άδεια δεν περιέχει Converter, και όταν μια πληρωμένη άδεια χρησιμοποιείται εκτός του χρονικού παραθύρου της. Δέχονται προσωρινές άδειες Demo/NFR. Δεν υπάρχει σιωπηλό δωρεάν επίπεδο. Δείτε το License Setup για το πώς φορτώνονται οι άδειες.

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

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

Και οι δύο διαδρομές κλήσης υπολογίζουν τη σημαία από τον ίδιο κανόνα: η διεπαφή C# DocumentConverter την παράγει εσωτερικά από την κατάσταση IsViewerLicensed και IsTemporary της άδειας, και ο χειριστής ?convert=run του widget κάνει τον ισοδύναμο έλεγχο (IsViewerLicensed && !IsTrial && !IsTemporary) για να γεμίσει το πεδίο watermarked που επιστρέφει. Μια ενσωμάτωση μπορεί να δημιουργηθεί και να δοκιμαστεί από άκρη σε άκρη με μια άδεια αξιολόγησης πριν από την αγορά — μόνο τα bytes εξόδου αλλάζουν.

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

Χρήση από C#

Κάθε μετατροπή επιστρέφει ένα αναζητήσιμο MemoryStream τοποθετημένο στο 0, έτοιμο για ανάγνωση ή αντιγραφή άμεσα. Ανάκτηση του DocumentConverter από το DI όπου και αν το χρειάζεστε — είναι χωρίς κατάσταση κατά το σχεδιασμό, έτσι ένα μόνο αντίγραφο είναι ασφαλές για επαναχρησιμοποίηση σε πολλαπλά αιτήματα.

csharp
// Ενθέστε το DocumentConverter· ο κατασκευαστής του είναι εσωτερικός, οπότε ποτέ μην το `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) ως ροή, το ίδιο όπως κάθε άλλο αποτέλεσμα μετατροπής.

Ο καλούντας κατέχει τη επιστρεφόμενη ροή και πρέπει να την απελευθερώσει μετά την αντιγραφή ή την επιστροφή του περιεχομένου της. Η υπηρεσία DocumentConverter λήγεται από την εξάρτηση ένεσης· μην τη δημιουργείτε ή την απελευθερώνετε χειροκίνητα.

Μορφές στόχου

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/Task, 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 είναι προαιρετικά και απενεργοποιημένα από προεπιλογή — ασφαλή από προεπιλογή. Ενεργοποιήστε τα στην πλευρά του διακομιστή, μαζί με την εγγραφή του πρόσθετου:

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

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

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

Χωρίς AddConverterWidget(), τα τρία ?convert= τελικά σημεία απαντούν 404 — αλλά το αρχείο JS εξακολουθεί να σερβίρεται ανεξαρτήτως (είναι ένας απλός ενσωματωμένος στατικός πόρος· μόνο τα τελικά σημεία στα οποία επικοινωνεί είναι περιορισμένα).

Ενσωμάτωση

html
<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

Doconut.convert(selectorOrElement, options) δέχεται έναν CSS selector ή ένα στοιχείο, ρίχνει σφάλμα αν το mount δεν βρεθεί και επιστρέφει έναν χειριστή. Το widget ανεβάζει ένα αρχείο, δείχνει προεπισκόπηση της σελίδας 1, επιτρέπει στον χρήστη να επιλέξει ένα από τα allowedTargets, μετατρέπει, προεπισκοπεί το αποτέλεσμα όταν μπορεί, και προσφέρει τη λήψη.

Επιλογές

ΕπιλογήΤύποςΠροεπιλογήΣημειώσεις
basePathstring/doconutΒασική διαδρομή για τα τελικά σημεία του ?convert=· πρέπει να ταιριάζει με το κλάδο ASP.NET όπου το UseDoconut() είναι πραγματικά προσαρτημένο (συνήθως συντονισμένο μέσω του MiddlewarePath)
resPathstring/doconut-resΑποδεκτό για συνέπεια ρυθμίσεων με άλλα widgets του Doconut· το widget μετατροπέα αυτή τη στιγμή δεν δημιουργεί καμία διεύθυνση URL από αυτό
maxUploadMbnumber25Μόνο προ-έλεγχος στην πλευρά του πελάτη — απορρίπτει ένα υπερβολικά μεγάλο αρχείο πριν τη μεταφόρτωση. Ο διακομιστής επιβάλλει το δικό του όριο ανεξάρτητα και απαντά 413 εάν το υπερβεί
licenseUrlstring | nullnullΌταν οριστεί, μετατρέπει την ειδοποίηση υδατογράμματος στην οθόνη αποτελεσμάτων σε σύνδεσμο προς αυτή τη διεύθυνση URL
labelsobject{}Αντικαθιστά οποιοδήποτε υποσύνολο των προεπιλεγμένων αγγλικών συμβολοσειρών του widget (κείμενο απόρριψης, κουμπιά, ανακοινώσεις aria-live, μηνύματα σφάλματος)

Ανακλήσεις

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

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

Επιτακτικό χειριστήριο

Doconut.convert() επιστρέφει το ίδιο το στιγμιότυπο του widget — κρατήστε το για να ελέγχετε το widget προγραμματιστικά:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // ένα File από το δικό σου <input type="file" id="picker">
conv.reset();         // πίσω στην οθόνη idle/drop; δεν επανεκκινεί το onReady
conv.loadFile(file);  // εκκινεί τη ροή με ένα αντικείμενο File; δεν κάνει τίποτα εκτός εάν είναι αυτή τη στιγμή αδρανής
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 — δημιουργήστε το δικό σας frontend εναντίον του απευθείας για διαφορετική εμπειρία χρήστη. Οι τρεις διαδρομές βρίσκονται κάτω από το κλαδί ASP.NET όπου το UseDoconut() είναι προσαρτημένο (συνήθως /doconut), και απαντούν με 404 μέχρι να κληθεί το AddConverterWidget(). Τα σφάλματα περιλαμβάνουν σώμα JSON, { "error": "..." }, εκτός από τις περιπτώσεις όπου ο πίνακας λέει «μόνο κατάσταση». Μια άγνωστη τιμή ?convert= απαντά με 400.

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

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

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

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

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

Τρόποι αποτυχίας, ομαδοποιημένοι ανά διαδρομή:

ΔιαδρομήΚατάστασηΠότεΣώμα
any404Το widget δεν είναι ενεργοποιημένο (AddConverterWidget() δεν κλήθηκε ποτέ) — ελέγχεται πριν την εκτέλεση οποιασδήποτε από τις τρεις διαδρομέςμόνο κατάσταση
any405Λάθος HTTP verb (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, ελέγχεται έναντι του Content-Length και ενώ το ανέβασμα διαβάζεταιFile is too large.
run400Κακοδιατυπωμένο token (δεν είναι GUID)Invalid token.
run400Ένα target που δεν μπορεί να αναλυθεί σε ConversionTargetUnknown target format.
run400target δεν βρίσκεται στο allowedTargets του πηγαίουThat target format is not available for this file.
run404Η αποθηκευμένη μεταφόρτωση έχει λήξει ή το token δεν ανοίχθηκε ποτέUpload expired — please re-open the file.
open, run500Η επεξεργασία απέτυχε εσωτερικάΈνα εξειδικευμένο μήνυμα — εξειδικευμένο με τον ίδιο τρόπο όπως κάθε άλλη διαδρομή σφάλματος Doconut· δεν εκθέτει ποτέ εσωτερικές λεπτομέρειες
download400Κακοδιατυπωμένο token (δεν είναι GUID)μόνο κατάσταση
download404Άγνωστο ή ληγμένο token λήψηςμόνο κατάσταση

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

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

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

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

Σε παραγωγή

  1. Εγκαταστήστε το πρόσθετο δίπλα στο βασικό πακέτο, στην ίδια έκδοση: dotnet add package Doconut.NET6.Converter.
  2. Προσθέστε το αρχείο άδειας. Τοποθετήστε Doconut.Viewer.Converter.lic στον ίδιο φάκελο με Doconut.Viewer.lic.
  3. Ορίστε το όριο του διακομιστή. MaxUploadMb στο AddConverterWidget είναι το όριο που επιβάλλει ο διακομιστής· το maxUploadMb του widget είναι μόνο ένας έλεγχος στην πλευρά του πελάτη. Κρατήστε τα δύο ίσα.
  4. Σερβίρετε το UI από την ίδια προέλευση όπως τα σημεία τέλους Doconut, ή κάντε reverse-proxy (δείτε Δημιουργήστε το δικό σας frontend).
  5. Αποδεσμεύστε τα αποτελέσματα μετατροπής. Η ροή που επιστρέφει το ConvertAsync είναι σε δεξαμενή· η αποδέσμευση της επιστρέφει τα buffers στην δεξαμενή.

Φάρμες ιστού

Το widget διατηρεί κάθε μεταφόρτωση και το αποτέλεσμα της στη μνήμη του κόμβου που εξυπηρέτησε το open. Πίσω από έναν φορτωτή ισορροπίας χωρίς sticky sessions, ένα μεταγενέστερο αίτημα run, download ή προεπισκόπησης μπορεί να φτάσει σε άλλο κόμβο και να μην βρει τη μεταφόρτωση. Καταχωρίστε το κοινόχρηστο, κρυπτογραφημένο κατάστημα widget μία φορά, μετά το AddDoconut():

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

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // ένας φάκελος που κάθε κόμβος μπορεί να διαβάσει και να γράψει
    store.FarmKey = farmKey;                   // τουλάχιστον 32 bytes, ταυτόσιο σε κάθε κόμβο
    // store.Ttl = TimeSpan.FromMinutes(30);   // πόσο διαρκεί η αποθήκευση ενός ανεβάσματος (η προεπιλογή)
});
  • Ένας μόνος διακομιστής δεν χρειάζεται τίποτα: χωρίς αυτήν την κλήση χρησιμοποιείται η αποθήκη στη μνήμη.
  • Οι μεταφορτώσεις και τα αποτελέσματα κρυπτογραφούνται κατά την αποθήκευση στο κοινόχρηστο (AES-256, encrypt-then-MAC), και κάθε αρχείο δεσμεύεται στο token του, ώστε ένα token να μην μπορεί ποτέ να διαβάσει το αρχείο κάποιου άλλου.
  • Στο κοινόχρηστο, μια μεταφόρτωση ή ένα αποτέλεσμα διατηρείται για Ttl μετά τη δημιουργία του· η ανάγνωσή του δεν επεκτείνει αυτό το παράθυρο.
  • FarmKey πρέπει να είναι τουλάχιστον 32 byte και το ίδιο σε κάθε κόμβο. Φορτώστε το από μυστική αποθήκη· μην το κωδικοποιείτε σκληρά. Η καταχώριση ρίχνει ένα ArgumentException όταν το RootPath λείπει ή το FarmKey είναι μικρότερο από 32 byte.
  • Κατευθύνετε το RootPath στην ίδια κοινόχρηστη τοποθεσία που χρησιμοποιεί ο κατανεμημένος viewer.

Αναφορά API

Η πρόσοψη και οι επιλογές του widget βρίσκονται στον χώρο ονομάτων 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);
}

Λαμβάνεται μέσω dependency injection· ο κατασκευαστής είναι εσωτερικός. Το 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 ώστε οι κλήσεις να μπορούν να αλυσιδωθούν.

Επίλυση προβλημάτων

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

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