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

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

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

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

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

Ο προβολέας αναφέρει The viewer handler could not be reached (no response).
Η αίτηση δεν έλαβε ποτέ απάντηση. Ένα κοινό αίτιο είναι ένα BasePath που ξεκινά με /: το '/doconut' γίνεται //doconut/DocImage.axd, μια αίτηση σε άλλο κεντρικό υπολογιστή. Γράψτε το χωρίς την αρχική κάθετο (BasePath: 'doconut').

Ο προβολέας αναφέρει Please make sure your middleware is configured.
Το σημείο λήξης της σελίδας απάντησε 404: το UseDoconut() δεν είναι προσαρτημένο εκεί που δείχνει το BasePath του πελάτη. Με app.Map("/doconut", branch => branch.UseDoconut()), ο πελάτης χρησιμοποιεί BasePath: 'doconut'.

HTTP 500 με:

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

Η ασφάλεια token του Doconut (ενεργοποιημένη εξ ορισμού) χρειάζεται κατάσταση συνεδρίας ASP.NET. Προσθέστε builder.Services.AddSession() και app.UseSession() πριν από το κλαδί του middleware 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), ή η εφαρμογή επανεκκινήθηκε (νέα κλειδιά συνεδρίας). Αυτό είναι το επίπεδο ασφαλείας που λειτουργεί όπως σχεδιάστηκε — δείτε Core Concepts → Sessions & Security. Η άρνηση είναι μια εικόνα που σερβίρεται με κατάσταση 200, έτσι ένας παρατηρητής που ελέγχει μόνο κωδικούς κατάστασης το μετρά ως σελίδα.

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

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). Το πρόσθετο είναι καταχωρημένο, αλλά καμία άδεια δεν χορηγεί πλέον τη δυνατότητά του — συνήθως μια Προσωρινή άδεια που έληξε μετά την εκκίνηση της εφαρμογής. Εγκαταστήστε μια άδεια που το χορηγεί και επαληθεύστε IsCapabilityGranted(LicenseCapability.Dicom) στο IDoconutLicenseService. Μια ελλιπής ή ανεπαρκής μη προσωρινή ενδυνάμωση συνήθως αποτυγχάνει νωρίτερα, κατά τη διάρκεια του 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 mentioning a plugin registered via 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.

Επικύρωση επιλογών γρήγορης αποτυχίας — διορθώστε τη λανθασμένη διαδρομή.

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

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

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

Το έργο σας έδωσε pin στα 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 όπως δηλώνεται από το πακέτο).

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

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

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Λάθος ή αντικατεστημένες γραμματοσειρές — ο διακομιστής δεν διαθέτει τις γραμματοσειρές του εγγράφου. Εγκαταστήστε τις ή κατευθύνετε το FontFolders (στο WordConfig/PptConfig) σε φάκελο που τις περιέχει. Σε Linux, δείτε παρακάτω.

Μια σημείωση εικόνας εμφανίζεται στον προβολέα, αλλά η εξαγωγή έχει ένα πλαίσιο «Image blocked» — ο κεντρικός υπολογιστής της εικόνας έχει ιδιωτική ή διεύθυνση loopback, την οποία ο διακομιστής αρνείται να ανακτήσει. Δείτε Annotations.

Linux

Το άνοιγμα οποιουδήποτε εγγράφου αποτυγχάνει με:

text
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.

Εγκαταστήστε τη βιβλιοθήκη ρυθμίσεων γραμματοσειρών: apt-get install -y libfontconfig1 (fontconfig σε RHEL/Fedora). Δείτε Installation.

Το άνοιγμα οποιουδήποτε εγγράφου αποτυγχάνει με:

text
The application uses a newer SkiaSharp than Doconut's native graphics library. Add the package SkiaSharp.NativeAssets.Linux at the same version as the application's SkiaSharp; see the Linux section of the Doconut documentation.

Η εφαρμογή αναφέρεται σε πιο πρόσφατο SkiaSharp, άμεσα ή μέσω άλλης βιβλιοθήκης. Προσθέστε το SkiaSharp.NativeAssets.Linux στην ίδια έκδοση με αυτό το SkiaSharp.

Το άνοιγμα οποιουδήποτε εγγράφου αποτυγχάνει με:

text
The native graphics library for this platform was not found next to the application. Doconut supports Windows x64/x86 and glibc-based Linux x64 (Alpine/musl is not supported); see the Linux section of the Doconut documentation.

Ο κεντρικός υπολογιστής δεν είναι υποστηριζόμενη πλατφόρμα. Οι διανομές Alpine και άλλες βασισμένες σε musl δεν υποστηρίζονται: χρησιμοποιήστε μια εικόνα βασισμένη σε Debian ή Ubuntu.

Το κείμενο είναι πιο φαρδύ ή πιο στενό από τα Windows, ή οι γραμμές σπάζουν διαφορετικά — οι γραμματοσειρές του εγγράφου δεν είναι εγκατεστημένες, έτσι το Doconut χρησιμοποιεί τη πιο κοντινή εγκατεστημένη γραμματοσειρά. Εγκαταστήστε γραμματοσειρές συμβατές με μετρική (fonts-liberation για Arial, Times New Roman και Courier New· fonts-crosextra-carlito και fonts-crosextra-caladea για Calibri και Cambria), ή αντιγράψτε τις δικές σας αδειοδοτημένες γραμματοσειρές στο /usr/share/fonts/ και εκτελέστε fc-cache -f. Το ασιατικό κείμενο που εμφανίζεται ως κενά κουτιά χρειάζεται fonts-noto-cjk.

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

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

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

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

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