Πώς λειτουργεί ο Viewer
Ο κύκλος ζωής του αιτήματος εγγράφου
Το Doconut αποδίδει έγγραφα ως σελίδες εικόνων που εξυπηρετούνται μέσω του ASP.NET Core middleware. Η κατανόηση του κύκλου ζωής — άνοιγμα, διακριτικό, αιτήματα σελίδων, κλείσιμο — εξηγεί σχεδόν κάθε συμπεριφορά που θα παρατηρήσετε, συμπεριλαμβανομένων των μηνυμάτων σφάλματος.
Τα τρία κινούμενα μέρη
Viewer— η δημόσια υπηρεσία που ενσωματώνετε. Ανοίγει έγγραφα και επιστρέφει διακριτικά συνεδρίας.- Η συνεδρία εγγράφου — ένα αντικείμενο στο διακομιστή που κρατά το φορτωμένο έγγραφο, κλειδωμένο με ένα διακριτικό στο
IMemoryCache. - Το Doconut middleware — προστίθεται από
UseDoconut()· απαντά σε κάθε αίτημα που κάνει το widget του προγράμματος περιήγησης (pages,thumbnails,search,annotations, …), πάντα πιστοποιημένο με το διακριτικό.
Viewer είναι χωρίς κατάσταση — κατά σχεδιασμό
Viewer είναι κλειδωμένο, δεν κρατά κατάσταση εγγράφου ανά αίτημα, και σκόπιμα δεν υλοποιεί IDisposable. Οι συνεδρίες ζουν ανεξάρτητα στον διαχειριστή συνεδριών και καθαρίζονται με τη λήξη της προσωρινής μνήμης ή με ένα ρητό CloseDocument(token).
Ενσωματώστε το όπου χρειάζεστε:
app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
var token = await viewer.OpenDocumentAsync($"files/{fileName}");
return Results.Content(token, "text/plain");
});Τι συμβαίνει μέσα στο OpenDocumentAsync
- Πύλη άδειας. Μια απορριφθείσα ή λήξη έκδοσης άδειας (μαύρη λίστα, παραποιημένη, ή μια έκδοση εκτός του παραθύρου ενημέρωσης της άδειας) ρίχνει αμέσως ένα
LicenseException, με τον λόγο απόρριψης ως μήνυμα — το άνοιγμα δεν υποβαθμίζεται σιωπηρά για μια μη έγκυρη (αντί για απουσία) άδεια. Μια λήξη ημερολογίου για προσωρινή ή συνδρομητική άδεια αποτελεί την εξαίρεση: δεν ρίχνει — υποβαθμίζεται σε υδατογράφημα. - Δημιουργία συνεδρίας. Η εργοστασιακή μονάδα του προβολέα επιλέγει τον κατάλληλο προβολέα μορφής για την επέκταση αρχείου και φορτώνει το έγγραφο (δείτε το Rendering Pipeline). Η συνεδρία αποθηκεύεται στο
IMemoryCacheκάτω από ένα νέο διακριτικό GUID με κυλιόμενη λήξη —DocOptions.TimeOutλεπτά, προεπιλογή 60. Κάθε αίτημα σελίδας επαναφέρει το χρονόμετρο. - Καταγραφή ασφαλείας. Με
UnsafeMode = false(η προεπιλογή), το διακριτικό δεσμεύεται στη συνεδρία ASP.NET του καλούντος: έναsecure-{token}σημάδι γράφεται στη συνεδρία, ώστε μόνο η συνεδρία του προγράμματος περιήγησης που άνοιξε το έγγραφο να μπορεί να ζητήσει τις σελίδες του. - Το διακριτικό επιστρέφεται. Είναι το μοναδικό διαπιστευτήριο για όλα όσα ακολουθούν.
Οι τρεις υπερφορτώσεις διαφέρουν μόνο στην είσοδο: μια διαδρομή αρχείου, μια διαδρομή αρχείου συν μια διαμόρφωση ανά μορφή (PdfConfig, WordConfig, …), ή ένα Stream συν ένα FileInfo του οποίου η επέκταση καθορίζει την ανίχνευση μορφής.
Πώς το widget λαμβάνει σελίδες
Το widget του πελάτη καλεί το Doconut middleware με το διακριτικό στη συμβολοσειρά ερωτήματος. Η ενέργεια του middleware εξαρτάται από το αίτημα:
| Ερώτημα | Σκοπός |
|---|---|
?token=…&page=N | Εικόνα σελίδας (PNG) |
?token=…&page=N&thumb=1 | Μικρογραφία |
?token=…&zoom=… | Απόδοση σελίδας με ζουμ |
?token=…&search=term | Αναζήτηση πλήρους κειμένου (με πύλη άδειας) |
?token=…&bookmarks | Δομή εγγράφου/σελιδοδείκτες |
?token=…© / &showlinks / &fileFormat | Αντιγραφή κειμένου, υπερσυνδέσεις και πληροφορίες μορφής |
?token=…&meta | Τεχνικά μεταδεδομένα DICOM· επιστρέφει 501 για συνεδρία DICOM σε .NET 6 |
?token=…&action=rotate/flip/close | Ενέργειες σελίδας και ρητό κλείσιμο |
?token=…&AnnSave=… / &AnnLoad | Αποθήκευση/φόρτωση σχολίων |
Κάθε μία από αυτές τις διαδρομές επικυρώνεται πρώτα:
- Χωρίς διακριτικό → το middleware επιστρέφει 404 (ή μια διαφήμιση έκδοσης όταν
ShowDoconutInfo = true). - Άγνωστο ή ληγμένο διακριτικό → μια εικόνα σφάλματος με
Document session not found. Please re-open document. - Απουσία middleware συνεδρίας (με
UnsafeMode = false) → HTTP 500 μεSession middleware not configured. Call UseSession() before UseDoconut(). - Διακριτικό ανοιγμένο από διαφορετική συνεδρία προγράμματος περιήγησης → μια εικόνα σφάλματος με
You Are Not Authorized To View This Page.
Η εξυπηρέτηση σελίδων από κοινόχρηστη αποθήκη αντί για τον κόμβο ανοίγματος είναι μια εντελώς διαφορετική διάταξη· δείτε το Κατανεμημένες Αναπτύξεις.
Κλείσιμο εγγράφου
viewer.CloseDocument(token);CloseDocument αφαιρεί τη συνεδρία από την προσωρινή μνήμη (που απελευθερώνει τη βασική μηχανή εγγράφου και ελευθερώνει τη μνήμη της αμέσως), διαγράφει το σημάδι secure-{token} και ανακαλεί την άδεια πρόσβασης. Η κλήση του είναι προαιρετική — η κυλιόμενη λήξη κάνει την ίδια εκκαθάριση αυτόματα — αλλά για μεγάλα έγγραφα είναι ο ευγενικός τρόπος να ελευθερώσετε τη μνήμη τη στιγμή που ο χρήστης ολοκληρώνει.
Συμπεράσματα
- Ένα ανοιχτό έγγραφο = μία συνεδρία = ένα διακριτικό. Τα διακριτικά είναι ανά συνεδρία προγράμματος περιήγησης, όχι παγκόσμια URLs.
- Το διακριτικό λήγει σε κυλιόμενο παράθυρο· ένας προβολέας που παραμένει αδρανής πέρα από
DocOptions.TimeOutχρειάζεται νέο άνοιγμα. Viewerμπορεί να ενσωματωθεί και να μοιραστεί ελεύθερα· οι συνεδρίες μεταφέρουν όλη την κατάσταση.
Ήταν αυτή η σελίδα χρήσιμη;