Rozwiązywanie problemów
Diagnozowanie typowych błędów
Poniżej znajdują się dosłowne komunikaty generowane przez Doconut, uporządkowane według objawów. Znajdź swój błąd i zastosuj rozwiązanie.
Przeglądarka nie wyświetla nic
Pusty obszar przeglądarki, konsola przeglądarki pełna 404 dla /doconut-res/...
UseDoconutResources() jest brakujący lub umieszczony po UseDoconut(). Musi być pierwszy w potoku.
Przeglądarka zgłasza The viewer handler could not be reached (no response).
Żądanie nigdy nie otrzymało odpowiedzi. Częstą przyczyną jest BasePath, który zaczyna się od /: '/doconut' staje się //doconut/DocImage.axd, żądanie do innego hosta. Zapisz je bez początkowego ukośnika (BasePath: 'doconut').
Przeglądarka zgłasza Please make sure your middleware is configured.
Punkt końcowy strony odpowiedział 404: UseDoconut() nie jest zamontowany tam, gdzie wskazuje BasePath klienta. Przy app.Map("/doconut", branch => branch.UseDoconut()), klient używa BasePath: 'doconut'.
HTTP 500 z:
Session middleware not configured. Call UseSession() before UseDoconut().Bezpieczeństwo tokenów Doconut (włączone domyślnie) wymaga stanu sesji ASP.NET. Dodaj builder.Services.AddSession() i app.UseSession() przed gałęzią pośrednika Doconut. Stan sesji wymaga również pamięci podręcznej: w aplikacji minimal-API dodaj builder.Services.AddDistributedMemoryCache(), lub aplikacja zatrzyma się przy uruchamianiu z Unable to resolve service for type 'IDistributedCache' (aplikacje MVC i Razor Pages rejestrują już jedną).
Obraz błędu w obszarze strony z napisem:
You Are Not Authorized To View This Page.Token został otwarty w innej sesji przeglądarki. Typowe przyczyny: ciasteczko sesji nie dociera do żądań strony (konfiguracja cross-origin, polityka SameSite, klient API bez pojemnika na ciasteczka), lub aplikacja została ponownie uruchomiona (nowe klucze sesji). To warstwa bezpieczeństwa działająca zgodnie z przeznaczeniem — zobacz Podstawowe pojęcia → Sesje i bezpieczeństwo. Odrzucenie jest obrazem zwróconym ze statusem 200, więc monitor sprawdzający tylko kody statusu liczy go jako stronę.
Obraz błędu z napisem:
Document session not found. Please re-open document.Token wygasł (przesuwane okno, domyślnie 60 minut — DocOptions.TimeOut) lub sesja została zamknięta. Otwórz ponownie dokument, aby uzyskać nowy token.
Otwieranie dokumentu nie powiodło się
LicenseException z komunikatem odrzucenia — plik licencji został znaleziony, ale odrzucony (nieprawidłowy podpis, uszkodzony, na czarnej liście lub kompilacja poza oknem wersji/aktualizacji licencji). Ten stan blokuje otwieranie (fail-fast) zamiast degradacji do znaku wodnego; przeczytaj License.RejectionMessage, aby poznać przyczynę.
LicenseException:
This document type requires the 'Dicom' plugin license.Rozszerzenie jest obsługiwane wyłącznie przez wtyczkę (tutaj: DICOM). Wtyczka jest zarejestrowana, ale żadna licencja nie przyznaje już jej możliwości — zazwyczaj tymczasowa licencja, która wygasła po uruchomieniu aplikacji. Zainstaluj licencję, która to umożliwia i zweryfikuj IsCapabilityGranted(LicenseCapability.Dicom) na IDoconutLicenseService. Brak lub niewystarczające uprawnienie nie‑tymczasowe zwykle kończy się niepowodzeniem podczas AddDoconut().
FormatNotSupportedException:
Document format '<extension>' is not supported.Żaden podgląd — wbudowany, wtyczka ani niestandardowy — nie obsługuje tego rozszerzenia. Sprawdź listę obsługiwanych formatów; dla własnych formatów DoconutOptions.RegisterViewer może dodać jeden.
InvalidDataException — zawartość pliku jest uszkodzona lub nie pasuje do jego rozszerzenia (np. plik został przemianowany). Zweryfikuj przesyłane pliki przed otwarciem.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().Rozwiązałeś DocumentConverter bez rejestracji wtyczki Converter.
Błędy uruchomienia
InvalidOperationException mentioning a plugin registered via AddPlugin — aktualna licencja niebędąca tymczasową nie przyznaje tej funkcji wtyczki. Usuń rejestrację lub zainstaluj licencję, która to umożliwia. Brak licencji oraz starszy plik TRIAL nie przyznają żadnych możliwości wtyczki.
ArgumentException z AddDoconut():
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.Walidacja opcji fail-fast — napraw nieprawidłową ścieżkę.
Błędy kompilacji / zależności
Błąd kompilatora CS1705, lub w czasie wykonywania przy otwieraniu dokumentu:
Could not load file or assembly 'System.Text.Json, Version=8.0.0.0'Twój projekt zablokował System.Text.Json lub System.Text.Encodings.Web poniżej zależności 8.0.x zadeklarowanych przez Doconut.NET8. Usuń downgrade i pozwól NuGet przywrócić graf pakietów (System.Text.Json 8.0.5 i System.Text.Encodings.Web 8.0.0).
Nieprawidłowy wygląd wyjścia
Strony zawierają znak wodny — aplikacja jest w stanie ewaluacyjnym: nie znaleziono pliku licencji, wygasła tymczasowa licencja lub nieprawidłowa domena. Przy aktywnej tymczasowej licencji tylko wyjście wtyczki jest znakowane. Kompilacja wydana po dacie subskrypcji płatnej licencji nie ma znaku wodnego: otwarcie zgłasza LicenseException. Sprawdź IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — odwołanie IDoconutLicenseService na stronie Licencjonowania pokazuje gotowy punkt końcowy.
Starsze dokumenty wyświetlają zniekształcony tekst — kodowanie stron kodowych nie jest ładowane domyślnie w .NET 8. Dodaj raz przy uruchamianiu:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Nieprawidłowe lub zastąpione czcionki — serwer nie ma czcionek dokumentu. Zainstaluj je lub skieruj FontFolders (na WordConfig/PptConfig) do folderu, który je zawiera. Na Linuxie, zobacz poniżej.
Adnotacja obrazu wyświetla się w przeglądarce, ale eksport ma pole „Image blocked” — host obrazu ma prywatny lub adres loopback, który serwer odrzuca. Zobacz Adnotacje.
Linux
Otwieranie dowolnego dokumentu kończy się błędem:
The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.Zainstaluj bibliotekę konfiguracji czcionek: apt-get install -y libfontconfig1 (fontconfig na RHEL/Fedora). Zobacz Instalacja.
Otwieranie dowolnego dokumentu kończy się błędem:
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.Aplikacja odwołuje się do nowszej wersji SkiaSharp, bezpośrednio lub przez inną bibliotekę. Dodaj SkiaSharp.NativeAssets.Linux w tej samej wersji co ten SkiaSharp.
Otwieranie dowolnego dokumentu kończy się błędem:
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.Host nie jest obsługiwaną platformą. Dystrybucje Alpine i inne oparte na musl nie są wspierane: użyj obrazu opartego na Debianie lub Ubuntu.
Tekst jest szerszy lub węższy niż w systemie Windows, lub linie łamią się inaczej — czcionki dokumentu nie są zainstalowane, więc Doconut używa najbliższej dostępnej czcionki. Zainstaluj czcionki kompatybilne metrycznie (fonts-liberation dla Arial, Times New Roman i Courier New; fonts-crosextra-carlito i fonts-crosextra-caladea dla Calibri i Cambria), lub skopiuj własne licencjonowane czcionki do /usr/share/fonts/ i uruchom fc-cache -f. Azjatycki tekst wyświetlany jako puste pola wymaga fonts-noto-cjk.
Funkcja działała w wersji testowej, cicha w produkcji
Klasyczna niespodzianka przy uruchomieniu: aktywna Temporary licencja przyznaje wszystkie możliwości; Twoja zakupiona licencja przyznaje tylko to, co kupiłeś. Pakiety wyszukiwania i adnotacji mogą zniknąć, gdy ich możliwości są nieobecne. Zarejestrowany Converter lub wtyczki DICOM z niewystarczającą nie‑temporary licencją zawodzą podczas AddDoconut(). Porównaj IsCapabilityGranted(...) ze wszystkimi funkcjami, które włączasz przed wdrożeniem.
Wyszukiwanie nie znajduje nic (lub zbyt mało)
- Dla bezpośredniego PDF,
AllowSearchnie był włączony w momencie otwarcia. Word, Excel i PowerPoint udostępniają ten sam przełącznik poprzez ich zagnieżdżonePdfConfig. - Treść jest skanowana/tylko obraz, więc standardowe Search nie ma warstwy tekstowej do dopasowania. Użyj źródła zawierającego tekst lub projekcji PDF zachowującej tekst.
- HTML i MS Project (MPP) nie są przeszukiwalne w ustawieniach domyślnych — ustaw
DefaultRender = false, aby renderowały się poprzez projekcję PDF z natywną warstwą tekstową. Word, Excel, PowerPoint, TXT, Visio, email, EPUB i MHT są przeszukiwane w domyślnych ustawieniach katalogu. objViewer.CanSearch()jestfalsepo inicjalizacji — rozpoznany format nie ma standardowej ścieżki wyszukiwania. Ten werdykt jest oddzielny od licencji Search; zweryfikuj oba.- Strona odczytuje wartość zwracaną przez
objViewer.Search(...)— liczba przychodzi w trzecim argumencie, jako callback.
Nadal utknąłeś?
Izoluj problem przy użyciu minimalnej aplikacji Quick Start; jeśli tam się odtworzy, skontaktuj się z pomocą techniczną, podając dokument, Twój Program.cs oraz wyjście diagnostyki licencji.
Czy ta strona była pomocna?