Αντιμετώπιση προβλημάτων

Διάγνωση κοινών σφαλμάτων

Κάθε μήνυμα παρακάτω είναι το κυριολεκτικό κείμενο που παράγει το Doconut, οργανωμένο ανά σύμπτωμα. Βρείτε το σφάλμα σας, εφαρμόστε τη διόρθωση.

Ο προβολέας δεν εμφανίζει τίποτα

Κενή περιοχή προβολέα, η κονσόλα του προγράμματος περιήγησης γεμάτη 404 για /doconut-res/...
UseDoconutResources() λείπει, ή τοποθετήθηκε μετά το UseDoconut(). Πρέπει να είναι πρώτο στην αλυσίδα.

HTTP 500 με:

text
Session middleware not configured. Call UseSession() before UseDoconut().

Η ασφάλεια token του Doconut (ενεργοποιημένη εξ ορισμού) απαιτεί κατάσταση συνεδρίας ASP.NET. Προσθέστε builder.Services.AddSession() και app.UseSession() πριν από το κλάδο μεσαρολογίας Doconut. Η κατάσταση συνεδρίας χρειάζεται επίσης μια κρυφή μνήμη: σε μια ελάχιστη εφαρμογή API προσθέστε builder.Services.AddDistributedMemoryCache(), ή η εφαρμογή σταματά κατά την εκκίνηση με Unable to resolve service for type 'IDistributedCache' (οι εφαρμογές MVC και Razor Pages καταχωρούν ήδη μία).

Μια εικόνα σφάλματος στην περιοχή της σελίδας με κείμενο:

text
You Are Not Authorized To View This Page.

Το token άνοιξε από διαφορετική συνεδρία προγράμματος περιήγησης. Συνηθισμένες αιτίες: το cookie συνεδρίας δεν φτάνει στα αιτήματα της σελίδας (ρύθμιση cross-origin, πολιτική SameSite, πελάτης API χωρίς cookie jar), ή η εφαρμογή επανεκκινήθηκε (νέα κλειδιά συνεδρίας). Αυτό είναι το επίπεδο ασφαλείας που λειτουργεί όπως σχεδιάστηκε — δείτε Core Concepts → Sessions & Security.

Μια εικόνα σφάλματος με κείμενο:

text
Document session not found. Please re-open document.

Το token έληξε (παράθυρο ολίσθησης, προεπιλογή 60 λεπτά — DocOptions.TimeOut) ή η συνεδρία κλείστηκε. Ανοίξτε ξανά το έγγραφο για ένα νέο token.

Η έναρξη ενός εγγράφου αποτυγχάνει

LicenseException με μήνυμα απόρριψης — το αρχείο άδειας βρέθηκε αλλά απορρίφθηκε (μη έγκυρη υπογραφή, παραποιημένο, στην μαύρη λίστα, ή μια έκδοση εκτός του παραθύρου έκδοσης/ενημέρωσης της άδειας). Αυτή η κατάσταση εμποδίζει το άνοιγμα (fail-fast) αντί να υποβαθμιστεί σε υδατογράφημα· διαβάστε License.RejectionMessage για τον λόγο.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

Η επέκταση διαχειρίζεται μόνο από ένα πρόσθετο (εδώ: DICOM) και η δυνατότητα δεν χορηγείται πλέον. Καταχωρίστε το πρόσθετο και επαληθεύστε lic.IsCapabilityGranted(LicenseCapability.Dicom). Ένα ελλιπές ή ανεπαρκές μη-προσωρινό δικαίωμα συνήθως αποτυγχάνει νωρίτερα κατά τη διάρκεια του AddDoconut().

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

Κανένας προβολέας — ενσωματωμένος, πρόσθετο ή προσαρμοσμένος — δεν υποστηρίζει αυτήν την επέκταση. Ελέγξτε τη λίστα υποστηριζόμενων μορφών· για τις δικές σας μορφές, το DoconutOptions.RegisterViewer μπορεί να προσθέσει μία.

InvalidDataException — το περιεχόμενο του αρχείου είναι κατεστραμμένο ή δεν ταιριάζει με την επέκταση του (π.χ. ένα μετονομασμένο αρχείο). Επικυρώστε τις μεταφορτώσεις πριν το άνοιγμα.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

Αντιμετωπίσατε το DocumentConverter χωρίς να καταχωρίσετε το πρόσθετο Converter.

Η εκκίνηση αποτυγχάνει

InvalidOperationException που αναφέρει ένα πρόσθετο καταχωρημένο μέσω AddPlugin — η τρέχουσα μη-προσωρινή άδεια δεν χορηγεί αυτήν τη δυνατότητα πρόσθετου. Αφαιρέστε την καταχώρηση ή εγκαταστήστε μια άδεια που το χορηγεί. Μια ελλιπής άδεια και ένα παλιό αρχείο TRIAL δεν χορηγούν καμία δυνατότητα πρόσθετου.

ArgumentException από το AddDoconut():

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Επικύρωση επιλογών fail-fast — διορθώστε τη λανθασμένη διαδρομή.

Σφάλματα κατασκευής / εξαρτήσεων

Σφάλμα μεταγλωττιστή CS1705, ή κατά την εκτέλεση όταν ανοίγετε ένα έγγραφο:

text
Could not load file or assembly 'System.Text.Json, Version=10.0.0.0'

Το έργο σας έδωσε σταθερή έκδοση στο System.Text.Json / System.Text.Encodings.Web κάτω από 10.0.x. Αφαιρέστε την υποβάθμιση και αφήστε το NuGet να επαναφέρει τις εκδόσεις που δηλώνει το Doconut.NET8.

TypeInitializationException στο πρώτο αρχείο παρουσίασης:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

Η μηχανή παρουσίασης απαιτεί αυστηρά το System.Drawing.Common 6.0.0 (δηλωμένο από το πακέτο). Μην αφαιρέσετε ή παρακάμψετε αυτήν την εξάρτηση — κάθε άνοιγμα PPT/PPTX/PPS/POT/ODP αποτυγχάνει χωρίς αυτήν.

Η έξοδος φαίνεται λανθασμένη

Οι σελίδες έχουν υδατογράφημα — η εφαρμογή βρίσκεται σε κατάσταση αξιολόγησης: δεν βρέθηκε αρχείο άδειας, λήξη προσωρινής ή συνδρομητικής περιόδου, ή μη έγκυρος τομέας. Εξετάστε το IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — η αναφορά της σελίδας Licensing στο IDoconutLicenseService δείχνει ένα έτοιμο endpoint.

Τα παλαιά έγγραφα εμφανίζουν παραμορφωμένο κείμενο — οι κωδικοποιήσεις σελίδων κώδικα δεν φορτώνονται εξ ορισμού στο .NET 8. Προσθέστε μία φορά κατά την εκκίνηση:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Λάθος ή αντικατεστημένες γραμματοσειρές σε Linux/Docker — το κοντέινερ δεν διαθέτει τις γραμματοσειρές του εγγράφου. Κατευθύνετε το FontFolders (στο WordConfig/PptConfig) σε έναν προσαρτημένο φάκελο γραμματοσειρών.

Οι παρουσιάσεις ανοίγουν αλλά αποτυγχάνουν να αποδοθούν σε Linux/macOS — ο τρέχων renderer PPT/PPTX/PPS/POT/ODP απαιτεί το τοπικό libgdiplus συν System.Drawing.EnableUnixSupport=true. Το πακέτο παρέχει System.Drawing.Common 6.0.0 επειδή αυτή είναι η τελευταία έκδοση που σέβεται αυτήν τη ρύθμιση.

Η λειτουργία λειτουργούσε στην αξιολόγηση, αλλά είναι σιωπηλή στην παραγωγή

Η κλασική έκπληξη κατά την έναρξη: μια ενεργή προσωρινή άδεια χορηγεί κάθε δυνατότητα· η αγορασμένη άδεια χορηγεί μόνο ό,τι αγοράσατε. Τα πακέτα αναζήτησης και σχολιασμού μπορούν να εξαφανιστούν όταν λείπουν οι δυνατότητές τους. Τα καταχωρημένα πρόσθετα Converter ή DICOM με ανεπαρκή μη-προσωρινή άδεια αποτυγχάνουν κατά το AddDoconut(). Συγκρίνετε το IsCapabilityGranted(...) με κάθε δυνατότητα που ενεργοποιείτε πριν από την ανάπτυξη.

Η αναζήτηση δεν βρίσκει τίποτα (ή πολύ λίγα)

  • Για άμεσο PDF, το AllowSearch δεν ήταν ενεργοποιημένο κατά το άνοιγμα. Το Word, Excel και PowerPoint εκθέτουν την ίδια εναλλαγή μέσω του ενσωματωμένου PdfConfig.
  • Το περιεχόμενο είναι σαρωμένο/μόνο εικόνα, έτσι η κανονική Αναζήτηση δεν έχει στρώση κειμένου για αντιστοίχιση. Χρησιμοποιήστε μια πηγή με κείμενο ή μια προβολή PDF που διατηρεί το κείμενο.
  • Τα HTML και το MS Project (MPP) δεν είναι αναζητήσιμα από προεπιλογή — ορίστε DefaultRender = false ώστε να αποδίδονται μέσω μιας προβολής PDF με εγγενή στρώση κειμένου. Το Word, Excel, PowerPoint, TXT, Visio, email, EPUB και MHT αναζητούνται από τις προεπιλεγμένες ρυθμίσεις του καταλόγου τους.
  • Το objViewer.CanSearch() είναι false μετά την αρχικοποίηση — η μορφή που επιλύθηκε δεν έχει τυπική διαδρομή αναζήτησης. Αυτό το αποτέλεσμα είναι ξεχωριστό από την άδεια Search· επαληθεύστε και τα δύο.

Ακόμα κολλήσατε;

Απομονώστε το πρόβλημα στην ελάχιστη εφαρμογή Quick Start· αν επαναληφθεί εκεί, επικοινωνήστε με την υποστήριξη παρέχοντας το έγγραφο, το Program.cs σας και την έξοδο διάγνωσης άδειας.

Ήταν αυτή η σελίδα χρήσιμη;