Καταχώριση και ενεργοποίηση του widget μετατροπέα drop‑in του Doconut σε .NET 8

Το widget drop‑in είναι το έτοιμο UI του Doconut για μεταφόρτωση αρχείου, εκτέλεση μετατροπής και λήψη του αποτελέσματος.
Από προεπιλογή τα τρία ?convert= endpoints του widget επιστρέφουν 404· γίνονται ενεργά μόνο όταν καταχωρίσετε το plugin Converter και καλέσετε AddConverterWidget() στο DoconutOptions.
Παρακάτω υπάρχει μια πλήρης, έτοιμη για αντιγραφή, διαμόρφωση εκκίνησης που ικανοποιεί και τις δύο απαιτήσεις.

---

1. Προαπαιτούμενα – άδεια και υποστήριξη συνεδρίας

• Άδεια – Το plugin Converter απαιτεί άδεια που παρέχει τη δυνατότητα Converter. Τοποθετήστε το αρχείο (π.χ., Doconut.Viewer.lic) κάπου προσβάσιμο από την εφαρμογή και κατευθύνετε το DoconutOptions.LicensePath σε αυτό.
• Κατάσταση συνεδρίας – Το μοντέλο ασφαλείας του Doconut αποθηκεύει τα tokens συνεδρίας εγγράφου στην συνεδρία ASP.NET Core. Προσθέστε μια κατανεμημένη κρυφή μνήμη και AddSession() πριν συνδεθεί το middleware.

builder.Services.AddDistributedMemoryCache();   // απαιτείται για τη συνεδρία
builder.Services.AddSession();                  // ενεργοποιεί συνεδρία με υποστήριξη IDistributedCache

---

2. Καταχώριση των βασικών υπηρεσιών Doconut

AddDoconut() είναι το μοναδικό σημείο εισόδου που ενσωματώνει το viewer, την υπηρεσία άδειας και το μητρώο plugin.

builder.Services.AddDoconut(options =>
{
    // Πείτε στο Doconut πού να βρει το αρχείο άδειας.
    options.LicensePath = "Doconut.Viewer.lic";

    // Καταχωρίστε το πρόσθετο Converter – αυτό επίσης επικυρώνει τη δυνατότητα άδειας.
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Αν η άδεια δεν περιλαμβάνει τη δυνατότητα Converter, η παραπάνω κλήση ρίχνει InvalidOperationException και η εφαρμογή δεν θα ξεκινήσει. Αυτή η συμπεριφορά fail‑fast σας αποτρέπει από την ανάπτυξη μιας λανθασμένης άδειας.

---

3. Ενεργοποίηση του widget με AddConverterWidget

Το widget είναι προαιρετικό. Η κλήση του AddConverterWidget() καταχωρίζει τα τρία endpoints μετατροπής (?convert=open, ?convert=run, ?convert=download) και συνδέει μια μικρή ποσότητα ρυθμίσεων στην πλευρά του πελάτη (μέγιστο μέγεθος μεταφόρτωσης, βασικές διαδρομές κ.λπ.).

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

    // Ενεργοποιήστε το UI drop‑in και ορίστε το όριο ανεβάσματος στην πλευρά του πελάτη.
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;   // προέλεγχος πελάτη; ο διακομιστής επιβάλλει το δικό του όριο
    });
});

Μόνο η κλήση AddConverterWidget δημιουργεί τα endpoints· το στατικό αρχείο JavaScript (doconutConverter.js) σερβίρεται πάντα ως ενσωματωμένος πόρος, αλλά θα αποτύχει να επικοινωνήσει με τον διακομιστή εάν λείπουν τα endpoints.

---

4. Σύνδεση του middleware με τη σωστή σειρά

Το middleware που σερβίρει στατικά περιουσιακά στοιχεία (UseDoconutResources) πρέπει να εκτελείται πριν από το τελικό middleware viewer (UseDoconut). Το middleware συνεδρίας πρέπει επίσης να τοποθετηθεί νωρίτερα επειδή το Doconut επικυρώνει τη συνεδρία σε κάθε αίτημα.

app.UseSession();           // πρέπει να προηγείται του UseDoconut()
app.UseDoconutResources();  // σερβίρει JS, CSS, εικόνες
app.UseDoconut();           // χειρίζεται αιτήματα ?convert= και σελίδων εγγράφου

Με αυτή τη σειρά ενεργή, ένα αίτημα προς /doconut-res/doconutConverter.js επιτυγχάνει, και το widget μπορεί να καλέσει τα /doconut?convert=open, /doconut?convert=run και /doconut?convert=download.

---

5. Τι κάνει πραγματικά το widget

Φάση	Endpoint διακομιστή	Τυπική απόκριση
Άνοιγμα	?convert=open	Επιστρέφει ένα JSON payload που περιέχει ένα token, αριθμό σελίδων, επέκταση πηγής και τη λίστα των επιτρεπόμενων μορφών προορισμού.
Εκτέλεση	?convert=run	Ξεκινά τη μετατροπή και επιστρέφει ένα downloadToken, αριθμό σελίδων αποτελέσματος, προτεινόμενο όνομα αρχείου και μια σημαία που υποδεικνύει αν το αποτέλεσμα έχει υδατογράφημα.
Λήψη	?convert=download	Μεταδίδει το μετατρεπόμενο αρχείο όταν ο πελάτης ακολουθεί το παρεχόμενο URL λήψης.

Στην πλευρά του πελάτη, το widget εκτελεί έναν έλεγχο μεγέθους προ‑μεταφόρτωσης έναντι του widget.MaxUploadMb. Εάν το αρχείο υπερβαίνει αυτό το όριο, το widget ακυρώνει τη μεταφόρτωση και ενεργοποιεί την κλήση επιστροφής onError με phase = "open" και ένα φιλικό μήνυμα. Ο διακομιστής επιβάλλει το δικό του όριο και θα απαντήσει 413 Payload Too Large εάν το αίτημα περάσει τον έλεγχο του πελάτη.

---

6. Σύνδεση με τα γεγονότα του widget (δεν απαιτείται κώδικας C#)

Όλες οι κλήσεις επιστροφής (onReady, onSourceLoaded, onConverted, onError, κ.λπ.) είναι συναρτήσεις JavaScript που παρέχονται από τη σελίδα που φιλοξενεί το widget. Επειδή η ερώτηση εστιάζει στην πλευρά της καταχώρισης, δεν χρειάζεται να γράψετε επιπλέον κώδικα C# για να διαχειριστείτε αυτές τις κλήσεις – το widget τις ενεργοποιεί αυτόματα μόλις τα endpoints είναι ενεργά.

---

7. Συνηθισμένα προβλήματα και πώς να τα αποφύγετε

Συμπτωμα	Πιθανή αιτία	Διόρθωση
404 on /doconut?convert=open	AddConverterWidget() παραλείφθηκε.	Προσθέστε την κλήση όπως φαίνεται στην ενότητα 3.
Η εφαρμογή αποτυγχάνει να ξεκινήσει με InvalidOperationException σχετικά με έλλειψη δυνατότητας	Το αρχείο άδειας δεν παρέχει Converter.	Αποκτήστε άδεια που περιλαμβάνει τη δυνατότητα Converter.
Σφάλμα σχετικό με συνεδρία 500	UseSession() τοποθετήθηκε μετά το UseDoconut() ή λείπει η καταγραφή της κρυφής μνήμης.	Βεβαιωθείτε ότι το app.UseSession() εκτελείται πριν το app.UseDoconut() και ότι μια υπηρεσία κρυφής μνήμης είναι καταγεγραμμένη.

---

8. Εκτέλεση της εφαρμογής και προβολή του widget σε δράση

1. Κατασκευάστε και εκτελέστε το έργο ASP.NET Core.
2. Ανοίξτε μια σελίδα που περιέχει ένα στοιχείο <div id="doconut-convert"></div> και περιλαμβάνει το script μετατροπέα Doconut (το script σερβίρεται αυτόματα από /doconut-res/doconutConverter.js).
3. Σύρετε ένα υποστηριζόμενο αρχείο (PDF, DOCX, DWG, κ.λπ.) στην περιοχή αποδέκτη.
4. Το widget θα καλέσει το ?convert=open, έπειτα το ?convert=run, και τελικά θα παρουσιάσει έναν σύνδεσμο Λήψη που οδηγεί στο ?convert=download.

Εάν τα τρία endpoints απαντούν με JSON αντί για 404, το widget είναι σωστά καταχωρημένο και έτοιμο για παραγωγική χρήση.

---

Επόμενο βήμα: Προσθέστε τα παραπάνω αποσπάσματα κώδικα στο Program.cs (ή στο Startup.cs), επαληθεύστε ότι το αρχείο άδειας υπάρχει, και εκκινήστε την εφαρμογή. Το widget μετατροπέα drop‑in θα είναι ενεργό χωρίς περαιτέρω αλλαγές στην πλευρά του διακομιστή.