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.

Podgląd nie wyświetla nic

Pusty obszar podglądu, 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().

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.

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 pojemnika na ciasteczka) lub aplikacja została zrestartowana (nowe klucze sesji). To warstwa bezpieczeństwa działająca zgodnie z projektem — zobacz Podstawowe pojęcia → 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.

Otwieranie dokumentu nie powodzi się

LicenseException z komunikatem odrzucenia — plik licencji został znaleziony, ale odrzucony (nieprawidłowy podpis, uszkodzony, na czarnej liście lub wersja kompilacji poza oknem wersji/aktualizacji licencji). Ten stan blokuje otwieranie (szybkie niepowodzenie) zamiast przejścia do znaku wodnego; przeczytaj License.RejectionMessage, aby poznać przyczynę.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

Rozszerzenie obsługiwane jest 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 zwykle 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 odpowiada jego rozszerzeniu (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.

Uruchamianie nie powodzi się

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 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 z szybkim niepowodzeniem — 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 wymusił wersję System.Text.Json lub System.Text.Encodings.Web niższą niż zależności 8.0.x zadeklarowane przez Doconut.NET6. Usuń downgrade i pozwól NuGet przywrócić graf pakietów (System.Text.Json 8.0.6 i System.Text.Encodings.Web 8.0.0 w pakiecie audited 26.7.0).

TypeInitializationException przy pierwszym pliku prezentacji:

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

Silnik prezentacji wymaga System.Drawing.Common w wersji 6.0.0 (zadeklarowanej w pakiecie). 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) — odwołanie 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 6. Dodaj raz przy starcie:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Nieprawidłowe lub zastąpione czcionki na Linux/Docker — kontener nie posiada czcionek dokumentu. Skieruj FontFolders (w WordConfig/PptConfig) na zamontowany katalog czcionek.

Prezentacje otwierają się, ale nie renderują na Linux/macOS — bieżący 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 znajduje za mało)

  • Dla bezpośredniego PDF, AllowSearch nie był włączony w momencie otwarcia. Word, Excel i PowerPoint udostępniają ten sam przełącznik w ich zagnieżdżonym PdfConfig.
  • Zawartość jest zeskanowana/tylko obraz, więc standardowe 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 ustawieniach domyślnych — ustaw DefaultRender = false, aby renderowały się przez projekcję PDF z natywną warstwą tekstową. Word, Excel, PowerPoint, TXT, Visio, email, EPUB i MHT są przeszukiwane w ich domyślnych ustawieniach katalogu.
  • objViewer.CanSearch() zwraca false po inicjalizacji — rozpoznany format nie ma standardowej ścieżki wyszukiwania. Ten werdykt jest oddzielny od licencji Search; zweryfikuj oba.

Nadal utknąłeś?

Izoluj problem przy użyciu minimalnej aplikacji Szybki start; jeśli występuje tam, skontaktuj się z pomocą techniczną, podając dokument, swój Program.cs oraz wyjście diagnostyczne licencji.

Czy ta strona była pomocna?