Πρόσθετο Μετατροπέα
Μετατροπή εγγράφων σε 45 μορφές-στόχους
Το πρόσθετο Converter μετατρέπει το Doconut σε υπηρεσία μετατροπής εγγράφων. Συμβάλλει στη μηχανή πίσω από τη δημόσια DocumentConverter διεπαφή, και — με επιλογή — ένα ενσωματωμένο widget με το δικό του συμβόλαιο HTTP, ώστε να μπορείτε να μετατρέπετε έγγραφα από C#, από το widget ή από ένα frontend που γράφετε εσείς.
| Διασύνδεση | Χρησιμοποιήστε το όταν |
|---|---|
DocumentConverter (C#) | Μετατρέπετε στον διακομιστή, χωρίς να εμπλέκεται πρόγραμμα περιήγησης |
Widget ενσωμάτωσης (doconutConverter.js) | Θέλετε μια έτοιμη οθόνη μεταφόρτωσης, μετατροπής και λήψης στη σελίδα σας |
Τελικά σημεία HTTP (?convert=open|run|download) | Δημιουργείτε το δικό σας UI μετατροπής σύμφωνα με ένα τεκμηριωμένο συμβόλαιο διακομιστή |
Εγκατάσταση του πακέτου
Εγκαταστήστε το πιο πρόσφατο σταθερό πρόσθετο Converter:
dotnet add package Doconut.NET8.ConverterΓια να κλειδώσετε το πρόσθετο στην έκδοση που περιγράφει αυτή η τεκμηρίωση, περάστε την έκδοση ξεχωριστά:
dotnet add package Doconut.NET8.Converter --version 26.10.0Διατηρήστε το πακέτο Converter στην ίδια έκδοση με το Doconut.NET8. Το αναγνωριστικό πακέτου είναι
Doconut.NET8.Converter· .<version> εμφανίζεται μόνο στο ληφθέν όνομα αρχείου .nupkg.
Το αρχείο άδειας του πρόσθετου, Doconut.Viewer.Converter.lic, τοποθετείται στον ίδιο φάκελο με το Doconut.Viewer.lic· διαβάζεται μαζί με την άδεια του προβολέα.
Πλατφόρμες. Το πρόσθετο λειτουργεί όπου τρέχει το Doconut.NET8: Windows και Linux βασισμένο σε glibc σε x64 (όχι Alpine ή άλλες διανομές βασισμένες σε musl). Σε Linux, εγκαταστήστε τη βιβλιοθήκη διαμόρφωσης γραμματοσειρών πριν ανοίξει το πρώτο έγγραφο:
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.NET8.Converter, εγκατεστημένο παράλληλα με το βασικό πακέτο προβολέα.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});Αυτό είναι ό,τι χρειάζεται η διεπαφή C#. Το widget και τα HTTP endpoints του είναι μια ξεχωριστή επιλογή, AddConverterWidget() (δείτε το Widget ενσωμάτωσης).
Το πρόσθετο χρειάζεται άδεια που χορηγεί τη δυνατότητα Converter. Χωρίς αυτή, το AddDoconut() ρίχνει ένα InvalidOperationException κατά την εκκίνηση, πριν η εφαρμογή εξυπηρετήσει ένα αίτημα:
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. Δεν υπάρχει σιωπηλό δωρεάν επίπεδο. Δείτε το Ρύθμιση Άδειας για το πώς φορτώνονται οι άδειες.
Άδεια & υδατογράφημα
| Κατάσταση άδειας | Εκκίνηση | Αποτέλεσμα μετατροπής |
|---|---|---|
Πληρωμένη άδεια προβολέα που χορηγεί 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 όπου και αν το χρειάζεστε — είναι χωρίς κατάσταση κατά το σχεδιασμό, έτσι ένα μόνο αντίγραφο είναι ασφαλές για επαναχρησιμοποίηση σε πολλαπλά αιτήματα.
// Ενθέστε το DocumentConverter· ο κατασκευαστής του είναι εσωτερικός, οπότε ποτέ μην το `new`.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// Το sourceExtension περιλαμβάνει την αρχική τελεία. Το password είναι null εκτός αν το έγγραφο είναι προστατευμένο.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// 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 μέλη:
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 είναι προαιρετικά και απενεργοποιημένα από προεπιλογή — ασφαλή από προεπιλογή. Ενεργοποιήστε τα στο διακομιστή, μαζί με την καταχώρηση του πρόσθετου:
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() ρίχνει εξαίρεση:
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 εξακολουθεί να σερβίρεται ανεξαρτήτως (είναι ένας απλός ενσωματωμένος στατικός πόρος· μόνο τα τελικά σημεία στα οποία επικοινωνεί είναι περιορισμένα).
Ενσωμάτωση
<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, μετατρέπει, προεπισκοπεί το αποτέλεσμα όταν μπορεί, και προσφέρει τη λήψη.
Επιλογές
| Επιλογή | Τύπος | Προεπιλογή | Σημειώσεις |
|---|---|---|---|
basePath | string | /doconut | Βασική διαδρομή για τα σημεία άκρης ?convert=· πρέπει να ταιριάζει με το κλαδί ASP.NET όπου το UseDoconut() είναι πραγματικά προσαρτημένο (συνήθως συντονισμένο μέσω MiddlewarePath) |
resPath | string | /doconut-res | Αποδεκτό για συνέπεια ρυθμίσεων με άλλα Doconut widget· το widget μετατροπέα αυτή τη στιγμή δεν δημιουργεί κανένα URL από αυτό |
maxUploadMb | number | 25 | Μόνο προέλεγχος στην πλευρά του πελάτη — απορρίπτει ένα υπερβολικά μεγάλο αρχείο πριν τη μεταφόρτωση. Ο διακομιστής επιβάλλει το δικό του όριο ανεξάρτητα και επιστρέφει 413 εάν το υπερβεί |
licenseUrl | string | null | null | Όταν οριστεί, μετατρέπει την ειδοποίηση υδατογραφήματος στην οθόνη αποτελεσμάτων σε σύνδεσμο προς αυτό το URL |
labels | object | {} | Αντικαθιστά οποιοδήποτε υποσύνολο των προεπιλεγμένων αγγλικών συμβολοσειρών του 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 προγραμματιστικά:
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; no-op εκτός εάν είναι αυτή τη στιγμή idle
conv.destroy(); // αφαιρεί τους listeners, αδειάζει το mount; η instance δεν είναι χρήσιμη μετά από αυτόΕτικέτες
Κάθε συμβολοσειρά έχει προεπιλογή στα αγγλικά· labels αντικαθιστά οποιοδήποτε υποσύνολο και τα υπόλοιπα παραμένουν αγγλικά. Τα τμήματα που αλλάζουν κατά την εκτέλεση χρησιμοποιούν {placeholders}, όπως uploading: 'Uploading {name}…' και pages: '{n} pages'.
| Κλειδί | Προεπιλογή αγγλικών |
|---|---|
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. |
Περαιτέρω κλειδιά καλύπτουν το 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, ώστε να μπορείτε να το θεματίσετε χωρίς να αγγίξετε τα εσωτερικά του:
#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> | Μετατροπή του αποθηκευμένου πηγαίου σε target | 200 — { 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 του προγράμματος περιήγησης δεν επεκτείνει κανένα από τα δύο παράθυρα.
Λειτουργίες αποτυχίας, ομαδοποιημένες ανά διαδρομή:
| Διαδρομή | Κατάσταση | Πότε | Σώμα |
|---|---|---|---|
| οποιαδήποτε | 404 | Το widget δεν είναι ενεργοποιημένο (AddConverterWidget() δεν κλήθηκε ποτέ) — ελέγχεται πριν την εκτέλεση οποιασδήποτε από τις τρεις διαδρομές | μόνο κατάσταση |
| οποιαδήποτε | 405 | Λάθος HTTP verb (open/run απαιτούν POST· download απαιτεί GET) | μόνο κατάσταση |
open | 400 | Δεν είναι multipart ανέβασμα | Expected a multipart file upload. |
open | 400 | Δεν υπάρχει αρχείο, ή είναι κενό | No file uploaded. |
open | 400 | Μια επέκταση πηγής που δεν μπορεί να μετατραπεί | This file type cannot be converted. |
open | 403 | Ο τύπος αρχείου απαιτεί δυνατότητα που δεν παρέχει η άδεια (αρχείο DICOM χωρίς Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | Το ανεβασμένο αρχείο υπερβαίνει το MaxUploadMb, ελέγχεται έναντι του Content-Length και κατά την ανάγνωση του ανεβάσματος | File is too large. |
run | 400 | Κακοδιατυπωμένο token (δεν είναι GUID) | Invalid token. |
run | 400 | Ένα target που δεν αναλύεται σε ConversionTarget | Unknown target format. |
run | 400 | target δεν βρίσκεται στην allowedTargets του πηγής | That target format is not available for this file. |
run | 404 | Το αποθηκευμένο ανέβασμα έχει λήξει ή το token δεν ανοίχθηκε ποτέ | Upload expired — please re-open the file. |
open, run | 500 | Η επεξεργασία απέτυχε εσωτερικά | Ένα εξομαλυνμένο μήνυμα — εξομαλυνμένο με τον ίδιο τρόπο όπως κάθε άλλη διαδρομή σφάλματος Doconut· δεν αποκαλύπτει ποτέ εσωτερικές λεπτομέρειες |
download | 400 | Κακοδιατυπωμένο token (δεν είναι GUID) | μόνο κατάσταση |
download | 404 | Άγνωστο ή ληγμένο token λήψης | μόνο κατάσταση |
Μια πλήρης διαδρομή με fetch:
// αρχείο: το αρχείο για μετατροπή, για παράδειγμα από ένα <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 σας.
Σε παραγωγή
- Εγκαταστήστε το πρόσθετο δίπλα στο βασικό πακέτο, στην ίδια έκδοση:
dotnet add package Doconut.NET8.Converter. - Προσθέστε το αρχείο άδειας. Τοποθετήστε
Doconut.Viewer.Converter.licστον ίδιο φάκελο με τοDoconut.Viewer.lic. - Ορίστε το όριο του διακομιστή.
MaxUploadMbστοAddConverterWidgetείναι το όριο που επιβάλλει ο διακομιστής· τοmaxUploadMbτου widget είναι μόνο ένας έλεγχος στην πλευρά του πελάτη. Διατηρήστε τα δύο ίσα. - Σερβίρετε το UI από την ίδια προέλευση με τα σημεία τέλους του Doconut, ή κάντε reverse-proxy (δείτε Δημιουργήστε το δικό σας frontend).
- Απορρίψτε τα αποτελέσματα μετατροπής. Η ροή που επιστρέφει το
ConvertAsyncείναι σε δεξαμενή· η απόρριψή της επιστρέφει τα buffers στην δεξαμενή.
Φάρμες ιστού
Το widget διατηρεί κάθε μεταφόρτωση και το αποτέλεσμα της στη μνήμη στον κόμβο που εξυπηρέτησε το open. Πίσω από έναν φορτωτή ισορροπίας χωρίς sticky sessions, ένα μεταγενέστερο αίτημα run, download ή προεπισκόπησης μπορεί να φτάσει σε άλλο κόμβο και να μην βρει τη μεταφόρτωση. Καταχωρίστε το κοινόχρηστο, κρυπτογραφημένο κατάστημα widget μία φορά, μετά το AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.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 βρίσκονται στον χώρο ονομάτων Doconut· το ConversionTarget βρίσκεται στο Doconut.Configs.Conversion. Το ConverterPlugin βρίσκεται στο 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);
}Λαμβάνεται μέσω dependency injection· ο κατασκευαστής είναι εσωτερικός. Το sourceExtension περιλαμβάνει την αρχική τελεία. Το HtmlToWordAsync γράφει ένα αρχείο .doc όταν το outputFormat είναι ConversionTarget.Doc, και ένα αρχείο .docx για οποιαδήποτε άλλη τιμή.
ConversionTarget
Οι 45 μορφές εξόδου που αναφέρονται στα Μορφές στόχου.
ConverterWidgetOptions
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 φορτώνει αλλά τα αιτήματά του απαντούν με 404 | Το AddConverterWidget() δεν κλήθηκε, ή το 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 |
Ήταν αυτή η σελίδα χρήσιμη;