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

Το πρόσθετο Converter μετατρέπει το Doconut σε μια υπηρεσία μετατροπής εγγράφων. Συνεισφέρει τη μηχανή πίσω από το δημόσιο DocumentConverter façade και — με επιλογή — ένα ενσωματωμένο 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 όπου το χρειάζεστε — είναι χωρίς κατάσταση (stateless) από τη σχεδίαση, οπότε ένα μόνο στιγμιότυπο είναι ασφαλές για επαναχρησιμοποίηση σε πολλαπλά αιτήματα.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
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

Τα σημεία λήψης ?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;
    });
});

<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() εξακολουθεί να απαιτεί το πρόσθετο Converter να είναι καταχωρισμένο και μια άδεια που παρέχει Converter — δεν παρέχει δικαιώματα μετατροπής από μόνο του.

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

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

Κλήσεις επιστροφής (callbacks):

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

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

Δημιουργία του δικού σας frontend

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

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

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

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

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

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

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

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

Υδατογράφημα (Watermarking)

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

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