Πώς Λειτουργεί ο Προβολέας

Το Doconut αποδίδει έγγραφα ως σελίδες εικόνων που εξυπηρετούνται μέσω του μεσαίου λογισμικού ASP.NET Core. Η κατανόηση του κύκλου ζωής — άνοιγμα, διακριτικό, αιτήματα σελίδων, κλείσιμο — εξηγεί σχεδόν κάθε συμπεριφορά που θα παρατηρήσετε, συμπεριλαμβανομένων των μηνυμάτων σφάλματος.

Τα τρία κινούμενα μέρη

• Viewer — η δημόσια υπηρεσία που ενσωματώνετε. Ανοίγει έγγραφα και επιστρέφει διακριτικά συνεδρίας.
• Η συνεδρία εγγράφου — ένα αντικείμενο στο διακομιστή που κρατά το φορτωμένο έγγραφο, κλειδωμένο με ένα διακριτικό στο IMemoryCache.
• Το μεσαίο λογισμικό Doconut — προστίθεται από UseDoconut()· απαντά σε κάθε αίτημα που κάνει το συστατικό του προγράμματος περιήγησης (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

1. Πύλη άδειας. Μια απορριφθείσα ή λήξη έκδοσης άδεια (μαύρη λίστα, παραποιημένη, ή μια έκδοση εκτός του παραθύρου ενημέρωσης της άδειας) ρίχνει αμέσως ένα LicenseException, με τον λόγο απόρριψης ως μήνυμα — το άνοιγμα δεν υποβαθμίζεται σιωπηρά για μια μη έγκυρη (αντί για απουσία) άδεια. Μια λήξη ημερολογίου για προσωρινή ή συνδρομητική άδεια είναι η εξαίρεση: δεν ρίχνει — υποβαθμίζεται σε υδατογράφημα.
2. Δημιουργία συνεδρίας. Η εργοστασιακή μονάδα προβολέα επιλέγει τον κατάλληλο προβολέα μορφής για την επέκταση αρχείου και φορτώνει το έγγραφο (δείτε το Rendering Pipeline). Η συνεδρία αποθηκεύεται στο IMemoryCache κάτω από ένα νέο GUID διακριτικό με συγγενή λήξη — DocOptions.TimeOut λεπτά, προεπιλογή 60. Κάθε αίτημα σελίδας επαναφέρει το ρολόι.
3. Καταχώρηση ασφαλείας. Με UnsafeMode = false (η προεπιλογή), το διακριτικό δεσμεύεται στη συνεδρία ASP.NET του καλούντος: ένας δείκτης secure-{token} γράφεται στη συνεδρία, ώστε μόνο η συνεδρία του προγράμματος περιήγησης που άνοιξε το έγγραφο να μπορεί να ζητήσει τις σελίδες του.
4. Το διακριτικό επιστρέφεται. Είναι το μοναδικό διαπιστευτήριο για όλα όσα ακολουθούν.

Οι τρεις υπερφορτώσεις διαφέρουν μόνο στην είσοδο: μια διαδρομή αρχείου, μια διαδρομή αρχείου συν μια διαμόρφωση ανά μορφή (PdfConfig, WordConfig, …), ή ένα Stream συν ένα FileInfo του οποίου η επέκταση καθορίζει την ανίχνευση μορφής.

Πώς το συστατικό λαμβάνει σελίδες

Το συστατικό πελάτη καλεί το μεσαίο λογισμικό Doconut με το διακριτικό στη συμβολοσειρά ερωτήματος. Η ενέργεια του μεσαίου λογισμικού εξαρτάται από το αίτημα:

Κάθε μία από αυτές τις διαδρομές επικυρώνεται πρώτα:

• Χωρίς διακριτικό → το μεσαίο λογισμικό επιστρέφει 404 (ή μια διαφήμιση έκδοσης όταν ShowDoconutInfo = true).
• Άγνωστο ή ληγμένο διακριτικό → μια εικόνα σφάλματος με Document session not found. Please re-open document.
• Απουσία μεσαίου λογισμικού συνεδρίας (με 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 μπορεί να ενσωματωθεί και να μοιραστεί ελεύθερα· οι συνεδρίες μεταφέρουν όλη την κατάσταση.