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

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

Κάθε μήνυμα παρακάτω είναι το κυριολεκτικό κείμενο που παράγει το 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), ή η εφαρμογή επανεκκινήθηκε (νέα κλειδιά συνεδρίας). Αυτό είναι το επίπεδο ασφαλείας που λειτουργεί όπως σχεδιάστηκε — δείτε Βασικές Έννοιες → Συνεδρίες & Ασφάλεια.

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

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

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

Ο διακομιστής λειτουργεί σωστά αλλά η σελίδα συμπεριφέρεται λανθασμένα — χωρίς κανένα σφάλμα

Αυτές είναι οι μορφές αποτυχίας που πρέπει να υποψιάζεστε πρώτα μετά τη μεταφορά μιας εφαρμογής. Και οι τρεις αφήνουν τον διακομιστή να λειτουργεί τέλεια, αποδίδουν το έγγραφο σωστά και δεν αναφέρουν τίποτα στην κονσόλα του προγράμματος περιήγησης.

Ένα ενεργό spinner που δεν σταματά ποτέ. Τα callbacks του προβολέα δηλώνονται ως παγκόσμιες συναρτήσεις με όνομα το αναγνωριστικό του container — ctlDoc_OnViewerReady() και συναρτήσεις‑φίλοι. Ο προηγούμενος προβολέας έψαχνε αυτά τα ονόματα· αυτός δεν το κάνει. Ο χειριστής που θα έσκρυβε το spinner απλώς δεν εκτελείται ποτέ. Περάστε τις συναρτήσεις ως επιλογές αντί αυτού:

javascript
objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Το έγγραφο πίσω από το spinner είναι εντάξει. Η πλήρης λίστα επιλογών βρίσκεται στο ViewerConfig.

Λείπουν εικονίδια ή χρωματισμός του προβολέα, οι σελίδες είναι διαφορετικά σωστές. Το ResPath είναι κενό ή δείχνει στη ρίζα της εφαρμογής — σωστό στη προηγούμενη βιβλιοθήκη, λανθασμένο εδώ. Πρέπει να ορίζει το πρόθεμα που το UseDoconutResources() τοποθετεί:

javascript
ResPath: 'doconut-res/images'   // ή '<your ResourcesPath>/images'

Κατεστραμμένα πλακίδια για μεταγενέστερες σελίδες όταν εξυπηρετούνται από κοινόχρηστη αποθήκη. Σελίδες που εξακολουθούν να γράφονται απαντούν με 202 Accepted. Ένας πελάτης χωρίς retryOn409: true το αντιμετωπίζει ως αποτυχημένη εικόνα. Δείτε Distributed Deployments.

Το άνοιγμα ενός εγγράφου αποτυγχάνει

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

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

Το πακέτο δεν θα εγκατασταθεί καθόλου — Doconut.NETStandard 26.8.0 στοχεύει
netstandard2.1, έτσι το NuGet απορρίπτει ένα έργο .NET Framework. Αυτό δεν είναι
επιλυμένο σφάλμα αποκατάστασης: το .NET Framework δεν μπορεί να καταναλώσει netstandard2.1. Χρησιμοποιήστε το
πακέτο Doconut.NETFramework αντί αυτού.

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

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

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

Ένας τοίχος σφαλμάτων μεταγλώττισης αμέσως μετά την αναβάθμιση του πακέτου — αυτό είναι αναμενόμενο.
Το 26.8.0 έχει διαφορετική επιφάνεια API από το 26.7.0, δεν είναι συμβατή ενημέρωση. Τα περισσότερα
σφάλματα είναι οι γραμμές using που μεταφέρθηκαν στο ριζικό χώρο ονομάτων Doconut; προχωρήστε μέσω του
Μεταφορά σε .NET Standard 2.1 αντί να τα διορθώνετε ένα‑ένα.

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

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

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

Το αποτέλεσμα φαίνεται λανθασμένο

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

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

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

Οι παρουσιάσεις ανοίγουν αλλά αποτυγχάνουν να αποδοθούν σε Linux/macOS — ο τρέχων αποδότης 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 μετά την αρχικοποίηση — η μορφή που επιλύθηκε δεν έχει τυπική διαδρομή αναζήτησης. Αυτό το αποτέλεσμα είναι ξεχωριστό από την άδεια Αναζήτησης· ελέγξτε και τα δύο.

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

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

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