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

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

Κάθε μήνυμα παρακάτω είναι το κυριολεκτικό κείμενο που παράγει το 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.

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

FormatNotSupportedException:

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

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

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

InvalidOperationException:

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

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

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

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

ArgumentException from 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 — διορθώστε τη λανθασμένη διαδρομή.

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

Compiler error CS1705, or at runtime when opening a document:

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

Το έργο σας έθεσε System.Text.Json ή System.Text.Encodings.Web σε έκδοση κάτω από τις εξαρτήσεις 8.0.x που δηλώνει το Doconut.NET6. Αφαιρέστε την υποβάθμιση και αφήστε το NuGet να επαναφέρει το γράφημα πακέτων (System.Text.Json 8.0.6 και System.Text.Encodings.Web 8.0.0 στο ελεγχόμενο πακέτο 26.7.0).

TypeInitializationException on the first presentation file:

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 6. Προσθέστε μία φορά κατά την εκκίνηση:

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 επειδή αυτή είναι η τελευταία έκδοση που σέβεται αυτήν τη ρύθμιση.

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

Η κλασική έκπληξη κατά τη μετάβαση σε παραγωγή: μια ενεργή προσωρινή άδεια χορηγεί κάθε δυνατότητα· η αγορασμένη άδεια χορηγεί μόνο ό,τι αγοράσατε. Τα πακέτα αναζήτησης και σχολιασμού μπορούν να εξαφανιστούν όταν λείπουν οι δυνατότητές τους. Τα καταχωρημένα plugins 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 σας και την έξοδο διαγνωστικών της άδειας.

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