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

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

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

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

dotnet add package Doconut.NETStandard.Converter

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

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

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

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

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

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

Το viewer.Converter.GetConverter() δεν υπάρχει εδώ. Η μετατροπή δεν προσεγγίζεται πλέον μέσω του αντικειμένου viewer: ενσωματώστε το Doconut.DocumentConverter αντ' αυτού.

// Ενθέστε το DocumentConverter· ο κατασκευαστής του είναι εσωτερικός, οπότε ποτέ μην το `new`.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// Το sourceExtension περιλαμβάνει την αρχική τελεία. Το password είναι null εκτός αν το document είναι προστατευμένο.
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) ως ροή, όπως κάθε άλλο αποτέλεσμα μετατροπής.

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

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

Αυτό το enum καλύπτει κάθε οικογένεια πηγής. Η προηγούμενη βιβλιοθήκη είχε τύπο *ConfigConverter ανά οικογένεια — WordConfigConverter, ExcelConfigConverter, κ.λπ. — ο καθένας με το δικό του ένθετο enum EnTargetFormat, συν ένα enum SourceFormatConverter για την είσοδο. Όλα αυτά έχουν αφαιρεθεί· δείτε τον οδηγός μετάβασης.

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

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

Τα ?convert=open|run|download τελικά σημεία του widget είναι προαιρετικά και απενεργοποιημένα από προεπιλογή — ασφαλή από προεπιλογή. Ενεργοποιήστε τα στην πλευρά του διακομιστή, μαζί με την καταχώριση του 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= τελικά σημεία απαντούν 404 — αλλά το αρχείο JS εξυπηρετείται ακόμη ανεξαρτήτως (είναι ένας απλός ενσωματωμένος στατικός πόρος· μόνο τα τελικά σημεία στα οποία επικοινωνεί είναι περιορισμένα). 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· δεν κάνει τίποτα εκτός αν είναι σε κατάσταση idle
conv.destroy();       // αφαιρεί τους listeners, αδειάζει το mount· η instance είναι αχρησιμοποίητη μετά από αυτό

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

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

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

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

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

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

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

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

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

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

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

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