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:

text
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:

text
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:

text
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:

text
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:

text
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:

text
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():

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.

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:

text
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:

csharp
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:

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.

Zainstaluj bibliotekę konfiguracji czcionek: apt-get install -y libfontconfig1 (fontconfig na RHEL/Fedora). Zobacz Instalacja.

Otwieranie dowolnego dokumentu kończy się błędem:

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.

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:

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.

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, AllowSearch nie był włączony w momencie otwarcia. Word, Excel i PowerPoint udostępniają ten sam przełącznik poprzez ich zagnieżdżone PdfConfig.
  • 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() jest false po 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?