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

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

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

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

dotnet add package Doconut.NET6.Converter

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

dotnet add package Doconut.NET6.Converter --version 26.7.0

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

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

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

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

Αυτή η κλήση αποτυγχάνει κατά την εκκίνηση λόγω έλλειψης άδειας, ενός παλαιού αρχείου TRIAL, ή μη προσωρινής άδειας που δεν παρέχει τη δυνατότητα Converter — ένα InvalidOperationException που προέρχεται από το AddDoconut(), πριν η εφαρμογή εξυπηρετήσει αιτήματα. Δέχονται προσωρινές εγγραφές Demo/NFR· μετά τη λήξη του ημερολογίου τους, η μετατροπή παραμένει διαθέσιμη με υδατογράφημα στην έξοδο. Δεν υπάρχει σιωπηλό δωρεάν επίπεδο. Δείτε το Ρύθμιση Άδειας για το πώς φορτώνονται οι άδειες.

Μετατροπή από 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(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

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

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

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Δεν μετατρέπει κάθε πηγή σε κάθε προορισμό — το πρόσθετο αντιστοιχίζει κάθε οικογένεια μορφής πηγής (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document) στο δικό του σταθερό σύνολο επιτρεπτών προορισμών. Μην κωδικοποιείτε σκληρά αυτό το enum ως λίστα προορισμών του UI σας: το ?convert=open επιστρέφει το πραγματικό allowedTargets για οποιοδήποτε αρχείο μόλις ανέβηκε, και αυτό πρέπει να καθοδηγεί έναν επιλογέα.

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

Το widget's ?convert=open|run|download endpoints είναι προαιρετικά και απενεργοποιημένα από προεπιλογή — ασφαλή από προεπιλογή. Ενεργοποιήστε τα από την πλευρά του διακομιστή, μαζί με την καταγραφή του plugin:

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

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

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

Προσαρμογή του widget

Αρχικές επιλογές που περνιούνται στο Doconut.convert(selector, options):

Ανακλήσεις:

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

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // επιστροφή στην οθόνη idle/drop; δεν επανεκκινεί το onReady
conv.loadFile(file);  // εκκινεί τη ροή με ένα αντικείμενο File; no-op εκτός εάν είναι τρέχουσα η κατάσταση idle
conv.destroy();       // αφαιρεί τους listeners, αδειάζει το mount; η instance δεν είναι χρησιμοποιήσιμη μετά από αυτό

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

Το widget είναι απλώς ένας πελάτης για αυτή τη σύμβαση HTTP — δημιουργήστε το δικό σας frontend απευθείας εναντίον της για διαφορετική εμπειρία χρήστη. Όλες οι τρεις διαδρομές βρίσκονται κάτω από το κλάδο ASP.NET όπου το UseDoconut() είναι προσαρτημένο (συνήθως /doconut):

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

Το sourceExt στην απόκριση open δεν έχει αρχική τελεία (π.χ. "docx") — η αντίθετη σύμβαση από την παράμετρο sourceExtension στο DocumentConverter.ConvertAsync, η οποία απαιτεί μία.

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

Ιδιοκτησία πόρων

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

Για το web widget, τα αποθηκευμένα upload και download έχουν ανεξάρτητα TTL 30 λεπτών. Ένας viewer resultToken ακολουθεί τη διάρκεια της συνεδρίας του viewer αντί αυτού. Το κλείσιμο ενός αποτελέσματος viewer δεν διαγράφει ένα ακόμη έγκυρο download stash, και η επαναφορά του widget του προγράμματος περιήγησης δεν επεκτείνει κανένα από τα TTL.

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

Υδατογράφημα

Με εγγεγραμμένο το ConverterPlugin, η άδεια του κεντρικού είναι σε μία από τις τρεις καταστάσεις:

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