Rozwiązywanie problemów

Diagnozowanie typowych błędów

Każda poniższa wiadomość to dosłowny tekst generowany przez Doconut, uporządkowany 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 błędów 404 dla /doconut-res/...
UseDoconutResources() jest brakujące lub umieszczone po UseDoconut(). Musi być pierwsze w potoku.

HTTP 500 z:

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

Obrazek 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 przechowalni ciasteczek) lub aplikacja została ponownie uruchomiona (nowe klucze sesji). To warstwa bezpieczeństwa działa zgodnie z założeniami — zobacz Podstawowe koncepcje → Sesje i bezpieczeństwo.

Obrazek 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.

Niepowodzenie otwierania dokumentu

LicenseException z komunikatem odrzucenia — plik licencji został znaleziony, ale odrzucony (nieprawidłowy podpis, uszkodzony, na czarnej liście lub wersja kompilacji poza zakresem wersji/okna 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) i możliwość nie jest już przyznana. Zarejestruj wtyczkę i sprawdź lic.IsCapabilityGranted(LicenseCapability.Dicom). Brak lub niewystarczające nie‑tymczasowe uprawnienie zazwyczaj powoduje błąd wcześniej, 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 możesz dodać je za pomocą DoconutOptions.RegisterViewer.

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 zarejestrowania wtyczki Converter.

Niepowodzenie uruchamiania

InvalidOperationException wspominający wtyczkę zarejestrowaną przez AddPlugin — bieżąca nie‑tymczasowa licencja nie przyznaje tej możliwości wtyczki. Usuń rejestrację lub zainstaluj licencję, która ją przyznaje. Brak licencji oraz starszy plik TRIAL nie przyznają żadnych możliwości wtyczek.

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.

Walidacja opcji w trybie fail-fast — popraw nieprawidłową ścieżkę.

Błędy kompilacji / zależności

Błąd kompilacji CS1705 lub w czasie wykonywania przy otwieraniu dokumentu:

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

Twój projekt wymusił wersję System.Text.Json / System.Text.Encodings.Web poniżej 10.0.x. Usuń obniżenie wersji i pozwól NuGet przywrócić wersje zadeklarowane przez Doconut.NET8.

TypeInitializationException on the first presentation file:

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

Silnik prezentacji wymaga System.Drawing.Common w wersji 6.0.0 (zadeklarowanej przez pakiet). Nie usuwaj ani nie nadpisuj tej zależności — każde otwarcie PPT/PPTX/PPS/POT/ODP zakończy się niepowodzeniem bez niej.

Wyjście wygląda niepoprawnie

Strony zawierają znak wodny — aplikacja jest w stanie ewaluacyjnym: nie znaleziono pliku licencji, wygasło tymczasowe lub subskrypcyjne okno, lub nieprawidłowa domena. Sprawdź IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — odniesienie do IDoconutLicenseService na stronie Licensing 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 na Linux/Docker — kontener nie posiada czcionek dokumentu. Wskaż FontFolders (w WordConfig/PptConfig) na zamontowany katalog czcionek.

Prezentacje otwierają się, ale nie renderują na Linux/macOS — aktualny renderer PPT/PPTX/PPS/POT/ODP wymaga natywnego libgdiplus oraz System.Drawing.EnableUnixSupport=true. Pakiet dostarcza System.Drawing.Common 6.0.0, ponieważ jest to ostatnia wersja obsługująca ten przełącznik.

Funkcja działała w wersji ewaluacyjnej, milczy w produkcji

Klasyczna niespodzianka przy uruchomieniu: aktywna licencja tymczasowa przyznaje wszystkie możliwości; zakupiona licencja przyznaje tylko to, co zostało zakupione. Pakiety wyszukiwania i adnotacji mogą zniknąć, gdy ich możliwości są nieobecne. Zarejestrowane wtyczki Converter lub DICOM z niewystarczającą nie‑tymczasową licencją zawodzą podczas AddDoconut(). Porównaj IsCapabilityGranted(...) z każdą funkcją, którą włączasz przed wdrożeniem.

Wyszukiwanie nie znajduje nic (lub za mało)

  • Dla bezpośredniego PDF, AllowSearch nie został włączony w momencie otwierania. Word, Excel i PowerPoint udostępniają ten sam przełącznik poprzez ich zagnieżdżony PdfConfig.
  • Zawartość jest zeskanowana/tylko obraz, więc zwykłe wyszukiwanie 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 domyślnych ustawieniach — ustaw DefaultRender = false, aby renderowały się przez projekcję PDF z natywną warstwą tekstową. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB i MHT są przeszukiwane w swoich 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.

Wciąż utknąłeś?

Izoluj problem przy użyciu minimalnej aplikacji Quick Start; jeśli występuje tam, skontaktuj się z pomocą techniczną, przekazując dokument, swój Program.cs oraz wynik diagnostyki licencji.

Czy ta strona była pomocna?